suricata
util-ja3.c
Go to the documentation of this file.
1 /* Copyright (C) 2007-2017 Open Information Security Foundation
2  *
3  * You can copy, redistribute or modify this Program under the terms of
4  * the GNU General Public License version 2 as published by the Free
5  * Software Foundation.
6  *
7  * This program is distributed in the hope that it will be useful,
8  * but WITHOUT ANY WARRANTY; without even the implied warranty of
9  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
10  * GNU General Public License for more details.
11  *
12  * You should have received a copy of the GNU General Public License
13  * version 2 along with this program; if not, write to the Free Software
14  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
15  * 02110-1301, USA.
16  */
17 
18 /**
19  * \file
20  *
21  * \author Mats Klepsland <mats.klepsland@gmail.com>
22  *
23  * Functions used to generate JA3 fingerprint.
24  */
25 
26 #include "suricata-common.h"
27 #include "app-layer-ssl.h"
28 #include "util-validate.h"
29 #include "util-ja3.h"
30 
31 #include "detect-engine.h"
32 
33 /**
34  * \brief Allocate new buffer.
35  *
36  * \return pointer to buffer on success.
37  * \return NULL on failure.
38  */
40 {
41  JA3Buffer *buffer = SCCalloc(1, sizeof(JA3Buffer));
42  if (buffer == NULL) {
43  return NULL;
44  }
45 
46  return buffer;
47 }
48 
49 /**
50  * \brief Free allocated buffer.
51  *
52  * \param buffer The buffer to free.
53  */
54 void Ja3BufferFree(JA3Buffer **buffer)
55 {
56  DEBUG_VALIDATE_BUG_ON(*buffer == NULL);
57 
58  if ((*buffer)->data != NULL) {
59  SCFree((*buffer)->data);
60  (*buffer)->data = NULL;
61  }
62 
63  SCFree(*buffer);
64  *buffer = NULL;
65 }
66 
67 #ifdef HAVE_JA3
68 
69 /**
70  * \internal
71  * \brief Resize buffer if it is full.
72  *
73  * \param buffer The buffer.
74  * \param len The length of the data that should fit into the buffer.
75  *
76  * \retval 0 on success.
77  * \retval -1 on failure.
78  */
79 static int Ja3BufferResizeIfFull(JA3Buffer *buffer, uint32_t len)
80 {
81  DEBUG_VALIDATE_BUG_ON(buffer == NULL);
82 
83  while (buffer->used + len + 2 > buffer->size)
84  {
85  buffer->size *= 2;
86  char *tmp = SCRealloc(buffer->data, buffer->size);
87  if (tmp == NULL) {
88  SCLogError("Error resizing JA3 buffer");
89  return -1;
90  }
91  buffer->data = tmp;
92  }
93 
94  return 0;
95 }
96 
97 /**
98  * \brief Append buffer to buffer.
99  *
100  * Append the second buffer to the first and then free it.
101  *
102  * \param buffer1 The first buffer.
103  * \param buffer2 The second buffer.
104  *
105  * \retval 0 on success.
106  * \retval -1 on failure.
107  */
108 int Ja3BufferAppendBuffer(JA3Buffer **buffer1, JA3Buffer **buffer2)
109 {
110  if (*buffer1 == NULL || *buffer2 == NULL) {
111  SCLogError("Buffers should not be NULL");
112  return -1;
113  }
114 
115  /* If buffer1 contains no data, then we just copy the second buffer
116  instead of appending its data. */
117  if ((*buffer1)->data == NULL) {
118  (*buffer1)->data = (*buffer2)->data;
119  (*buffer1)->used = (*buffer2)->used;
120  (*buffer1)->size = (*buffer2)->size;
121  SCFree(*buffer2);
122  return 0;
123  }
124 
125  int rc = Ja3BufferResizeIfFull(*buffer1, (*buffer2)->used);
126  if (rc != 0) {
127  Ja3BufferFree(buffer1);
128  Ja3BufferFree(buffer2);
129  return -1;
130  }
131 
132  if ((*buffer2)->used == 0) {
133  (*buffer1)->used += snprintf((*buffer1)->data + (*buffer1)->used,
134  (*buffer1)->size - (*buffer1)->used, ",");
135  } else {
136  (*buffer1)->used += snprintf((*buffer1)->data + (*buffer1)->used,
137  (*buffer1)->size - (*buffer1)->used, ",%s",
138  (*buffer2)->data);
139  }
140 
141  Ja3BufferFree(buffer2);
142 
143  return 0;
144 }
145 
146 /**
147  * \internal
148  * \brief Return number of digits in number.
149  *
150  * \param num The number.
151  *
152  * \return digits Number of digits.
153  */
154 static uint32_t NumberOfDigits(uint32_t num)
155 {
156  if (num < 10) {
157  return 1;
158  }
159 
160  return 1 + NumberOfDigits(num / 10);
161 }
162 
163 /**
164  * \brief Add value to buffer.
165  *
166  * \param buffer The buffer.
167  * \param value The value.
168  *
169  * \retval 0 on success.
170  * \retval -1 on failure.
171  */
172 int Ja3BufferAddValue(JA3Buffer **buffer, uint32_t value)
173 {
174  if (*buffer == NULL) {
175  SCLogError("Buffer should not be NULL");
176  return -1;
177  }
178 
179  if ((*buffer)->data == NULL) {
180  (*buffer)->data = SCMalloc(JA3_BUFFER_INITIAL_SIZE);
181  if ((*buffer)->data == NULL) {
182  SCLogError("Error allocating memory for JA3 data");
183  Ja3BufferFree(buffer);
184  return -1;
185  }
186  (*buffer)->size = JA3_BUFFER_INITIAL_SIZE;
187  }
188 
189  uint32_t value_len = NumberOfDigits(value);
190 
191  int rc = Ja3BufferResizeIfFull(*buffer, value_len);
192  if (rc != 0) {
193  Ja3BufferFree(buffer);
194  return -1;
195  }
196 
197  if ((*buffer)->used == 0) {
198  (*buffer)->used += snprintf((*buffer)->data, (*buffer)->size, "%u", value);
199  }
200  else {
201  (*buffer)->used += snprintf(
202  (*buffer)->data + (*buffer)->used, (*buffer)->size - (*buffer)->used, "-%u", value);
203  }
204 
205  return 0;
206 }
207 
208 /**
209  * \brief Generate Ja3 hash string.
210  *
211  * \param buffer The Ja3 buffer.
212  *
213  * \retval pointer to hash string on success.
214  * \retval NULL on failure.
215  */
216 char *Ja3GenerateHash(JA3Buffer *buffer)
217 {
218  if (buffer == NULL) {
219  SCLogError("Buffer should not be NULL");
220  return NULL;
221  }
222 
223  if (buffer->data == NULL) {
224  SCLogError("Buffer data should not be NULL");
225  return NULL;
226  }
227 
228  char *ja3_hash = SCMalloc(SC_MD5_HEX_LEN + 1);
229  if (ja3_hash == NULL) {
230  SCLogError("Error allocating memory for JA3 hash");
231  return NULL;
232  }
233 
234  SCMd5HashBufferToHex((unsigned char *)buffer->data, buffer->used, ja3_hash, SC_MD5_HEX_LEN + 1);
235  return ja3_hash;
236 }
237 
238 /**
239  * \brief Check if JA3 is disabled.
240  *
241  * Issue warning if JA3 is disabled or if we are lacking support for JA3.
242  *
243  * \param type Type to add to warning.
244  *
245  * \retval 1 if disabled.
246  * \retval 0 otherwise.
247  */
248 int Ja3IsDisabled(const char *type)
249 {
250  bool is_enabled = SSLJA3IsEnabled();
251  if (is_enabled == 0) {
252  if (strcmp(type, "rule") != 0) {
253  SCLogWarning("JA3 is disabled, skipping %s", type);
254  }
255  return 1;
256  }
257 
258  return 0;
259 }
260 
261 InspectionBuffer *Ja3DetectGetHash(DetectEngineThreadCtx *det_ctx,
262  const DetectEngineTransforms *transforms, Flow *_f, const uint8_t _flow_flags, void *txv,
263  const int list_id)
264 {
265  InspectionBuffer *buffer = InspectionBufferGet(det_ctx, list_id);
266  if (buffer->inspect == NULL) {
267  uint32_t b_len = 0;
268  const uint8_t *b = NULL;
269 
270  if (rs_quic_tx_get_ja3(txv, &b, &b_len) != 1)
271  return NULL;
272  if (b == NULL || b_len == 0)
273  return NULL;
274 
275  uint8_t ja3_hash[SC_MD5_HEX_LEN + 1];
276  // this adds a final zero
277  SCMd5HashBufferToHex(b, b_len, (char *)ja3_hash, SC_MD5_HEX_LEN + 1);
278 
279  InspectionBufferSetup(det_ctx, list_id, buffer, NULL, 0);
280  InspectionBufferCopy(buffer, ja3_hash, SC_MD5_HEX_LEN);
281  InspectionBufferApplyTransforms(buffer, transforms);
282  }
283  return buffer;
284 }
285 
286 InspectionBuffer *Ja3DetectGetString(DetectEngineThreadCtx *det_ctx,
287  const DetectEngineTransforms *transforms, Flow *_f, const uint8_t _flow_flags, void *txv,
288  const int list_id)
289 {
290  InspectionBuffer *buffer = InspectionBufferGet(det_ctx, list_id);
291  if (buffer->inspect == NULL) {
292  uint32_t b_len = 0;
293  const uint8_t *b = NULL;
294 
295  if (rs_quic_tx_get_ja3(txv, &b, &b_len) != 1)
296  return NULL;
297  if (b == NULL || b_len == 0)
298  return NULL;
299 
300  InspectionBufferSetup(det_ctx, list_id, buffer, b, b_len);
301  InspectionBufferApplyTransforms(buffer, transforms);
302  }
303  return buffer;
304 }
305 
306 #else /* HAVE_JA3 */
307 
308 /* Stubs for when JA3 is disabled */
309 
310 int Ja3BufferAppendBuffer(JA3Buffer **buffer1, JA3Buffer **buffer2)
311 {
312  return 0;
313 }
314 
315 int Ja3BufferAddValue(JA3Buffer **buffer, uint32_t value)
316 {
317  return 0;
318 }
319 
321 {
322  return NULL;
323 }
324 
325 int Ja3IsDisabled(const char *type)
326 {
327  return true;
328 }
329 
330 #endif /* HAVE_JA3 */
len
uint8_t len
Definition: app-layer-dnp3.h:2
detect-engine.h
JA3Buffer_
Definition: util-ja3.h:31
DetectEngineTransforms
Definition: detect.h:409
JA3Buffer_::size
size_t size
Definition: util-ja3.h:33
InspectionBuffer
Definition: detect.h:374
Flow_
Flow data structure.
Definition: flow.h:356
Ja3BufferAddValue
int Ja3BufferAddValue(JA3Buffer **buffer, uint32_t value)
Definition: util-ja3.c:315
JA3Buffer_::data
char * data
Definition: util-ja3.h:32
util-ja3.h
InspectionBufferGet
InspectionBuffer * InspectionBufferGet(DetectEngineThreadCtx *det_ctx, const int list_id)
Definition: detect-engine.c:1494
JA3_BUFFER_INITIAL_SIZE
#define JA3_BUFFER_INITIAL_SIZE
Definition: util-ja3.h:27
Ja3IsDisabled
int Ja3IsDisabled(const char *type)
Definition: util-ja3.c:325
JA3Buffer_::used
size_t used
Definition: util-ja3.h:34
Ja3BufferInit
JA3Buffer * Ja3BufferInit(void)
Allocate new buffer.
Definition: util-ja3.c:39
Ja3BufferFree
void Ja3BufferFree(JA3Buffer **buffer)
Free allocated buffer.
Definition: util-ja3.c:54
SSLJA3IsEnabled
bool SSLJA3IsEnabled(void)
return whether ja3 is effectively enabled
Definition: app-layer-ssl.c:3376
DetectEngineThreadCtx_
Definition: detect.h:1104
Ja3BufferAppendBuffer
int Ja3BufferAppendBuffer(JA3Buffer **buffer1, JA3Buffer **buffer2)
Definition: util-ja3.c:310
SCLogWarning
#define SCLogWarning(...)
Macro used to log WARNING messages.
Definition: util-debug.h:249
type
uint16_t type
Definition: decode-vlan.c:107
SCRealloc
#define SCRealloc(ptr, sz)
Definition: util-mem.h:50
InspectionBufferCopy
void InspectionBufferCopy(InspectionBuffer *buffer, uint8_t *buf, uint32_t buf_len)
Definition: detect-engine.c:1637
suricata-common.h
Ja3GenerateHash
char * Ja3GenerateHash(JA3Buffer *buffer)
Definition: util-ja3.c:320
InspectionBufferApplyTransforms
void InspectionBufferApplyTransforms(InspectionBuffer *buffer, const DetectEngineTransforms *transforms)
Definition: detect-engine.c:1693
util-validate.h
SCMalloc
#define SCMalloc(sz)
Definition: util-mem.h:47
InspectionBuffer::inspect
const uint8_t * inspect
Definition: detect.h:375
SCLogError
#define SCLogError(...)
Macro used to log ERROR messages.
Definition: util-debug.h:261
InspectionBufferSetup
void InspectionBufferSetup(DetectEngineThreadCtx *det_ctx, const int list_id, InspectionBuffer *buffer, const uint8_t *data, const uint32_t data_len)
setup the buffer with our initial data
Definition: detect-engine.c:1589
SCFree
#define SCFree(p)
Definition: util-mem.h:61
SCCalloc
#define SCCalloc(nm, sz)
Definition: util-mem.h:53
DEBUG_VALIDATE_BUG_ON
#define DEBUG_VALIDATE_BUG_ON(exp)
Definition: util-validate.h:102
app-layer-ssl.h