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 */
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 */
79static 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 */
108int 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 */
154static 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 */
172int 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 */
216char *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 */
248int 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
261InspectionBuffer *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 (!SCQuicTxGetJa3(txv, STREAM_TOSERVER | STREAM_TOCLIENT, &b, &b_len))
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(det_ctx, buffer, transforms);
282 }
283 return buffer;
284}
285
286InspectionBuffer *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 (!SCQuicTxGetJa3(txv, STREAM_TOSERVER | STREAM_TOCLIENT, &b, &b_len))
296 return NULL;
297 if (b == NULL || b_len == 0)
298 return NULL;
299
300 InspectionBufferSetupAndApplyTransforms(det_ctx, list_id, buffer, b, b_len, transforms);
301 }
302 return buffer;
303}
304
305#else /* HAVE_JA3 */
306
307/* Stubs for when JA3 is disabled */
308
310{
311 return 0;
312}
313
314int Ja3BufferAddValue(JA3Buffer **buffer, uint32_t value)
315{
316 return 0;
317}
318
320{
321 return NULL;
322}
323
324int Ja3IsDisabled(const char *type)
325{
326 return true;
327}
328
329#endif /* HAVE_JA3 */
uint8_t len
bool SSLJA3IsEnabled(void)
return whether ja3 is effectively enabled
uint16_t type
void InspectionBufferCopy(InspectionBuffer *buffer, uint8_t *buf, uint32_t buf_len)
void InspectionBufferApplyTransforms(DetectEngineThreadCtx *det_ctx, InspectionBuffer *buffer, const DetectEngineTransforms *transforms)
void InspectionBufferSetupAndApplyTransforms(DetectEngineThreadCtx *det_ctx, const int list_id, InspectionBuffer *buffer, const uint8_t *data, const uint32_t data_len, const DetectEngineTransforms *transforms)
setup the buffer with our initial data
InspectionBuffer * InspectionBufferGet(DetectEngineThreadCtx *det_ctx, const int list_id)
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
Flow data structure.
Definition flow.h:356
uint32_t used
Definition util-ja3.h:34
uint32_t size
Definition util-ja3.h:33
char * data
Definition util-ja3.h:32
#define SCLogWarning(...)
Macro used to log WARNING messages.
Definition util-debug.h:255
#define SCLogError(...)
Macro used to log ERROR messages.
Definition util-debug.h:267
JA3Buffer * Ja3BufferInit(void)
Allocate new buffer.
Definition util-ja3.c:39
int Ja3BufferAddValue(JA3Buffer **buffer, uint32_t value)
Definition util-ja3.c:314
int Ja3BufferAppendBuffer(JA3Buffer **buffer1, JA3Buffer **buffer2)
Definition util-ja3.c:309
int Ja3IsDisabled(const char *type)
Definition util-ja3.c:324
char * Ja3GenerateHash(JA3Buffer *buffer)
Definition util-ja3.c:319
void Ja3BufferFree(JA3Buffer **buffer)
Free allocated buffer.
Definition util-ja3.c:54
#define JA3_BUFFER_INITIAL_SIZE
Definition util-ja3.h:27
#define SCMalloc(sz)
Definition util-mem.h:47
#define SCFree(p)
Definition util-mem.h:61
#define SCRealloc(ptr, sz)
Definition util-mem.h:50
#define SCCalloc(nm, sz)
Definition util-mem.h:53
#define DEBUG_VALIDATE_BUG_ON(exp)