src/libstrongswan/utils/chunk.h

   1 /*
   2  * Copyright (C) 2008-2013 Tobias Brunner
   3  * Copyright (C) 2005-2008 Martin Willi
   4  * Copyright (C) 2005 Jan Hutter
   5  * Hochschule fuer Technik Rapperswil
   6  *
   7  * This program is free software; you can redistribute it and/or modify it
   8  * under the terms of the GNU General Public License as published by the
   9  * Free Software Foundation; either version 2 of the License, or (at your
  10  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
  11  *
  12  * This program is distributed in the hope that it will be useful, but
  13  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  14  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  15  * for more details.
  16  */
  17
  18 /**
  19  * @defgroup chunk chunk
  20  * @{ @ingroup utils
  21  */
  22
  23 #ifndef CHUNK_H_
  24 #define CHUNK_H_
  25
  26 #include <string.h>
  27 #include <stdarg.h>
  28 #include <sys/types.h>
  29 #ifdef HAVE_ALLOCA_H
  30 #include <alloca.h>
  31 #endif
  32
  33 typedef struct chunk_t chunk_t;
  34
  35 /**
  36  * General purpose pointer/length abstraction.
  37  */
  38 struct chunk_t {
  39         /** Pointer to start of data */
  40         u_char *ptr;
  41         /** Length of data in bytes */
  42         size_t len;
  43 };
  44
  45 #include "utils.h"
  46
  47 /**
  48  * A { NULL, 0 }-chunk handy for initialization.
  49  */
  50 extern chunk_t chunk_empty;
  51
  52 /**
  53  * Create a new chunk pointing to "ptr" with length "len"
  54  */
  55 static inline chunk_t chunk_create(u_char *ptr, size_t len)
  56 {
  57         chunk_t chunk = {ptr, len};
  58         return chunk;
  59 }
  60
  61 /**
  62  * Create a clone of a chunk pointing to "ptr"
  63  */
  64 chunk_t chunk_create_clone(u_char *ptr, chunk_t chunk);
  65
  66 /**
  67  * Calculate length of multiple chunks
  68  */
  69 size_t chunk_length(const char *mode, ...);
  70
  71 /**
  72  * Concatenate chunks into a chunk pointing to "ptr".
  73  *
  74  * The mode string specifies the number of chunks, and how to handle each of
  75  * them with a single character: 'c' for copy (allocate new chunk), 'm' for move
  76  * (free given chunk) or 's' for sensitive-move (clear given chunk, then free).
  77  */
  78 chunk_t chunk_create_cat(u_char *ptr, const char* mode, ...);
  79
  80 /**
  81  * Split up a chunk into parts, "mode" is a string of "a" (alloc),
  82  * "c" (copy) and "m" (move). Each letter say for the corresponding chunk if
  83  * it should get allocated on heap, copied into existing chunk, or the chunk
  84  * should point into "chunk". The length of each part is an argument before
  85  * each target chunk. E.g.:
  86  * chunk_split(chunk, "mcac", 3, &a, 7, &b, 5, &c, d.len, &d);
  87  */
  88 void chunk_split(chunk_t chunk, const char *mode, ...);
  89
  90 /**
  91  * Write the binary contents of a chunk_t to a file
  92  *
  93  * @param chunk                 contents to write to file
  94  * @param path                  path where file is written to
  95  * @param label                 label specifying file type
  96  * @param mask                  file mode creation mask
  97  * @param force                 overwrite existing file by force
  98  * @return                              TRUE if write operation was successful
  99  */
 100 bool chunk_write(chunk_t chunk, char *path, char *label, mode_t mask, bool force);
 101
 102 /**
 103  * Convert a chunk of data to hex encoding.
 104  *
 105  * The resulting string is '\\0' terminated, but the chunk does not include
 106  * the '\\0'. If buf is supplied, it must hold at least (chunk.len * 2 + 1).
 107  *
 108  * @param chunk                 data to convert to hex encoding
 109  * @param buf                   buffer to write to, NULL to malloc
 110  * @param uppercase             TRUE to use uppercase letters
 111  * @return                              chunk of encoded data
 112  */
 113 chunk_t chunk_to_hex(chunk_t chunk, char *buf, bool uppercase);
 114
 115 /**
 116  * Convert a hex encoded in a binary chunk.
 117  *
 118  * If buf is supplied, it must hold at least (hex.len / 2) + (hex.len % 2)
 119  * bytes. It is filled by the right to give correct values for short inputs.
 120  *
 121  * @param hex                   hex encoded input data
 122  * @param buf                   buffer to write decoded data, NULL to malloc
 123  * @return                              converted data
 124  */
 125 chunk_t chunk_from_hex(chunk_t hex, char *buf);
 126
 127 /**
 128  * Convert a chunk of data to its base64 encoding.
 129  *
 130  * The resulting string is '\\0' terminated, but the chunk does not include
 131  * the '\\0'. If buf is supplied, it must hold at least (chunk.len * 4 / 3 + 1).
 132  *
 133  * @param chunk                 data to convert
 134  * @param buf                   buffer to write to, NULL to malloc
 135  * @return                              chunk of encoded data
 136  */
 137 chunk_t chunk_to_base64(chunk_t chunk, char *buf);
 138
 139 /**
 140  * Convert a base64 in a binary chunk.
 141  *
 142  * If buf is supplied, it must hold at least (base64.len / 4 * 3).
 143  *
 144  * @param base64                base64 encoded input data
 145  * @param buf                   buffer to write decoded data, NULL to malloc
 146  * @return                              converted data
 147  */
 148 chunk_t chunk_from_base64(chunk_t base64, char *buf);
 149
 150 /**
 151  * Convert a chunk of data to its base32 encoding.
 152  *
 153  * The resulting string is '\\0' terminated, but the chunk does not include
 154  * the '\\0'. If buf is supplied, it must hold (chunk.len * 8 / 5 + 1) bytes.
 155  *
 156  * @param chunk                 data to convert
 157  * @param buf                   buffer to write to, NULL to malloc
 158  * @return                              chunk of encoded data
 159  */
 160 chunk_t chunk_to_base32(chunk_t chunk, char *buf);
 161
 162 /**
 163  * Free contents of a chunk
 164  */
 165 static inline void chunk_free(chunk_t *chunk)
 166 {
 167         free(chunk->ptr);
 168         *chunk = chunk_empty;
 169 }
 170
 171 /**
 172  * Overwrite the contents of a chunk and free it
 173  */
 174 static inline void chunk_clear(chunk_t *chunk)
 175 {
 176         if (chunk->ptr)
 177         {
 178                 memwipe(chunk->ptr, chunk->len);
 179                 chunk_free(chunk);
 180         }
 181 }
 182
 183 /**
 184  * Initialize a chunk using a char array
 185  */
 186 #define chunk_from_chars(...) ((chunk_t){(char[]){__VA_ARGS__}, sizeof((char[]){__VA_ARGS__})})
 187
 188 /**
 189  * Initialize a chunk to point to a thing
 190  */
 191 #define chunk_from_thing(thing) chunk_create((char*)&(thing), sizeof(thing))
 192
 193 /**
 194  * Initialize a chunk from a static string, not containing 0-terminator
 195  */
 196 #define chunk_from_str(str) chunk_create(str, strlen(str))
 197
 198 /**
 199  * Allocate a chunk on the heap
 200  */
 201 #define chunk_alloc(bytes) ({size_t x = (bytes); chunk_create(x ? malloc(x) : NULL, x);})
 202
 203 /**
 204  * Allocate a chunk on the stack
 205  */
 206 #define chunk_alloca(bytes) ({size_t x = (bytes); chunk_create(x ? alloca(x) : NULL, x);})
 207
 208 /**
 209  * Clone a chunk on heap
 210  */
 211 #define chunk_clone(chunk) ({chunk_t x = (chunk); chunk_create_clone(x.len ? malloc(x.len) : NULL, x);})
 212
 213 /**
 214  * Clone a chunk on stack
 215  */
 216 #define chunk_clonea(chunk) ({chunk_t x = (chunk); chunk_create_clone(x.len ? alloca(x.len) : NULL, x);})
 217
 218 /**
 219  * Concatenate chunks into a chunk on heap
 220  */
 221 #define chunk_cat(mode, ...) chunk_create_cat(malloc(chunk_length(mode, __VA_ARGS__)), mode, __VA_ARGS__)
 222
 223 /**
 224  * Concatenate chunks into a chunk on stack
 225  */
 226 #define chunk_cata(mode, ...) chunk_create_cat(alloca(chunk_length(mode, __VA_ARGS__)), mode, __VA_ARGS__)
 227
 228 /**
 229  * Skip n bytes in chunk (forward pointer, shorten length)
 230  */
 231 static inline chunk_t chunk_skip(chunk_t chunk, size_t bytes)
 232 {
 233         if (chunk.len > bytes)
 234         {
 235                 chunk.ptr += bytes;
 236                 chunk.len -= bytes;
 237                 return chunk;
 238         }
 239         return chunk_empty;
 240 }
 241
 242 /**
 243  * Skip a leading zero-valued byte
 244  */
 245 static inline chunk_t chunk_skip_zero(chunk_t chunk)
 246 {
 247         if (chunk.len > 1 && *chunk.ptr == 0x00)
 248         {
 249                 chunk.ptr++;
 250                 chunk.len--;
 251         }
 252         return chunk;
 253 }
 254
 255
 256 /**
 257  *  Compare two chunks, returns zero if a equals b
 258  *  or negative/positive if a is small/greater than b
 259  */
 260 int chunk_compare(chunk_t a, chunk_t b);
 261
 262 /**
 263  * Compare two chunks for equality,
 264  * NULL chunks are never equal.
 265  */
 266 static inline bool chunk_equals(chunk_t a, chunk_t b)
 267 {
 268         return a.ptr != NULL  && b.ptr != NULL &&
 269                         a.len == b.len && memeq(a.ptr, b.ptr, a.len);
 270 }
 271
 272 /**
 273  * Compare two chunks (given as pointers) for equality (useful as callback),
 274  * NULL chunks are never equal.
 275  */
 276 static inline bool chunk_equals_ptr(chunk_t *a, chunk_t *b)
 277 {
 278         return a != NULL && b != NULL && chunk_equals(*a, *b);
 279 }
 280
 281 /**
 282  * Increment a chunk, as it would reprensent a network order integer.
 283  *
 284  * @param chunk                 chunk to increment
 285  * @return                              TRUE if an overflow occurred
 286  */
 287 bool chunk_increment(chunk_t chunk);
 288
 289 /**
 290  * Check if a chunk has printable characters only.
 291  *
 292  * If sane is given, chunk is cloned into sane and all non printable characters
 293  * get replaced by "replace".
 294  *
 295  * @param chunk                 chunk to check for printability
 296  * @param sane                  pointer where sane version is allocated, or NULL
 297  * @param replace               character to use for replaceing unprintable characters
 298  * @return                              TRUE if all characters in chunk are printable
 299  */
 300 bool chunk_printable(chunk_t chunk, chunk_t *sane, char replace);
 301
 302 /**
 303  * Computes a 32 bit hash of the given chunk.
 304  * @note This hash is only intended for hash tables not for cryptographic purposes.
 305  */
 306 u_int32_t chunk_hash(chunk_t chunk);
 307
 308 /**
 309  * Incremental version of chunk_hash. Use this to hash two or more chunks.
 310  */
 311 u_int32_t chunk_hash_inc(chunk_t chunk, u_int32_t hash);
 312
 313 /**
 314  * Computes a quick MAC from the given chunk and key using SipHash.
 315  *
 316  * The key must have a length of 128-bit (16 bytes).
 317  *
 318  * @note While SipHash has strong features using it for cryptographic purposes
 319  * is not recommended (in particular because of the rather short output size).
 320  *
 321  * @param chunk                 data to process
 322  * @param key                   key to use
 323  * @return                              MAC for given input and key
 324  */
 325 u_int64_t chunk_mac(chunk_t chunk, u_char *key);
 326
 327 /**
 328  * printf hook function for chunk_t.
 329  *
 330  * Arguments are:
 331  *      chunk_t *chunk
 332  * Use #-modifier to print a compact version
 333  */
 334 int chunk_printf_hook(printf_hook_data_t *data, printf_hook_spec_t *spec,
 335                                           const void *const *args);
 336
 337 #endif /** CHUNK_H_ @}*/