Annotation of embedaddon/strongswan/src/libstrongswan/utils/chunk.h, revision 1.1
1.1 ! misho 1: /*
! 2: * Copyright (C) 2008-2019 Tobias Brunner
! 3: * Copyright (C) 2005-2008 Martin Willi
! 4: * Copyright (C) 2005 Jan Hutter
! 5: * HSR 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: #include <utils/utils.h>
! 34:
! 35: typedef struct chunk_t chunk_t;
! 36:
! 37: /**
! 38: * General purpose pointer/length abstraction.
! 39: */
! 40: struct chunk_t {
! 41: /** Pointer to start of data */
! 42: u_char *ptr;
! 43: /** Length of data in bytes */
! 44: size_t len;
! 45: };
! 46:
! 47: #include "utils.h"
! 48:
! 49: /**
! 50: * A { NULL, 0 }-chunk handy for initialization.
! 51: */
! 52: extern chunk_t chunk_empty;
! 53:
! 54: /**
! 55: * Create a new chunk pointing to "ptr" with length "len"
! 56: */
! 57: static inline chunk_t chunk_create(u_char *ptr, size_t len)
! 58: {
! 59: chunk_t chunk = {ptr, len};
! 60: return chunk;
! 61: }
! 62:
! 63: /**
! 64: * Create a clone of a chunk pointing to "ptr"
! 65: */
! 66: chunk_t chunk_create_clone(u_char *ptr, chunk_t chunk);
! 67:
! 68: /**
! 69: * Calculate length of multiple chunks
! 70: */
! 71: size_t chunk_length(const char *mode, ...);
! 72:
! 73: /**
! 74: * Concatenate chunks into a chunk pointing to "ptr".
! 75: *
! 76: * The mode string specifies the number of chunks, and how to handle each of
! 77: * them with a single character: 'c' for copy (allocate new chunk), 'm' for move
! 78: * (free given chunk) or 's' for sensitive-move (clear given chunk, then free).
! 79: */
! 80: chunk_t chunk_create_cat(u_char *ptr, const char* mode, ...);
! 81:
! 82: /**
! 83: * Split up a chunk into parts, "mode" is a string of "a" (alloc),
! 84: * "c" (copy) and "m" (move). Each letter say for the corresponding chunk if
! 85: * it should get allocated on heap, copied into existing chunk, or the chunk
! 86: * should point into "chunk". The length of each part is an argument before
! 87: * each target chunk. E.g.:
! 88: * chunk_split(chunk, "mcac", 3, &a, 7, &b, 5, &c, d.len, &d);
! 89: */
! 90: void chunk_split(chunk_t chunk, const char *mode, ...);
! 91:
! 92: /**
! 93: * Write the binary contents of a chunk_t to a file
! 94: *
! 95: * If the write fails, errno is set appropriately.
! 96: *
! 97: * @param chunk contents to write to file
! 98: * @param path path where file is written to
! 99: * @param mask file mode creation mask
! 100: * @param force overwrite existing file by force
! 101: * @return TRUE if write operation was successful
! 102: */
! 103: bool chunk_write(chunk_t chunk, char *path, mode_t mask, bool force);
! 104:
! 105: /**
! 106: * Store data read from FD into a chunk
! 107: *
! 108: * On error, errno is set appropriately.
! 109: *
! 110: * @param fd file descriptor to read from
! 111: * @param chunk chunk receiving allocated buffer
! 112: * @return TRUE if successful, FALSE on failure
! 113: */
! 114: bool chunk_from_fd(int fd, chunk_t *chunk);
! 115:
! 116: /**
! 117: * mmap() a file to a chunk
! 118: *
! 119: * The returned chunk structure is allocated from heap, but it must be freed
! 120: * through chunk_unmap(). A user may alter the chunk ptr or len, but must pass
! 121: * the chunk pointer returned from chunk_map() to chunk_unmap() after use.
! 122: *
! 123: * On error, errno is set appropriately.
! 124: *
! 125: * @param path path of file to map
! 126: * @param wr TRUE to sync writes to disk
! 127: * @return mapped chunk, NULL on error
! 128: */
! 129: chunk_t *chunk_map(char *path, bool wr);
! 130:
! 131: /**
! 132: * munmap() a chunk previously mapped with chunk_map()
! 133: *
! 134: * When unmapping a writeable map, the return value should be checked to
! 135: * ensure changes landed on disk.
! 136: *
! 137: * @param chunk pointer returned from chunk_map()
! 138: * @return TRUE of changes written back to file
! 139: */
! 140: bool chunk_unmap(chunk_t *chunk);
! 141:
! 142: /**
! 143: * Convert a chunk of data to hex encoding.
! 144: *
! 145: * The resulting string is '\\0' terminated, but the chunk does not include
! 146: * the '\\0'. If buf is supplied, it must hold at least (chunk.len * 2 + 1).
! 147: *
! 148: * @param chunk data to convert to hex encoding
! 149: * @param buf buffer to write to, NULL to malloc
! 150: * @param uppercase TRUE to use uppercase letters
! 151: * @return chunk of encoded data
! 152: */
! 153: chunk_t chunk_to_hex(chunk_t chunk, char *buf, bool uppercase);
! 154:
! 155: /**
! 156: * Convert a hex encoded in a binary chunk.
! 157: *
! 158: * If buf is supplied, it must hold at least (hex.len / 2) + (hex.len % 2)
! 159: * bytes. It is filled by the right to give correct values for short inputs.
! 160: *
! 161: * @param hex hex encoded input data
! 162: * @param buf buffer to write decoded data, NULL to malloc
! 163: * @return converted data
! 164: */
! 165: chunk_t chunk_from_hex(chunk_t hex, char *buf);
! 166:
! 167: /**
! 168: * Convert a chunk of data to its base64 encoding.
! 169: *
! 170: * The resulting string is '\\0' terminated, but the chunk does not include
! 171: * the '\\0'. If buf is supplied, it must hold at least (chunk.len * 4 / 3 + 1).
! 172: *
! 173: * @param chunk data to convert
! 174: * @param buf buffer to write to, NULL to malloc
! 175: * @return chunk of encoded data
! 176: */
! 177: chunk_t chunk_to_base64(chunk_t chunk, char *buf);
! 178:
! 179: /**
! 180: * Convert a base64 in a binary chunk.
! 181: *
! 182: * If buf is supplied, it must hold at least (base64.len / 4 * 3).
! 183: *
! 184: * @param base64 base64 encoded input data
! 185: * @param buf buffer to write decoded data, NULL to malloc
! 186: * @return converted data
! 187: */
! 188: chunk_t chunk_from_base64(chunk_t base64, char *buf);
! 189:
! 190: /**
! 191: * Convert a chunk of data to its base32 encoding.
! 192: *
! 193: * The resulting string is '\\0' terminated, but the chunk does not include
! 194: * the '\\0'. If buf is supplied, it must hold (chunk.len * 8 / 5 + 1) bytes.
! 195: *
! 196: * @param chunk data to convert
! 197: * @param buf buffer to write to, NULL to malloc
! 198: * @return chunk of encoded data
! 199: */
! 200: chunk_t chunk_to_base32(chunk_t chunk, char *buf);
! 201:
! 202: /**
! 203: * Free contents of a chunk
! 204: */
! 205: static inline void chunk_free(chunk_t *chunk)
! 206: {
! 207: free(chunk->ptr);
! 208: *chunk = chunk_empty;
! 209: }
! 210:
! 211: /**
! 212: * Overwrite the contents of a chunk and free it
! 213: */
! 214: static inline void chunk_clear(chunk_t *chunk)
! 215: {
! 216: if (chunk->ptr)
! 217: {
! 218: memwipe(chunk->ptr, chunk->len);
! 219: chunk_free(chunk);
! 220: }
! 221: }
! 222:
! 223: /**
! 224: * Initialize a chunk using a char array
! 225: */
! 226: #define chunk_from_chars(...) ((chunk_t){(u_char[]){__VA_ARGS__}, sizeof((u_char[]){__VA_ARGS__})})
! 227:
! 228: /**
! 229: * Initialize a chunk to point to a thing
! 230: */
! 231: #define chunk_from_thing(thing) chunk_create((u_char*)&(thing), sizeof(thing))
! 232:
! 233: /**
! 234: * Initialize a chunk from a string, not containing 0-terminator
! 235: */
! 236: #define chunk_from_str(str) ({char *x = (str); chunk_create((u_char*)x, strlen(x));})
! 237:
! 238: /**
! 239: * Allocate a chunk on the heap
! 240: */
! 241: #define chunk_alloc(bytes) ({size_t x = (bytes); chunk_create(x ? malloc(x) : NULL, x);})
! 242:
! 243: /**
! 244: * Allocate a chunk on the stack
! 245: */
! 246: #define chunk_alloca(bytes) ({size_t x = (bytes); chunk_create(x ? alloca(x) : NULL, x);})
! 247:
! 248: /**
! 249: * Clone a chunk on heap
! 250: */
! 251: #define chunk_clone(chunk) ({chunk_t x = (chunk); chunk_create_clone(x.len ? malloc(x.len) : NULL, x);})
! 252:
! 253: /**
! 254: * Clone a chunk on stack
! 255: */
! 256: #define chunk_clonea(chunk) ({chunk_t x = (chunk); chunk_create_clone(x.len ? alloca(x.len) : NULL, x);})
! 257:
! 258: /**
! 259: * Concatenate chunks into a chunk on heap
! 260: */
! 261: #define chunk_cat(mode, ...) chunk_create_cat(malloc(chunk_length(mode, __VA_ARGS__)), mode, __VA_ARGS__)
! 262:
! 263: /**
! 264: * Concatenate chunks into a chunk on stack
! 265: */
! 266: #define chunk_cata(mode, ...) chunk_create_cat(alloca(chunk_length(mode, __VA_ARGS__)), mode, __VA_ARGS__)
! 267:
! 268: /**
! 269: * Skip n bytes in chunk (forward pointer, shorten length)
! 270: */
! 271: static inline chunk_t chunk_skip(chunk_t chunk, size_t bytes)
! 272: {
! 273: if (chunk.len > bytes)
! 274: {
! 275: chunk.ptr += bytes;
! 276: chunk.len -= bytes;
! 277: return chunk;
! 278: }
! 279: return chunk_empty;
! 280: }
! 281:
! 282: /**
! 283: * Skip any leading zero-valued bytes
! 284: */
! 285: static inline chunk_t chunk_skip_zero(chunk_t chunk)
! 286: {
! 287: while (chunk.len > 1 && *chunk.ptr == 0x00)
! 288: {
! 289: chunk.ptr++;
! 290: chunk.len--;
! 291: }
! 292: return chunk;
! 293: }
! 294:
! 295: /**
! 296: * Copy the data from src to dst, left-padded with chr if dst is longer,
! 297: * otherwise data is copied truncated on the left.
! 298: *
! 299: * @param dst data is copied here
! 300: * @param src data is copied from here
! 301: * @param chr value to use for padding if necessary
! 302: * @return the destination chunk
! 303: */
! 304: chunk_t chunk_copy_pad(chunk_t dst, chunk_t src, u_char chr);
! 305:
! 306: /**
! 307: * Compare two chunks, returns zero if a equals b
! 308: * or negative/positive if a is small/greater than b
! 309: */
! 310: int chunk_compare(chunk_t a, chunk_t b);
! 311:
! 312: /**
! 313: * Compare two chunks for equality,
! 314: * NULL chunks are never equal.
! 315: */
! 316: static inline bool chunk_equals(chunk_t a, chunk_t b)
! 317: {
! 318: return a.ptr != NULL && b.ptr != NULL &&
! 319: a.len == b.len && memeq(a.ptr, b.ptr, a.len);
! 320: }
! 321:
! 322: /**
! 323: * Compare two chunks for equality, constant time for cryptographic purposes.
! 324: *
! 325: * Note that this function is constant time only for chunks with the same
! 326: * length, i.e. it does not protect against guessing the length of one of the
! 327: * chunks.
! 328: */
! 329: static inline bool chunk_equals_const(chunk_t a, chunk_t b)
! 330: {
! 331: return a.ptr != NULL && b.ptr != NULL &&
! 332: a.len == b.len && memeq_const(a.ptr, b.ptr, a.len);
! 333: }
! 334:
! 335: /**
! 336: * Compare two chunks (given as pointers) for equality (useful as callback),
! 337: * NULL chunks are never equal.
! 338: */
! 339: static inline bool chunk_equals_ptr(chunk_t *a, chunk_t *b)
! 340: {
! 341: return a != NULL && b != NULL && chunk_equals(*a, *b);
! 342: }
! 343:
! 344: /**
! 345: * Increment a chunk, as it would represent a network order integer.
! 346: *
! 347: * @param chunk chunk to increment
! 348: * @return TRUE if an overflow occurred
! 349: */
! 350: bool chunk_increment(chunk_t chunk);
! 351:
! 352: /**
! 353: * Check if a chunk has printable characters only.
! 354: *
! 355: * If sane is given, chunk is cloned into sane and all non printable characters
! 356: * get replaced by "replace".
! 357: *
! 358: * @param chunk chunk to check for printability
! 359: * @param sane pointer where sane version is allocated, or NULL
! 360: * @param replace character to use for replacing unprintable characters
! 361: * @return TRUE if all characters in chunk are printable
! 362: */
! 363: bool chunk_printable(chunk_t chunk, chunk_t *sane, char replace);
! 364:
! 365: /**
! 366: * Seed initial key for chunk_hash().
! 367: *
! 368: * This call should get invoked once during startup. This is usually done
! 369: * by calling library_init(). Calling it multiple times is safe, it gets
! 370: * executed just once.
! 371: */
! 372: void chunk_hash_seed();
! 373:
! 374: /**
! 375: * Computes a 32 bit hash of the given chunk.
! 376: *
! 377: * @note The output of this function is randomized, that is, it will only
! 378: * produce the same output for the same input when calling it from the same
! 379: * process. For a more predictable hash function use chunk_hash_static()
! 380: * instead.
! 381: *
! 382: * @note This hash is only intended for hash tables not for cryptographic
! 383: * purposes.
! 384: *
! 385: * @param chunk data to hash
! 386: * @return hash value
! 387: */
! 388: uint32_t chunk_hash(chunk_t chunk);
! 389:
! 390: /**
! 391: * Incremental version of chunk_hash. Use this to hash two or more chunks.
! 392: *
! 393: * @param chunk data to hash
! 394: * @param hash previous hash value
! 395: * @return hash value
! 396: */
! 397: uint32_t chunk_hash_inc(chunk_t chunk, uint32_t hash);
! 398:
! 399: /**
! 400: * Computes a 32 bit hash of the given chunk.
! 401: *
! 402: * Compared to chunk_hash() this will always calculate the same output for the
! 403: * same input. Therefore, it should not be used for hash tables (to prevent
! 404: * hash flooding).
! 405: *
! 406: * @note This hash is not intended for cryptographic purposes.
! 407: *
! 408: * @param chunk data to hash
! 409: * @return hash value
! 410: */
! 411: uint32_t chunk_hash_static(chunk_t chunk);
! 412:
! 413: /**
! 414: * Incremental version of chunk_hash_static(). Use this to hash two or more
! 415: * chunks in a predictable way.
! 416: *
! 417: * @param chunk data to hash
! 418: * @param hash previous hash value
! 419: * @return hash value
! 420: */
! 421: uint32_t chunk_hash_static_inc(chunk_t chunk, uint32_t hash);
! 422:
! 423: /**
! 424: * Computes a quick MAC from the given chunk and key using SipHash.
! 425: *
! 426: * The key must have a length of 128-bit (16 bytes).
! 427: *
! 428: * @note While SipHash has strong features using it for cryptographic purposes
! 429: * is not recommended (in particular because of the rather short output size).
! 430: *
! 431: * @param chunk data to process
! 432: * @param key key to use
! 433: * @return MAC for given input and key
! 434: */
! 435: uint64_t chunk_mac(chunk_t chunk, u_char *key);
! 436:
! 437: /**
! 438: * Calculate the Internet Checksum according to RFC 1071 for the given chunk.
! 439: *
! 440: * If the result is used with chunk_internet_checksum_inc() and the data length
! 441: * is not a multiple of 16 bit the checksum bytes have to be swapped to
! 442: * compensate the even/odd alignment.
! 443: *
! 444: * @param data data to process
! 445: * @return checksum (one's complement, network order)
! 446: */
! 447: uint16_t chunk_internet_checksum(chunk_t data);
! 448:
! 449: /**
! 450: * Extend the given Internet Checksum (one's complement, in network byte order)
! 451: * with the given data.
! 452: *
! 453: * If data is not a multiple of 16 bits the checksum may have to be swapped to
! 454: * compensate even/odd alignment (see chunk_internet_checksum()).
! 455: *
! 456: * @param data data to process
! 457: * @param checksum previous checksum (one's complement, network order)
! 458: * @return checksum (one's complement, network order)
! 459: */
! 460: uint16_t chunk_internet_checksum_inc(chunk_t data, uint16_t checksum);
! 461:
! 462: /**
! 463: * printf hook function for chunk_t.
! 464: *
! 465: * Arguments are:
! 466: * chunk_t *chunk
! 467: * Use #-modifier to print a compact version
! 468: * Use +-modifier to print a compact version without separator
! 469: */
! 470: int chunk_printf_hook(printf_hook_data_t *data, printf_hook_spec_t *spec,
! 471: const void *const *args);
! 472:
! 473: #endif /** CHUNK_H_ @}*/
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to chunk.h CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / strongswan / src / libstrongswan / utils