include/sodium/utils.h

0001
0002 #ifndef sodium_utils_H
0003 #define sodium_utils_H
0004
0005 #include <limits.h>
0006 #include <stddef.h>
0007 #include <stdint.h>
0008
0009 #include "export.h"
0010
0011 #ifdef __cplusplus
0012 extern "C" {
0013 #endif
0014
0015 #ifndef SODIUM_C99
0016 # if defined(__cplusplus) || !defined(__STDC_VERSION__) || __STDC_VERSION__ < 199901L
0017 #  define SODIUM_C99(X)
0018 # else
0019 #  define SODIUM_C99(X) X
0020 # endif
0021 #endif
0022
0023 SODIUM_EXPORT
0024 void sodium_memzero(void *const pnt, const size_t len);
0025
0026 SODIUM_EXPORT
0027 void sodium_stackzero(const size_t len);
0028
0029 /*
0030  * WARNING: sodium_memcmp() must be used to verify if two secret keys
0031  * are equal, in constant time.
0032  * It returns 0 if the keys are equal, and -1 if they differ.
0033  * This function is not designed for lexicographical comparisons.
0034  */
0035 SODIUM_EXPORT
0036 int sodium_memcmp(const void *const b1_, const void *const b2_, size_t len)
0037     __attribute__((warn_unused_result));
0038
0039 /*
0040  * sodium_compare() returns -1 if b1_ < b2_, 1 if b1_ > b2_ and 0 if b1_ == b2_
0041  * It is suitable for lexicographical comparisons, or to compare nonces
0042  * and counters stored in little-endian format.
0043  * However, it is slower than sodium_memcmp().
0044  */
0045 SODIUM_EXPORT
0046 int sodium_compare(const unsigned char *b1_, const unsigned char *b2_, size_t len)
0047     __attribute__((warn_unused_result));
0048
0049 SODIUM_EXPORT
0050 int sodium_is_zero(const unsigned char *n, const size_t nlen);
0051
0052 SODIUM_EXPORT
0053 void sodium_increment(unsigned char *n, const size_t nlen);
0054
0055 SODIUM_EXPORT
0056 void sodium_add(unsigned char *a, const unsigned char *b, const size_t len);
0057
0058 SODIUM_EXPORT
0059 void sodium_sub(unsigned char *a, const unsigned char *b, const size_t len);
0060
0061 SODIUM_EXPORT
0062 char *sodium_bin2hex(char *const hex, const size_t hex_maxlen, const unsigned char *const bin,
0063                      const size_t bin_len) __attribute__((nonnull(1)));
0064
0065 SODIUM_EXPORT
0066 int sodium_hex2bin(unsigned char *const bin, const size_t bin_maxlen, const char *const hex,
0067                    const size_t hex_len, const char *const ignore, size_t *const bin_len,
0068                    const char **const hex_end) __attribute__((nonnull(1)));
0069
0070 #define sodium_base64_VARIANT_ORIGINAL            1
0071 #define sodium_base64_VARIANT_ORIGINAL_NO_PADDING 3
0072 #define sodium_base64_VARIANT_URLSAFE             5
0073 #define sodium_base64_VARIANT_URLSAFE_NO_PADDING  7
0074
0075 /*
0076  * Computes the required length to encode BIN_LEN bytes as a base64 string
0077  * using the given variant. The computed length includes a trailing \0.
0078  */
0079 #define sodium_base64_ENCODED_LEN(BIN_LEN, VARIANT)                            \
0080   ((BIN_LEN) / 3U > (SIZE_MAX - 5) / 4U                                        \
0081        ? (size_t)SIZE_MAX                                                      \
0082        : (((BIN_LEN) / 3U) * 4U +                                              \
0083           ((((BIN_LEN) - ((BIN_LEN) / 3U) * 3U) |                              \
0084             (((BIN_LEN) - ((BIN_LEN) / 3U) * 3U) >> 1)) &                      \
0085            1U) *                                                               \
0086               (4U - ((0U - (((VARIANT) & 2U) >> 1)) &                          \
0087                      (3U - ((BIN_LEN) - ((BIN_LEN) / 3U) * 3U)))) +            \
0088           1U))
0089
0090 SODIUM_EXPORT
0091 size_t sodium_base64_encoded_len(const size_t bin_len, const int variant);
0092
0093 SODIUM_EXPORT
0094 char *sodium_bin2base64(char *const b64, const size_t b64_maxlen, const unsigned char *const bin,
0095                         const size_t bin_len, const int variant) __attribute__((nonnull(1)));
0096
0097 SODIUM_EXPORT
0098 int sodium_base642bin(unsigned char *const bin, const size_t bin_maxlen, const char *const b64,
0099                       const size_t b64_len, const char *const ignore, size_t *const bin_len,
0100                       const char **const b64_end, const int variant) __attribute__((nonnull(1)));
0101
0102 SODIUM_EXPORT
0103 int sodium_ip2bin(unsigned char bin[16], const char *ip, size_t ip_len_)
0104     __attribute__((warn_unused_result)) __attribute__((nonnull));
0105
0106 SODIUM_EXPORT
0107 char *sodium_bin2ip(char *ip, size_t ip_maxlen, const unsigned char bin[16])
0108     __attribute__((nonnull));
0109
0110 SODIUM_EXPORT
0111 int sodium_mlock(void *const addr, const size_t len) __attribute__((nonnull));
0112
0113 SODIUM_EXPORT
0114 int sodium_munlock(void *const addr, const size_t len) __attribute__((nonnull));
0115
0116 /* WARNING: sodium_malloc() and sodium_allocarray() are not general-purpose
0117  * allocation functions.
0118  *
0119  * They return a pointer to a region filled with 0xd0 bytes, immediately
0120  * followed by a guard page. As a result, accessing a single byte after the
0121  * requested allocation size will intentionally trigger a segmentation fault.
0122  *
0123  * A canary and an additional guard page placed before the beginning of the
0124  * region may also kill the process if a buffer underflow is detected.
0125  *
0126  * The memory layout is:
0127  * [unprotected region size (read only)][guard page (no access)][unprotected pages
0128  * (read/write)][guard page (no access)]
0129  *
0130  * The layout of the unprotected pages is:
0131  * [optional padding][16-bytes canary][user region]
0132  *
0133  * Important limitations:
0134  * - These functions are significantly slower than standard allocation functions.
0135  * - Each allocation requires 3 or 4 additional pages.
0136  * - The returned address will not be aligned if the allocation size is not
0137  *   a multiple of the required alignment. For this reason, these functions
0138  *   are designed to store data such as secret keys and messages.
0139  *
0140  * sodium_malloc() can be used to allocate any libsodium data structure.
0141  *
0142  * The crypto_generichash_state structure is packed and its length is
0143  * either 357 or 361 bytes. When using sodium_malloc() to allocate a
0144  * crypto_generichash_state structure, padding must be added to ensure
0145  * proper alignment. Use crypto_generichash_statebytes() rather than sizeof():
0146  *
0147  *     state = sodium_malloc(crypto_generichash_statebytes());
0148  */
0149
0150 SODIUM_EXPORT
0151 void *sodium_malloc(const size_t size) __attribute__((malloc));
0152
0153 SODIUM_EXPORT
0154 void *sodium_allocarray(size_t count, size_t size) __attribute__((malloc));
0155
0156 SODIUM_EXPORT
0157 void sodium_free(void *ptr);
0158
0159 SODIUM_EXPORT
0160 int sodium_mprotect_noaccess(void *ptr) __attribute__((nonnull));
0161
0162 SODIUM_EXPORT
0163 int sodium_mprotect_readonly(void *ptr) __attribute__((nonnull));
0164
0165 SODIUM_EXPORT
0166 int sodium_mprotect_readwrite(void *ptr) __attribute__((nonnull));
0167
0168 SODIUM_EXPORT
0169 int sodium_pad(size_t *padded_buflen_p, unsigned char *buf, size_t unpadded_buflen,
0170                size_t blocksize, size_t max_buflen) __attribute__((nonnull(2)));
0171
0172 SODIUM_EXPORT
0173 int sodium_unpad(size_t *unpadded_buflen_p, const unsigned char *buf, size_t padded_buflen,
0174                  size_t blocksize) __attribute__((nonnull(2)));
0175
0176 /* -------- */
0177
0178 int _sodium_alloc_init(void);
0179
0180 #ifdef __cplusplus
0181 }
0182 #endif
0183
0184 #endif