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) 46 __attribute__ ((warn_unused_result)); 47 48 SODIUM_EXPORT 49 int sodium_is_zero(const unsigned char *n, const size_t nlen); 50 51 SODIUM_EXPORT 52 void sodium_increment(unsigned char *n, const size_t nlen); 53 54 SODIUM_EXPORT 55 void sodium_add(unsigned char *a, const unsigned char *b, const size_t len); 56 57 SODIUM_EXPORT 58 char *sodium_bin2hex(char * const hex, const size_t hex_maxlen, 59 const unsigned char * const bin, const size_t bin_len); 60 61 SODIUM_EXPORT 62 int sodium_hex2bin(unsigned char * const bin, const size_t bin_maxlen, 63 const char * const hex, const size_t hex_len, 64 const char * const ignore, size_t * const bin_len, 65 const char ** const hex_end); 66 67 #define sodium_base64_VARIANT_ORIGINAL 1 68 #define sodium_base64_VARIANT_ORIGINAL_NO_PADDING 3 69 #define sodium_base64_VARIANT_URLSAFE 5 70 #define sodium_base64_VARIANT_URLSAFE_NO_PADDING 7 71 72 /* 73 * Computes the required length to encode BIN_LEN bytes as a base64 string 74 * using the given variant. The computed length includes a trailing \0. 75 */ 76 #define sodium_base64_ENCODED_LEN(BIN_LEN, VARIANT) \ 77 (((BIN_LEN) / 3U) * 4U + \ 78 ((((BIN_LEN) - ((BIN_LEN) / 3U) * 3U) | (((BIN_LEN) - ((BIN_LEN) / 3U) * 3U) >> 1)) & 1U) * \ 79 (4U - (~((((VARIANT) & 2U) >> 1) - 1U) & (3U - ((BIN_LEN) - ((BIN_LEN) / 3U) * 3U)))) + 1U) 80 81 SODIUM_EXPORT 82 size_t sodium_base64_encoded_len(const size_t bin_len, const int variant); 83 84 SODIUM_EXPORT 85 char *sodium_bin2base64(char * const b64, const size_t b64_maxlen, 86 const unsigned char * const bin, const size_t bin_len, 87 const int variant); 88 89 SODIUM_EXPORT 90 int sodium_base642bin(unsigned char * const bin, const size_t bin_maxlen, 91 const char * const b64, const size_t b64_len, 92 const char * const ignore, size_t * const bin_len, 93 const char ** const b64_end, const int variant); 94 95 SODIUM_EXPORT 96 int sodium_mlock(void * const addr, const size_t len); 97 98 SODIUM_EXPORT 99 int sodium_munlock(void * const addr, const size_t len); 100 101 /* WARNING: sodium_malloc() and sodium_allocarray() are not general-purpose 102 * allocation functions. 103 * 104 * They return a pointer to a region filled with 0xd0 bytes, immediately 105 * followed by a guard page. 106 * As a result, accessing a single byte after the requested allocation size 107 * will intentionally trigger a segmentation fault. 108 * 109 * A canary and an additional guard page placed before the beginning of the 110 * region may also kill the process if a buffer underflow is detected. 111 * 112 * The memory layout is: 113 * [unprotected region size (read only)][guard page (no access)][unprotected pages (read/write)][guard page (no access)] 114 * With the layout of the unprotected pages being: 115 * [optional padding][16-bytes canary][user region] 116 * 117 * However: 118 * - These functions are significantly slower than standard functions 119 * - Each allocation requires 3 or 4 additional pages 120 * - The returned address will not be aligned if the allocation size is not 121 * a multiple of the required alignment. For this reason, these functions 122 * are designed to store data, such as secret keys and messages. 123 * 124 * sodium_malloc() can be used to allocate any libsodium data structure. 125 * 126 * The crypto_generichash_state structure is packed and its length is 127 * either 357 or 361 bytes. For this reason, when using sodium_malloc() to 128 * allocate a crypto_generichash_state structure, padding must be added in 129 * order to ensure proper alignment. crypto_generichash_statebytes() 130 * returns the rounded up structure size, and should be prefered to sizeof(): 131 * state = sodium_malloc(crypto_generichash_statebytes()); 132 */ 133 134 SODIUM_EXPORT 135 void *sodium_malloc(const size_t size) 136 __attribute__ ((malloc)); 137 138 SODIUM_EXPORT 139 void *sodium_allocarray(size_t count, size_t size) 140 __attribute__ ((malloc)); 141 142 SODIUM_EXPORT 143 void sodium_free(void *ptr); 144 145 SODIUM_EXPORT 146 int sodium_mprotect_noaccess(void *ptr); 147 148 SODIUM_EXPORT 149 int sodium_mprotect_readonly(void *ptr); 150 151 SODIUM_EXPORT 152 int sodium_mprotect_readwrite(void *ptr); 153 154 SODIUM_EXPORT 155 int sodium_pad(size_t *padded_buflen_p, unsigned char *buf, 156 size_t unpadded_buflen, size_t blocksize, size_t max_buflen); 157 158 SODIUM_EXPORT 159 int sodium_unpad(size_t *unpadded_buflen_p, const unsigned char *buf, 160 size_t padded_buflen, size_t blocksize); 161 162 /* -------- */ 163 164 int _sodium_alloc_init(void); 165 166 #ifdef __cplusplus 167 } 168 #endif 169 170 #endif 171