utils.h (6150B)
1 2 #ifndef sodium_utils_H 3 #define sodium_utils_H 4 5 #include <stddef.h> 6 7 #include "export.h" 8 9 #ifdef __cplusplus 10 extern "C" { 11 #endif 12 13 #ifndef SODIUM_C99 14 # if defined(__cplusplus) || !defined(__STDC_VERSION__) || __STDC_VERSION__ < 199901L 15 # define SODIUM_C99(X) 16 # else 17 # define SODIUM_C99(X) X 18 # endif 19 #endif 20 21 SODIUM_EXPORT 22 void sodium_memzero(void * const pnt, const size_t len); 23 24 SODIUM_EXPORT 25 void sodium_stackzero(const size_t len); 26 27 /* 28 * WARNING: sodium_memcmp() must be used to verify if two secret keys 29 * are equal, in constant time. 30 * It returns 0 if the keys are equal, and -1 if they differ. 31 * This function is not designed for lexicographical comparisons. 32 */ 33 SODIUM_EXPORT 34 int sodium_memcmp(const void * const b1_, const void * const b2_, size_t len) 35 __attribute__ ((warn_unused_result)); 36 37 /* 38 * sodium_compare() returns -1 if b1_ < b2_, 1 if b1_ > b2_ and 0 if b1_ == b2_ 39 * It is suitable for lexicographical comparisons, or to compare nonces 40 * and counters stored in little-endian format. 41 * However, it is slower than sodium_memcmp(). 42 */ 43 SODIUM_EXPORT 44 int sodium_compare(const unsigned char *b1_, const unsigned char *b2_, 45 size_t len) __attribute__ ((warn_unused_result)); 46 47 SODIUM_EXPORT 48 int sodium_is_zero(const unsigned char *n, const size_t nlen); 49 50 SODIUM_EXPORT 51 void sodium_increment(unsigned char *n, const size_t nlen); 52 53 SODIUM_EXPORT 54 void sodium_add(unsigned char *a, const unsigned char *b, const size_t len); 55 56 SODIUM_EXPORT 57 void sodium_sub(unsigned char *a, const unsigned char *b, const size_t len); 58 59 SODIUM_EXPORT 60 char *sodium_bin2hex(char * const hex, const size_t hex_maxlen, 61 const unsigned char * const bin, const size_t bin_len) 62 __attribute__ ((nonnull(1))); 63 64 SODIUM_EXPORT 65 int sodium_hex2bin(unsigned char * const bin, const size_t bin_maxlen, 66 const char * const hex, const size_t hex_len, 67 const char * const ignore, size_t * const bin_len, 68 const char ** const hex_end) 69 __attribute__ ((nonnull(1))); 70 71 #define sodium_base64_VARIANT_ORIGINAL 1 72 #define sodium_base64_VARIANT_ORIGINAL_NO_PADDING 3 73 #define sodium_base64_VARIANT_URLSAFE 5 74 #define sodium_base64_VARIANT_URLSAFE_NO_PADDING 7 75 76 /* 77 * Computes the required length to encode BIN_LEN bytes as a base64 string 78 * using the given variant. The computed length includes a trailing \0. 79 */ 80 #define sodium_base64_ENCODED_LEN(BIN_LEN, VARIANT) \ 81 (((BIN_LEN) / 3U) * 4U + \ 82 ((((BIN_LEN) - ((BIN_LEN) / 3U) * 3U) | (((BIN_LEN) - ((BIN_LEN) / 3U) * 3U) >> 1)) & 1U) * \ 83 (4U - (~((((VARIANT) & 2U) >> 1) - 1U) & (3U - ((BIN_LEN) - ((BIN_LEN) / 3U) * 3U)))) + 1U) 84 85 SODIUM_EXPORT 86 size_t sodium_base64_encoded_len(const size_t bin_len, const int variant); 87 88 SODIUM_EXPORT 89 char *sodium_bin2base64(char * const b64, const size_t b64_maxlen, 90 const unsigned char * const bin, const size_t bin_len, 91 const int variant) __attribute__ ((nonnull(1))); 92 93 SODIUM_EXPORT 94 int sodium_base642bin(unsigned char * const bin, const size_t bin_maxlen, 95 const char * const b64, const size_t b64_len, 96 const char * const ignore, size_t * const bin_len, 97 const char ** const b64_end, const int variant) 98 __attribute__ ((nonnull(1))); 99 100 SODIUM_EXPORT 101 int sodium_mlock(void * const addr, const size_t len) 102 __attribute__ ((nonnull)); 103 104 SODIUM_EXPORT 105 int sodium_munlock(void * const addr, const size_t len) 106 __attribute__ ((nonnull)); 107 108 /* WARNING: sodium_malloc() and sodium_allocarray() are not general-purpose 109 * allocation functions. 110 * 111 * They return a pointer to a region filled with 0xd0 bytes, immediately 112 * followed by a guard page. 113 * As a result, accessing a single byte after the requested allocation size 114 * will intentionally trigger a segmentation fault. 115 * 116 * A canary and an additional guard page placed before the beginning of the 117 * region may also kill the process if a buffer underflow is detected. 118 * 119 * The memory layout is: 120 * [unprotected region size (read only)][guard page (no access)][unprotected pages (read/write)][guard page (no access)] 121 * With the layout of the unprotected pages being: 122 * [optional padding][16-bytes canary][user region] 123 * 124 * However: 125 * - These functions are significantly slower than standard functions 126 * - Each allocation requires 3 or 4 additional pages 127 * - The returned address will not be aligned if the allocation size is not 128 * a multiple of the required alignment. For this reason, these functions 129 * are designed to store data, such as secret keys and messages. 130 * 131 * sodium_malloc() can be used to allocate any libsodium data structure. 132 * 133 * The crypto_generichash_state structure is packed and its length is 134 * either 357 or 361 bytes. For this reason, when using sodium_malloc() to 135 * allocate a crypto_generichash_state structure, padding must be added in 136 * order to ensure proper alignment. crypto_generichash_statebytes() 137 * returns the rounded up structure size, and should be preferred to sizeof(): 138 * state = sodium_malloc(crypto_generichash_statebytes()); 139 */ 140 141 SODIUM_EXPORT 142 void *sodium_malloc(const size_t size) 143 __attribute__ ((malloc)); 144 145 SODIUM_EXPORT 146 void *sodium_allocarray(size_t count, size_t size) 147 __attribute__ ((malloc)); 148 149 SODIUM_EXPORT 150 void sodium_free(void *ptr); 151 152 SODIUM_EXPORT 153 int sodium_mprotect_noaccess(void *ptr) __attribute__ ((nonnull)); 154 155 SODIUM_EXPORT 156 int sodium_mprotect_readonly(void *ptr) __attribute__ ((nonnull)); 157 158 SODIUM_EXPORT 159 int sodium_mprotect_readwrite(void *ptr) __attribute__ ((nonnull)); 160 161 SODIUM_EXPORT 162 int sodium_pad(size_t *padded_buflen_p, unsigned char *buf, 163 size_t unpadded_buflen, size_t blocksize, size_t max_buflen) 164 __attribute__ ((nonnull(2))); 165 166 SODIUM_EXPORT 167 int sodium_unpad(size_t *unpadded_buflen_p, const unsigned char *buf, 168 size_t padded_buflen, size_t blocksize) 169 __attribute__ ((nonnull(2))); 170 171 /* -------- */ 172 173 int _sodium_alloc_init(void); 174 175 #ifdef __cplusplus 176 } 177 #endif 178 179 #endif