suricata
util-byte.h
Go to the documentation of this file.
1 /* Copyright (C) 2007-2022 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 Brian Rectanus <brectanu@gmail.com>
22  */
23 
24 #ifndef __UTIL_BYTE_H__
25 #define __UTIL_BYTE_H__
26 
27 #include <stdint.h>
28 
29 #define BYTE_BIG_ENDIAN 0
30 #define BYTE_LITTLE_ENDIAN 1
31 
32 /** Wrappers for OS dependent byte swapping functions */
33 #ifdef OS_FREEBSD
34 #include <sys/endian.h>
35 #define SCByteSwap16(x) bswap16(x)
36 #define SCByteSwap32(x) bswap32(x)
37 #define SCByteSwap64(x) bswap64(x)
38 #elif defined __OpenBSD__
39 #include <sys/types.h>
40 #define SCByteSwap16(x) swap16(x)
41 #define SCByteSwap32(x) swap32(x)
42 #define SCByteSwap64(x) swap64(x)
43 #elif OS_DARWIN
44 #include <libkern/OSByteOrder.h>
45 #define SCByteSwap16(x) OSSwapInt16(x)
46 #define SCByteSwap32(x) OSSwapInt32(x)
47 #define SCByteSwap64(x) OSSwapInt64(x)
48 #elif defined(__WIN32) || defined(_WIN32) || defined(sun)
49 /* Quick & dirty solution, nothing seems to exist for this in Win32 API */
50 #define SCByteSwap16(x) \
51  ((((x) & 0xff00) >> 8) \
52  | (((x) & 0x00ff) << 8))
53 #define SCByteSwap32(x) \
54  ((((x) & 0xff000000) >> 24) \
55  | (((x) & 0x00ff0000) >> 8) \
56  | (((x) & 0x0000ff00) << 8) \
57  | (((x) & 0x000000ff) << 24))
58 #define SCByteSwap64(x) \
59  ((((x) & 0xff00000000000000ull) >> 56) \
60  | (((x) & 0x00ff000000000000ull) >> 40) \
61  | (((x) & 0x0000ff0000000000ull) >> 24) \
62  | (((x) & 0x000000ff00000000ull) >> 8) \
63  | (((x) & 0x00000000ff000000ull) << 8) \
64  | (((x) & 0x0000000000ff0000ull) << 24) \
65  | (((x) & 0x000000000000ff00ull) << 40) \
66  | (((x) & 0x00000000000000ffull) << 56))
67 #else
68 #include <byteswap.h>
69 #define SCByteSwap16(x) bswap_16(x)
70 #define SCByteSwap32(x) bswap_32(x)
71 #define SCByteSwap64(x) bswap_64(x)
72 #endif /* OS_FREEBSD */
73 
74 /** \brief Turn byte array into string.
75  *
76  * All non-printables are copied over, except for '\0', which is
77  * turned into literal \0 in the string.
78  *
79  * \param bytes byte array
80  * \param nbytes number of bytes
81  * \return string nul-terminated string or NULL on error
82  */
83 char *BytesToString(const uint8_t *bytes, size_t nbytes);
84 void BytesToStringBuffer(const uint8_t *bytes, size_t nbytes, char *outstr, size_t outlen);
85 
86 /**
87  * Extract bytes from a byte string and convert to a unint64_t.
88  *
89  * \param res Stores result
90  * \param e Endianness (BYTE_BIG_ENDIAN or BYTE_LITTLE_ENDIAN)
91  * \param len Number of bytes to extract (8 max)
92  * \param bytes Data to extract from
93  *
94  * \return n Number of bytes extracted on success
95  * \return -1 On error
96  */
97 int WARN_UNUSED ByteExtractUint64(uint64_t *res, int e, uint16_t len, const uint8_t *bytes);
98 
99 /**
100  * Extract bytes from a byte string and convert to a uint32_t.
101  *
102  * \param res Stores result
103  * \param e Endianness (BYTE_BIG_ENDIAN or BYTE_LITTLE_ENDIAN)
104  * \param len Number of bytes to extract (8 max)
105  * \param bytes Data to extract from
106  *
107  * \return n Number of bytes extracted on success
108  * \return -1 On error
109  */
110 int WARN_UNUSED ByteExtractUint32(uint32_t *res, int e, uint16_t len, const uint8_t *bytes);
111 
112 /**
113  * Extract bytes from a byte string and convert to a unint16_t.
114  *
115  * \param res Stores result
116  * \param e Endianness (BYTE_BIG_ENDIAN or BYTE_LITTLE_ENDIAN)
117  * \param len Number of bytes to extract (8 max)
118  * \param bytes Data to extract from
119  *
120  * \return n Number of bytes extracted on success
121  * \return -1 On error
122  */
123 int WARN_UNUSED ByteExtractUint16(uint16_t *res, int e, uint16_t len, const uint8_t *bytes);
124 
125 /**
126  * Extract unsigned integer value from a string.
127  *
128  * \param res Stores result
129  * \param base Base of the number to extract
130  * \param len Number of bytes to extract (23 max or 0 for unbounded)
131  * \param str String to extract from
132  * \param bool Enable strict check for parsers
133  *
134  * \return n Number of bytes extracted on success
135  * \return -1 On error
136  */
138  uint64_t *res, int base, size_t len, const char *str, bool strict);
139 
140 /**
141  * Extract unsigned integer value from a string as uint64_t.
142  *
143  * \param res Stores result
144  * \param base Base of the number to extract
145  * \param len Number of bytes to extract (23 max or 0 for unbounded)
146  * \param str String to extract from
147  *
148  * \return n Number of bytes extracted on success
149  * \return -1 On error
150  */
151 int WARN_UNUSED ByteExtractStringUint64(uint64_t *res, int base, size_t len, const char *str);
152 
153 /**
154  * Extract unsigned integer value from a string as uint32_t.
155  *
156  * \param res Stores result
157  * \param base Base of the number to extract
158  * \param len Number of bytes to extract (23 max or 0 for unbounded)
159  * \param str String to extract from
160  *
161  * \return n Number of bytes extracted on success
162  * \return -1 On error
163  */
164 int WARN_UNUSED ByteExtractStringUint32(uint32_t *res, int base, size_t len, const char *str);
165 
166 /**
167  * Extract unsigned integer value from a string as uint16_t.
168  *
169  * \param res Stores result
170  * \param base Base of the number to extract
171  * \param len Number of bytes to extract (23 max or 0 for unbounded)
172  * \param str String to extract from
173  *
174  * \return n Number of bytes extracted on success
175  * \return -1 On error
176  */
177 int WARN_UNUSED ByteExtractStringUint16(uint16_t *res, int base, size_t len, const char *str);
178 
179 /**
180  * Extract unsigned integer value from a string as uint8_t.
181  *
182  * \param res Stores result
183  * \param base Base of the number to extract
184  * \param len Number of bytes to extract (23 max or 0 for unbounded)
185  * \param str String to extract from
186  *
187  * \return n Number of bytes extracted on success
188  * \return -1 On error
189  */
190 int WARN_UNUSED ByteExtractStringUint8(uint8_t *res, int base, size_t len, const char *str);
191 
192 /**
193  * Extract signed integer value from a string.
194  *
195  * \param res Stores result
196  * \param base Base of the number to extract
197  * \param len Number of bytes to extract (23 max or 0 for unbounded)
198  * \param str String to extract from
199  * \param bool Enable strict check for parsers
200  *
201  * \return n Number of bytes extracted on success
202  * \return -1 On error
203  */
205  int64_t *res, int base, size_t len, const char *str, bool strict);
206 
207 /**
208  * Extract signed integer value from a string as uint64_t.
209  *
210  * \param res Stores result
211  * \param base Base of the number to extract
212  * \param len Number of bytes to extract (23 max or 0 for unbounded)
213  * \param str String to extract from
214  *
215  * \return n Number of bytes extracted on success
216  * \return -1 On error
217  */
218 int WARN_UNUSED ByteExtractStringInt64(int64_t *res, int base, size_t len, const char *str);
219 
220 /**
221  * Extract signed integer value from a string as uint32_t.
222  *
223  * \param res Stores result
224  * \param base Base of the number to extract
225  * \param len Number of bytes to extract (23 max or 0 for unbounded)
226  * \param str String to extract from
227  *
228  * \return n Number of bytes extracted on success
229  * \return -1 On error
230  */
231 int WARN_UNUSED ByteExtractStringInt32(int32_t *res, int base, size_t len, const char *str);
232 
233 /**
234  * Extract signed integer value from a string as uint16_t.
235  *
236  * \param res Stores result
237  * \param base Base of the number to extract
238  * \param len Number of bytes to extract (23 max or 0 for unbounded)
239  * \param str String to extract from
240  *
241  * \return n Number of bytes extracted on success
242  * \return -1 On error
243  */
244 int WARN_UNUSED ByteExtractStringInt16(int16_t *res, int base, size_t len, const char *str);
245 
246 /**
247  * Extract signed integer value from a string as uint8_t.
248  *
249  * \param res Stores result
250  * \param base Base of the number to extract
251  * \param len Number of bytes to extract (23 max or 0 for unbounded)
252  * \param str String to extract from
253  *
254  * \return n Number of bytes extracted on success
255  * \return -1 On error
256  */
257 int WARN_UNUSED ByteExtractStringInt8(int8_t *res, int base, size_t len, const char *str);
258 
259 /**
260  * Extract unsigned integer value from a string as uint64_t strictly.
261  *
262  * \param res Stores result
263  * \param base Base of the number to extract
264  * \param len Number of bytes to extract (23 max or 0 for unbounded)
265  * \param str String to extract from
266  *
267  * \return n Number of bytes extracted on success
268  * \return -1 On error
269  */
270 int StringParseUint64(uint64_t *res, int base, size_t len, const char *str);
271 
272 /**
273  * Extract unsigned integer value from a string as uint32_t strictly.
274  *
275  * \param res Stores result
276  * \param base Base of the number to extract
277  * \param len Number of bytes to extract (23 max or 0 for unbounded)
278  * \param str String to extract from
279  *
280  * \return n Number of bytes extracted on success
281  * \return -1 On error
282  */
283 int StringParseUint32(uint32_t *res, int base, size_t len, const char *str);
284 
285 /**
286  * Extract unsigned integer value from a string as uint16_t strictly.
287  *
288  * \param res Stores result
289  * \param base Base of the number to extract
290  * \param len Number of bytes to extract (23 max or 0 for unbounded)
291  * \param str String to extract from
292  *
293  * \return n Number of bytes extracted on success
294  * \return -1 On error
295  */
296 int StringParseUint16(uint16_t *res, int base, size_t len, const char *str);
297 
298 /**
299  * Extract unsigned integer value from a string as uint8_t strictly.
300  *
301  * \param res Stores result
302  * \param base Base of the number to extract
303  * \param len Number of bytes to extract (23 max or 0 for unbounded)
304  * \param str String to extract from
305  *
306  * \return n Number of bytes extracted on success
307  * \return -1 On error
308  */
309 int StringParseUint8(uint8_t *res, int base, size_t len, const char *str);
310 
311 /**
312  * Extract signed integer value from a string as int64_t strictly.
313  *
314  * \param res Stores result
315  * \param base Base of the number to extract
316  * \param len Number of bytes to extract (23 max or 0 for unbounded)
317  * \param str String to extract from
318  *
319  * \return n Number of bytes extracted on success
320  * \return -1 On error
321  */
322 int StringParseInt64(int64_t *res, int base, size_t len, const char *str);
323 
324 /**
325  * Extract signed integer value from a string as int32_t strictly.
326  *
327  * \param res Stores result
328  * \param base Base of the number to extract
329  * \param len Number of bytes to extract (23 max or 0 for unbounded)
330  * \param str String to extract from
331  *
332  * \return n Number of bytes extracted on success
333  * \return -1 On error
334  */
335 int StringParseInt32(int32_t *res, int base, size_t len, const char *str);
336 
337 /**
338  * Extract signed integer value from a string as int16_t strictly.
339  *
340  * \param res Stores result
341  * \param base Base of the number to extract
342  * \param len Number of bytes to extract (23 max or 0 for unbounded)
343  * \param str String to extract from
344  *
345  * \return n Number of bytes extracted on success
346  * \return -1 On error
347  */
348 int StringParseInt16(int16_t *res, int base, size_t len, const char *str);
349 
350 /**
351  * Extract signed integer value from a string as int8_t strictly.
352  *
353  * \param res Stores result
354  * \param base Base of the number to extract
355  * \param len Number of bytes to extract (23 max or 0 for unbounded)
356  * \param str String to extract from
357  *
358  * \return n Number of bytes extracted on success
359  * \return -1 On error
360  */
361 int StringParseInt8(int8_t *res, int base, size_t len, const char *str);
362 
363 /**
364  * Extract unsigned integer value from a string as uint64_t strictly within the range.
365  *
366  * \param res Stores result
367  * \param base Base of the number to extract
368  * \param len Number of bytes to extract (23 max or 0 for unbounded)
369  * \param str String to extract from
370  *
371  * \return n Number of bytes extracted on success
372  * \return -1 On error
373  */
375  uint64_t *res, int base, size_t len, const char *str, uint64_t min, uint64_t max);
376 
377 /**
378  * Extract unsigned integer value from a string as uint32_t strictly within the range.
379  *
380  * \param res Stores result
381  * \param base Base of the number to extract
382  * \param len Number of bytes to extract (23 max or 0 for unbounded)
383  * \param str String to extract from
384  *
385  * \return n Number of bytes extracted on success
386  * \return -1 On error
387  */
389  uint32_t *res, int base, size_t len, const char *str, uint32_t min, uint32_t max);
390 
391 /**
392  * Extract unsigned integer value from a string as uint16_t strictly within the range.
393  *
394  * \param res Stores result
395  * \param base Base of the number to extract
396  * \param len Number of bytes to extract (23 max or 0 for unbounded)
397  * \param str String to extract from
398  *
399  * \return n Number of bytes extracted on success
400  * \return -1 On error
401  */
403  uint16_t *res, int base, size_t len, const char *str, uint16_t min, uint16_t max);
404 
405 /**
406  * Extract unsigned integer value from a string as uint8_t strictly within the range.
407  *
408  * \param res Stores result
409  * \param base Base of the number to extract
410  * \param len Number of bytes to extract (23 max or 0 for unbounded)
411  * \param str String to extract from
412  *
413  * \return n Number of bytes extracted on success
414  * \return -1 On error
415  */
417  uint8_t *res, int base, size_t len, const char *str, uint8_t min, uint8_t max);
418 
419 /**
420  * Extract signed integer value from a string as int64_t strictly within the range.
421  *
422  * \param res Stores result
423  * \param base Base of the number to extract
424  * \param len Number of bytes to extract (23 max or 0 for unbounded)
425  * \param str String to extract from
426  *
427  * \return n Number of bytes extracted on success
428  * \return -1 On error
429  */
431  int64_t *res, int base, size_t len, const char *str, int64_t min, int64_t max);
432 
433 /**
434  * Extract signed integer value from a string as int32_t strictly within the range.
435  *
436  * \param res Stores result
437  * \param base Base of the number to extract
438  * \param len Number of bytes to extract (23 max or 0 for unbounded)
439  * \param str String to extract from
440  *
441  * \return n Number of bytes extracted on success
442  * \return -1 On error
443  */
445  int32_t *res, int base, size_t len, const char *str, int32_t min, int32_t max);
446 
447 /**
448  * Extract signed integer value from a string as int16_t strictly within the range.
449  *
450  * \param res Stores result
451  * \param base Base of the number to extract
452  * \param len Number of bytes to extract (23 max or 0 for unbounded)
453  * \param str String to extract from
454  *
455  * \return n Number of bytes extracted on success
456  * \return -1 On error
457  */
459  int16_t *res, int base, size_t len, const char *str, int16_t min, int16_t max);
460 
461 /**
462  * Extract signed integer value from a string as int8_t strictly within the range.
463  *
464  * \param res Stores result
465  * \param base Base of the number to extract
466  * \param len Number of bytes to extract (23 max or 0 for unbounded)
467  * \param str String to extract from
468  *
469  * \return n Number of bytes extracted on success
470  * \return -1 On error
471  */
473  int8_t *res, int base, size_t len, const char *str, int8_t min, int8_t max);
474 
475 #ifdef UNITTESTS
476 void ByteRegisterTests(void);
477 #endif /* UNITTESTS */
478 
479 /** ------ Inline functions ----- */
480 static inline int WARN_UNUSED ByteExtract(uint64_t *res, int e, uint16_t len, const uint8_t *bytes)
481 {
482  if ((e != BYTE_BIG_ENDIAN) && (e != BYTE_LITTLE_ENDIAN)) {
483  /** \todo Need standard return values */
484  return -1;
485  }
486 
487  *res = 0;
488 
489  /* Go through each byte and merge it into the result in the correct order */
490  /** \todo Probably a more efficient way to do this. */
491  for (int i = 0; i < len; i++) {
492  uint64_t b;
493  if (e == BYTE_LITTLE_ENDIAN) {
494  b = bytes[i];
495  }
496  else {
497  b = bytes[len - i - 1];
498  }
499 
500  *res |= (b << ((i & 7) << 3));
501  }
502 
503  return len;
504 }
505 
506 #endif /* __UTIL_BYTE_H__ */
ByteExtractStringInt32
int WARN_UNUSED ByteExtractStringInt32(int32_t *res, int base, size_t len, const char *str)
Definition: util-byte.c:536
ByteExtractUint32
int WARN_UNUSED ByteExtractUint32(uint32_t *res, int e, uint16_t len, const uint8_t *bytes)
Definition: util-byte.c:143
len
uint8_t len
Definition: app-layer-dnp3.h:2
StringParseUint16
int StringParseUint16(uint16_t *res, int base, size_t len, const char *str)
Definition: util-byte.c:336
ByteExtractStringInt64
int WARN_UNUSED ByteExtractStringInt64(int64_t *res, int base, size_t len, const char *str)
Definition: util-byte.c:531
StringParseI32RangeCheck
int WARN_UNUSED StringParseI32RangeCheck(int32_t *res, int base, size_t len, const char *str, int32_t min, int32_t max)
Definition: util-byte.c:704
ByteExtractStringSigned
int WARN_UNUSED ByteExtractStringSigned(int64_t *res, int base, size_t len, const char *str, bool strict)
Definition: util-byte.c:485
BytesToStringBuffer
void BytesToStringBuffer(const uint8_t *bytes, size_t nbytes, char *outstr, size_t outlen)
Turn byte array into string.
Definition: util-byte.c:85
ByteExtractStringUint64
int WARN_UNUSED ByteExtractStringUint64(uint64_t *res, int base, size_t len, const char *str)
Definition: util-byte.c:234
ByteExtractStringUint32
int WARN_UNUSED ByteExtractStringUint32(uint32_t *res, int base, size_t len, const char *str)
Definition: util-byte.c:239
StringParseU16RangeCheck
int WARN_UNUSED StringParseU16RangeCheck(uint16_t *res, int base, size_t len, const char *str, uint16_t min, uint16_t max)
Definition: util-byte.c:429
ByteExtractUint16
int WARN_UNUSED ByteExtractUint16(uint16_t *res, int e, uint16_t len, const uint8_t *bytes)
Definition: util-byte.c:164
ByteExtractUint64
int WARN_UNUSED ByteExtractUint64(uint64_t *res, int e, uint16_t len, const uint8_t *bytes)
Definition: util-byte.c:122
StringParseUint8
int StringParseUint8(uint8_t *res, int base, size_t len, const char *str)
Definition: util-byte.c:359
ByteExtractStringUint8
int WARN_UNUSED ByteExtractStringUint8(uint8_t *res, int base, size_t len, const char *str)
Definition: util-byte.c:285
ByteExtractStringUint16
int WARN_UNUSED ByteExtractStringUint16(uint16_t *res, int base, size_t len, const char *str)
Definition: util-byte.c:262
StringParseU64RangeCheck
int WARN_UNUSED StringParseU64RangeCheck(uint64_t *res, int base, size_t len, const char *str, uint64_t min, uint64_t max)
Definition: util-byte.c:382
BytesToString
char * BytesToString(const uint8_t *bytes, size_t nbytes)
Turn byte array into string.
Definition: util-byte.c:41
BYTE_BIG_ENDIAN
#define BYTE_BIG_ENDIAN
Definition: util-byte.h:29
StringParseUint32
int StringParseUint32(uint32_t *res, int base, size_t len, const char *str)
Definition: util-byte.c:313
StringParseInt16
int StringParseInt16(int16_t *res, int base, size_t len, const char *str)
Definition: util-byte.c:637
StringParseI16RangeCheck
int WARN_UNUSED StringParseI16RangeCheck(int16_t *res, int base, size_t len, const char *str, int16_t min, int16_t max)
Definition: util-byte.c:733
BYTE_LITTLE_ENDIAN
#define BYTE_LITTLE_ENDIAN
Definition: util-byte.h:30
ByteExtractString
int WARN_UNUSED ByteExtractString(uint64_t *res, int base, size_t len, const char *str, bool strict)
Definition: util-byte.c:185
str
#define str(s)
Definition: suricata-common.h:280
StringParseI8RangeCheck
int WARN_UNUSED StringParseI8RangeCheck(int8_t *res, int base, size_t len, const char *str, int8_t min, int8_t max)
Definition: util-byte.c:762
StringParseInt8
int StringParseInt8(int8_t *res, int base, size_t len, const char *str)
Definition: util-byte.c:661
StringParseU32RangeCheck
int WARN_UNUSED StringParseU32RangeCheck(uint32_t *res, int base, size_t len, const char *str, uint32_t min, uint32_t max)
Definition: util-byte.c:401
ByteExtractStringInt16
int WARN_UNUSED ByteExtractStringInt16(int16_t *res, int base, size_t len, const char *str)
Definition: util-byte.c:560
StringParseI64RangeCheck
int WARN_UNUSED StringParseI64RangeCheck(int64_t *res, int base, size_t len, const char *str, int64_t min, int64_t max)
Definition: util-byte.c:685
StringParseInt32
int StringParseInt32(int32_t *res, int base, size_t len, const char *str)
Definition: util-byte.c:613
ByteRegisterTests
void ByteRegisterTests(void)
Definition: util-byte.c:1019
StringParseInt64
int StringParseInt64(int64_t *res, int base, size_t len, const char *str)
Definition: util-byte.c:608
WARN_UNUSED
#define WARN_UNUSED
Definition: suricata-common.h:392
ByteExtractStringInt8
int WARN_UNUSED ByteExtractStringInt8(int8_t *res, int base, size_t len, const char *str)
Definition: util-byte.c:584
StringParseUint64
int StringParseUint64(uint64_t *res, int base, size_t len, const char *str)
Definition: util-byte.c:308
StringParseU8RangeCheck
int WARN_UNUSED StringParseU8RangeCheck(uint8_t *res, int base, size_t len, const char *str, uint8_t min, uint8_t max)
Definition: util-byte.c:457