Allow memwipe() to be called with NULL argument
[strongswan.git] / src / libstrongswan / utils / utils.h
1 /*
2 * Copyright (C) 2008-2012 Tobias Brunner
3 * Copyright (C) 2008 Martin Willi
4 * Hochschule fuer Technik Rapperswil
5 *
6 * This program is free software; you can redistribute it and/or modify it
7 * under the terms of the GNU General Public License as published by the
8 * Free Software Foundation; either version 2 of the License, or (at your
9 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
10 *
11 * This program is distributed in the hope that it will be useful, but
12 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
13 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * for more details.
15 */
16
17 /**
18 * @defgroup utils_i utils
19 * @{ @ingroup utils
20 */
21
22 #ifndef UTILS_H_
23 #define UTILS_H_
24
25 #include <sys/types.h>
26 #include <stdlib.h>
27 #include <stddef.h>
28 #include <sys/time.h>
29 #include <arpa/inet.h>
30 #include <string.h>
31
32 #include "enum.h"
33
34 /**
35 * strongSwan program return codes
36 */
37 #define SS_RC_LIBSTRONGSWAN_INTEGRITY 64
38 #define SS_RC_DAEMON_INTEGRITY 65
39 #define SS_RC_INITIALIZATION_FAILED 66
40
41 #define SS_RC_FIRST SS_RC_LIBSTRONGSWAN_INTEGRITY
42 #define SS_RC_LAST SS_RC_INITIALIZATION_FAILED
43
44 /**
45 * Number of bits in a byte
46 */
47 #define BITS_PER_BYTE 8
48
49 /**
50 * Default length for various auxiliary text buffers
51 */
52 #define BUF_LEN 512
53
54 /**
55 * General purpose boolean type.
56 */
57 #ifdef HAVE_STDBOOL_H
58 # include <stdbool.h>
59 #else
60 # ifndef HAVE__BOOL
61 # define _Bool signed char
62 # endif /* HAVE__BOOL */
63 # define bool _Bool
64 # define false 0
65 # define true 1
66 # define __bool_true_false_are_defined 1
67 #endif /* HAVE_STDBOOL_H */
68 #ifndef FALSE
69 # define FALSE false
70 #endif /* FALSE */
71 #ifndef TRUE
72 # define TRUE true
73 #endif /* TRUE */
74
75 /**
76 * Helper function that compares two strings for equality
77 */
78 static inline bool streq(const char *x, const char *y)
79 {
80 return strcmp(x, y) == 0;
81 }
82
83 /**
84 * Macro compares two strings for equality, length limited
85 */
86 #define strneq(x,y,len) (strncmp(x, y, len) == 0)
87
88 /**
89 * Helper function that compares two strings for equality ignoring case
90 */
91 static inline bool strcaseeq(const char *x, const char *y)
92 {
93 return strcasecmp(x, y) == 0;
94 }
95
96 /**
97 * Macro compares two strings for equality ignoring case, length limited
98 */
99 #define strncaseeq(x,y,len) (strncasecmp(x, y, len) == 0)
100
101 /**
102 * NULL-safe strdup variant
103 */
104 static inline char *strdupnull(const char *s)
105 {
106 return s ? strdup(s) : NULL;
107 }
108
109 /**
110 * Macro compares two binary blobs for equality
111 */
112 #define memeq(x,y,len) (memcmp(x, y, len) == 0)
113
114 /**
115 * Macro gives back larger of two values.
116 */
117 #define max(x,y) ({ \
118 typeof(x) _x = (x); \
119 typeof(y) _y = (y); \
120 _x > _y ? _x : _y; })
121
122
123 /**
124 * Macro gives back smaller of two values.
125 */
126 #define min(x,y) ({ \
127 typeof(x) _x = (x); \
128 typeof(y) _y = (y); \
129 _x < _y ? _x : _y; })
130
131 /**
132 * Call destructor of an object, if object != NULL
133 */
134 #define DESTROY_IF(obj) if (obj) (obj)->destroy(obj)
135
136 /**
137 * Call offset destructor of an object, if object != NULL
138 */
139 #define DESTROY_OFFSET_IF(obj, offset) if (obj) obj->destroy_offset(obj, offset);
140
141 /**
142 * Call function destructor of an object, if object != NULL
143 */
144 #define DESTROY_FUNCTION_IF(obj, fn) if (obj) obj->destroy_function(obj, fn);
145
146 /**
147 * Debug macro to follow control flow
148 */
149 #define POS printf("%s, line %d\n", __FILE__, __LINE__)
150
151 /**
152 * Object allocation/initialization macro, using designated initializer.
153 */
154 #define INIT(this, ...) { (this) = malloc(sizeof(*(this))); \
155 *(this) = (typeof(*(this))){ __VA_ARGS__ }; }
156
157 /**
158 * Method declaration/definition macro, providing private and public interface.
159 *
160 * Defines a method name with this as first parameter and a return value ret,
161 * and an alias for this method with a _ prefix, having the this argument
162 * safely casted to the public interface iface.
163 * _name is provided a function pointer, but will get optimized out by GCC.
164 */
165 #define METHOD(iface, name, ret, this, ...) \
166 static ret name(union {iface *_public; this;} \
167 __attribute__((transparent_union)), ##__VA_ARGS__); \
168 static typeof(name) *_##name = (typeof(name)*)name; \
169 static ret name(this, ##__VA_ARGS__)
170
171 /**
172 * Same as METHOD(), but is defined for two public interfaces.
173 */
174 #define METHOD2(iface1, iface2, name, ret, this, ...) \
175 static ret name(union {iface1 *_public1; iface2 *_public2; this;} \
176 __attribute__((transparent_union)), ##__VA_ARGS__); \
177 static typeof(name) *_##name = (typeof(name)*)name; \
178 static ret name(this, ##__VA_ARGS__)
179
180 /**
181 * Architecture independent bitfield definition helpers (at least with GCC).
182 *
183 * Defines a bitfield with a type t and a fixed size of bitfield members, e.g.:
184 * BITFIELD2(u_int8_t,
185 * low: 4,
186 * high: 4,
187 * ) flags;
188 * The member defined first placed at bit 0.
189 */
190 #if BYTE_ORDER == LITTLE_ENDIAN
191 #define BITFIELD2(t, a, b,...) struct { t a; t b; __VA_ARGS__}
192 #define BITFIELD3(t, a, b, c,...) struct { t a; t b; t c; __VA_ARGS__}
193 #define BITFIELD4(t, a, b, c, d,...) struct { t a; t b; t c; t d; __VA_ARGS__}
194 #define BITFIELD5(t, a, b, c, d, e,...) struct { t a; t b; t c; t d; t e; __VA_ARGS__}
195 #elif BYTE_ORDER == BIG_ENDIAN
196 #define BITFIELD2(t, a, b,...) struct { t b; t a; __VA_ARGS__}
197 #define BITFIELD3(t, a, b, c,...) struct { t c; t b; t a; __VA_ARGS__}
198 #define BITFIELD4(t, a, b, c, d,...) struct { t d; t c; t b; t a; __VA_ARGS__}
199 #define BITFIELD5(t, a, b, c, d, e,...) struct { t e; t d; t c; t b; t a; __VA_ARGS__}
200 #endif
201
202 /**
203 * Macro to allocate a sized type.
204 */
205 #define malloc_thing(thing) ((thing*)malloc(sizeof(thing)))
206
207 /**
208 * Get the number of elements in an array
209 */
210 #define countof(array) (sizeof(array)/sizeof(array[0]))
211
212 /**
213 * Ignore result of functions tagged with warn_unused_result attributes
214 */
215 #define ignore_result(call) { if(call){}; }
216
217 /**
218 * Assign a function as a class method
219 */
220 #define ASSIGN(method, function) (method = (typeof(method))function)
221
222 /**
223 * time_t not defined
224 */
225 #define UNDEFINED_TIME 0
226
227 /**
228 * Maximum time since epoch causing wrap-around on Jan 19 03:14:07 UTC 2038
229 */
230 #define TIME_32_BIT_SIGNED_MAX 0x7fffffff
231
232 /**
233 * define some missing fixed width int types on OpenSolaris.
234 * TODO: since the uintXX_t types are defined by the C99 standard we should
235 * probably use those anyway
236 */
237 #ifdef __sun
238 #include <stdint.h>
239 typedef uint8_t u_int8_t;
240 typedef uint16_t u_int16_t;
241 typedef uint32_t u_int32_t;
242 typedef uint64_t u_int64_t;
243 #endif
244
245 typedef enum status_t status_t;
246
247 /**
248 * Return values of function calls.
249 */
250 enum status_t {
251 /**
252 * Call succeeded.
253 */
254 SUCCESS,
255
256 /**
257 * Call failed.
258 */
259 FAILED,
260
261 /**
262 * Out of resources.
263 */
264 OUT_OF_RES,
265
266 /**
267 * The suggested operation is already done
268 */
269 ALREADY_DONE,
270
271 /**
272 * Not supported.
273 */
274 NOT_SUPPORTED,
275
276 /**
277 * One of the arguments is invalid.
278 */
279 INVALID_ARG,
280
281 /**
282 * Something could not be found.
283 */
284 NOT_FOUND,
285
286 /**
287 * Error while parsing.
288 */
289 PARSE_ERROR,
290
291 /**
292 * Error while verifying.
293 */
294 VERIFY_ERROR,
295
296 /**
297 * Object in invalid state.
298 */
299 INVALID_STATE,
300
301 /**
302 * Destroy object which called method belongs to.
303 */
304 DESTROY_ME,
305
306 /**
307 * Another call to the method is required.
308 */
309 NEED_MORE,
310 };
311
312 /**
313 * enum_names for type status_t.
314 */
315 extern enum_name_t *status_names;
316
317 typedef enum tty_escape_t tty_escape_t;
318
319 /**
320 * Excape codes for tty colors
321 */
322 enum tty_escape_t {
323 /** text properties */
324 TTY_RESET,
325 TTY_BOLD,
326 TTY_UNDERLINE,
327 TTY_BLINKING,
328
329 /** foreground colors */
330 TTY_FG_BLACK,
331 TTY_FG_RED,
332 TTY_FG_GREEN,
333 TTY_FG_YELLOW,
334 TTY_FG_BLUE,
335 TTY_FG_MAGENTA,
336 TTY_FG_CYAN,
337 TTY_FG_WHITE,
338 TTY_FG_DEF,
339
340 /** background colors */
341 TTY_BG_BLACK,
342 TTY_BG_RED,
343 TTY_BG_GREEN,
344 TTY_BG_YELLOW,
345 TTY_BG_BLUE,
346 TTY_BG_MAGENTA,
347 TTY_BG_CYAN,
348 TTY_BG_WHITE,
349 TTY_BG_DEF,
350 };
351
352 /**
353 * Get the escape string for a given TTY color, empty string on non-tty fd
354 */
355 char* tty_escape_get(int fd, tty_escape_t escape);
356
357 /**
358 * deprecated pluto style return value:
359 * error message, NULL for success
360 */
361 typedef const char *err_t;
362
363 /**
364 * Handle struct timeval like an own type.
365 */
366 typedef struct timeval timeval_t;
367
368 /**
369 * Handle struct timespec like an own type.
370 */
371 typedef struct timespec timespec_t;
372
373 /**
374 * Handle struct chunk_t like an own type.
375 */
376 typedef struct sockaddr sockaddr_t;
377
378 /**
379 * Clone a data to a newly allocated buffer
380 */
381 void *clalloc(void *pointer, size_t size);
382
383 /**
384 * Same as memcpy, but XORs src into dst instead of copy
385 */
386 void memxor(u_int8_t dest[], u_int8_t src[], size_t n);
387
388 /**
389 * Safely overwrite n bytes of memory at ptr with zero, non-inlining variant.
390 */
391 void memwipe_noinline(void *ptr, size_t n);
392
393 /**
394 * Safely overwrite n bytes of memory at ptr with zero, inlining variant.
395 */
396 static inline void memwipe_inline(void *ptr, size_t n)
397 {
398 volatile char *c = (volatile char*)ptr;
399 size_t m, i;
400
401 /* byte wise until long aligned */
402 for (i = 0; (uintptr_t)&c[i] % sizeof(long) && i < n; i++)
403 {
404 c[i] = 0;
405 }
406 /* word wise */
407 if (n >= sizeof(long))
408 {
409 for (m = n - sizeof(long); i <= m; i += sizeof(long))
410 {
411 *(volatile long*)&c[i] = 0;
412 }
413 }
414 /* byte wise of the rest */
415 for (; i < n; i++)
416 {
417 c[i] = 0;
418 }
419 }
420
421 /**
422 * Safely overwrite n bytes of memory at ptr with zero, auto-inlining variant.
423 */
424 static inline void memwipe(void *ptr, size_t n)
425 {
426 if (!ptr)
427 {
428 return;
429 }
430 if (__builtin_constant_p(n))
431 {
432 memwipe_inline(ptr, n);
433 }
434 else
435 {
436 memwipe_noinline(ptr, n);
437 }
438 }
439
440 /**
441 * A variant of strstr with the characteristics of memchr, where haystack is not
442 * a null-terminated string but simply a memory area of length n.
443 */
444 void *memstr(const void *haystack, const char *needle, size_t n);
445
446 /**
447 * Translates the characters in the given string, searching for characters
448 * in 'from' and mapping them to characters in 'to'.
449 * The two characters sets 'from' and 'to' must contain the same number of
450 * characters.
451 */
452 char *translate(char *str, const char *from, const char *to);
453
454 /**
455 * Creates a directory and all required parent directories.
456 *
457 * @param path path to the new directory
458 * @param mode permissions of the new directory/directories
459 * @return TRUE on success
460 */
461 bool mkdir_p(const char *path, mode_t mode);
462
463 /**
464 * Thread-safe wrapper around strerror and strerror_r.
465 *
466 * This is required because the first is not thread-safe (on some platforms)
467 * and the second uses two different signatures (POSIX/GNU) and is impractical
468 * to use anyway.
469 *
470 * @param errnum error code (i.e. errno)
471 * @return error message
472 */
473 const char *safe_strerror(int errnum);
474
475 /**
476 * Replace usages of strerror(3) with thread-safe variant.
477 */
478 #define strerror(errnum) safe_strerror(errnum)
479
480 #ifndef HAVE_CLOSEFROM
481 /**
482 * Close open file descriptors greater than or equal to lowfd.
483 *
484 * @param lowfd start closing file descriptoros from here
485 */
486 void closefrom(int lowfd);
487 #endif
488
489 /**
490 * Get a timestamp from a monotonic time source.
491 *
492 * While the time()/gettimeofday() functions are affected by leap seconds
493 * and system time changes, this function returns ever increasing monotonic
494 * time stamps.
495 *
496 * @param tv timeval struct receiving monotonic timestamps, or NULL
497 * @return monotonic timestamp in seconds
498 */
499 time_t time_monotonic(timeval_t *tv);
500
501 /**
502 * Add the given number of milliseconds to the given timeval struct
503 *
504 * @param tv timeval struct to modify
505 * @param ms number of milliseconds
506 */
507 static inline void timeval_add_ms(timeval_t *tv, u_int ms)
508 {
509 tv->tv_usec += ms * 1000;
510 while (tv->tv_usec > 1000000 /* 1s */)
511 {
512 tv->tv_usec -= 1000000;
513 tv->tv_sec++;
514 }
515 }
516
517 /**
518 * returns null
519 */
520 void *return_null();
521
522 /**
523 * No-Operation function
524 */
525 void nop();
526
527 /**
528 * returns TRUE
529 */
530 bool return_true();
531
532 /**
533 * returns FALSE
534 */
535 bool return_false();
536
537 /**
538 * returns FAILED
539 */
540 status_t return_failed();
541
542 /**
543 * returns SUCCESS
544 */
545 status_t return_success();
546
547 /**
548 * Write a 16-bit host order value in network order to an unaligned address.
549 *
550 * @param host host order 16-bit value
551 * @param network unaligned address to write network order value to
552 */
553 static inline void htoun16(void *network, u_int16_t host)
554 {
555 char *unaligned = (char*)network;
556
557 host = htons(host);
558 memcpy(unaligned, &host, sizeof(host));
559 }
560
561 /**
562 * Write a 32-bit host order value in network order to an unaligned address.
563 *
564 * @param host host order 32-bit value
565 * @param network unaligned address to write network order value to
566 */
567 static inline void htoun32(void *network, u_int32_t host)
568 {
569 char *unaligned = (char*)network;
570
571 host = htonl(host);
572 memcpy((char*)unaligned, &host, sizeof(host));
573 }
574
575 /**
576 * Write a 64-bit host order value in network order to an unaligned address.
577 *
578 * @param host host order 64-bit value
579 * @param network unaligned address to write network order value to
580 */
581 static inline void htoun64(void *network, u_int64_t host)
582 {
583 char *unaligned = (char*)network;
584
585 #ifdef be64toh
586 host = htobe64(host);
587 memcpy((char*)unaligned, &host, sizeof(host));
588 #else
589 u_int32_t high_part, low_part;
590
591 high_part = host >> 32;
592 high_part = htonl(high_part);
593 low_part = host & 0xFFFFFFFFLL;
594 low_part = htonl(low_part);
595
596 memcpy(unaligned, &high_part, sizeof(high_part));
597 unaligned += sizeof(high_part);
598 memcpy(unaligned, &low_part, sizeof(low_part));
599 #endif
600 }
601
602 /**
603 * Read a 16-bit value in network order from an unaligned address to host order.
604 *
605 * @param network unaligned address to read network order value from
606 * @return host order value
607 */
608 static inline u_int16_t untoh16(void *network)
609 {
610 char *unaligned = (char*)network;
611 u_int16_t tmp;
612
613 memcpy(&tmp, unaligned, sizeof(tmp));
614 return ntohs(tmp);
615 }
616
617 /**
618 * Read a 32-bit value in network order from an unaligned address to host order.
619 *
620 * @param network unaligned address to read network order value from
621 * @return host order value
622 */
623 static inline u_int32_t untoh32(void *network)
624 {
625 char *unaligned = (char*)network;
626 u_int32_t tmp;
627
628 memcpy(&tmp, unaligned, sizeof(tmp));
629 return ntohl(tmp);
630 }
631
632 /**
633 * Read a 64-bit value in network order from an unaligned address to host order.
634 *
635 * @param network unaligned address to read network order value from
636 * @return host order value
637 */
638 static inline u_int64_t untoh64(void *network)
639 {
640 char *unaligned = (char*)network;
641
642 #ifdef be64toh
643 u_int64_t tmp;
644
645 memcpy(&tmp, unaligned, sizeof(tmp));
646 return be64toh(tmp);
647 #else
648 u_int32_t high_part, low_part;
649
650 memcpy(&high_part, unaligned, sizeof(high_part));
651 unaligned += sizeof(high_part);
652 memcpy(&low_part, unaligned, sizeof(low_part));
653
654 high_part = ntohl(high_part);
655 low_part = ntohl(low_part);
656
657 return (((u_int64_t)high_part) << 32) + low_part;
658 #endif
659 }
660
661 /**
662 * Special type to count references
663 */
664 typedef volatile u_int refcount_t;
665
666
667 #ifdef HAVE_GCC_ATOMIC_OPERATIONS
668
669 #define ref_get(ref) {__sync_fetch_and_add(ref, 1); }
670 #define ref_put(ref) (!__sync_sub_and_fetch(ref, 1))
671
672 #define cas_bool(ptr, oldval, newval) \
673 (__sync_bool_compare_and_swap(ptr, oldval, newval))
674 #define cas_ptr(ptr, oldval, newval) \
675 (__sync_bool_compare_and_swap(ptr, oldval, newval))
676
677 #else /* !HAVE_GCC_ATOMIC_OPERATIONS */
678
679 /**
680 * Get a new reference.
681 *
682 * Increments the reference counter atomic.
683 *
684 * @param ref pointer to ref counter
685 */
686 void ref_get(refcount_t *ref);
687
688 /**
689 * Put back a unused reference.
690 *
691 * Decrements the reference counter atomic and
692 * says if more references available.
693 *
694 * @param ref pointer to ref counter
695 * @return TRUE if no more references counted
696 */
697 bool ref_put(refcount_t *ref);
698
699 /**
700 * Atomically replace value of ptr with newval if it currently equals oldval.
701 *
702 * @param ptr pointer to variable
703 * @param oldval old value of the variable
704 * @param newval new value set if possible
705 * @return TRUE if value equaled oldval and newval was written
706 */
707 bool cas_bool(bool *ptr, bool oldval, bool newval);
708
709 /**
710 * Atomically replace value of ptr with newval if it currently equals oldval.
711 *
712 * @param ptr pointer to variable
713 * @param oldval old value of the variable
714 * @param newval new value set if possible
715 * @return TRUE if value equaled oldval and newval was written
716 */
717 bool cas_ptr(void **ptr, void *oldval, void *newval);
718
719 #endif /* HAVE_GCC_ATOMIC_OPERATIONS */
720
721 /**
722 * printf hook for time_t.
723 *
724 * Arguments are:
725 * time_t* time, bool utc
726 */
727 int time_printf_hook(printf_hook_data_t *data, printf_hook_spec_t *spec,
728 const void *const *args);
729
730 /**
731 * printf hook for time_t deltas.
732 *
733 * Arguments are:
734 * time_t* begin, time_t* end
735 */
736 int time_delta_printf_hook(printf_hook_data_t *data, printf_hook_spec_t *spec,
737 const void *const *args);
738
739 /**
740 * printf hook for memory areas.
741 *
742 * Arguments are:
743 * u_char *ptr, u_int len
744 */
745 int mem_printf_hook(printf_hook_data_t *data, printf_hook_spec_t *spec,
746 const void *const *args);
747
748 #endif /** UTILS_H_ @}*/