1 /* 2 * Copyright (c) 2018 Thomas Pornin <pornin@bolet.org> 3 * 4 * Permission is hereby granted, free of charge, to any person obtaining 5 * a copy of this software and associated documentation files (the 6 * "Software"), to deal in the Software without restriction, including 7 * without limitation the rights to use, copy, modify, merge, publish, 8 * distribute, sublicense, and/or sell copies of the Software, and to 9 * permit persons to whom the Software is furnished to do so, subject to 10 * the following conditions: 11 * 12 * The above copyright notice and this permission notice shall be 13 * included in all copies or substantial portions of the Software. 14 * 15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 16 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 17 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 18 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS 19 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN 20 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 21 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 22 * SOFTWARE. 23 */ 24 25 #ifndef BR_BEARSSL_KDF_H__ 26 #define BR_BEARSSL_KDF_H__ 27 28 #include <stddef.h> 29 #include <stdint.h> 30 31 #include "bearssl_hash.h" 32 #include "bearssl_hmac.h" 33 34 #ifdef __cplusplus 35 extern "C" { 36 #endif 37 38 /** \file bearssl_kdf.h 39 * 40 * # Key Derivation Functions 41 * 42 * KDF are functions that takes a variable length input, and provide a 43 * variable length output, meant to be used to derive subkeys from a 44 * master key. 45 * 46 * ## HKDF 47 * 48 * HKDF is a KDF defined by [RFC 5869](https://tools.ietf.org/html/rfc5869). 49 * It is based on HMAC, itself using an underlying hash function. Any 50 * hash function can be used, as long as it is compatible with the rules 51 * for the HMAC implementation (i.e. output size is 64 bytes or less, hash 52 * internal state size is 64 bytes or less, and the internal block length is 53 * a power of 2 between 16 and 256 bytes). HKDF has two phases: 54 * 55 * - HKDF-Extract: the input data in ingested, along with a "salt" value. 56 * 57 * - HKDF-Expand: the output is produced, from the result of processing 58 * the input and salt, and using an extra non-secret parameter called 59 * "info". 60 * 61 * The "salt" and "info" strings are non-secret and can be empty. Their role 62 * is normally to bind the input and output, respectively, to conventional 63 * identifiers that qualifu them within the used protocol or application. 64 * 65 * The implementation defined in this file uses the following functions: 66 * 67 * - `br_hkdf_init()`: initialize an HKDF context, with a hash function, 68 * and the salt. This starts the HKDF-Extract process. 69 * 70 * - `br_hkdf_inject()`: inject more input bytes. This function may be 71 * called repeatedly if the input data is provided by chunks. 72 * 73 * - `br_hkdf_flip()`: end the HKDF-Extract process, and start the 74 * HKDF-Expand process. 75 * 76 * - `br_hkdf_produce()`: get the next bytes of output. This function 77 * may be called several times to obtain the full output by chunks. 78 * For correct HKDF processing, the same "info" string must be 79 * provided for each call. 80 * 81 * Note that the HKDF total output size (the number of bytes that 82 * HKDF-Expand is willing to produce) is limited: if the hash output size 83 * is _n_ bytes, then the maximum output size is _255*n_. 84 * 85 * ## SHAKE 86 * 87 * SHAKE is defined in 88 * [FIPS 202](https://csrc.nist.gov/publications/detail/fips/202/final) 89 * under two versions: SHAKE128 and SHAKE256, offering an alleged 90 * "security level" of 128 and 256 bits, respectively (SHAKE128 is 91 * about 20 to 25% faster than SHAKE256). SHAKE internally relies on 92 * the Keccak family of sponge functions, not on any externally provided 93 * hash function. Contrary to HKDF, SHAKE does not have a concept of 94 * either a "salt" or an "info" string. The API consists in four 95 * functions: 96 * 97 * - `br_shake_init()`: initialize a SHAKE context for a given 98 * security level. 99 * 100 * - `br_shake_inject()`: inject more input bytes. This function may be 101 * called repeatedly if the input data is provided by chunks. 102 * 103 * - `br_shake_flip()`: end the data injection process, and start the 104 * data production process. 105 * 106 * - `br_shake_produce()`: get the next bytes of output. This function 107 * may be called several times to obtain the full output by chunks. 108 */ 109 110 /** 111 * \brief HKDF context. 112 * 113 * The HKDF context is initialized with a hash function implementation 114 * and a salt value. Contents are opaque (callers should not access them 115 * directly). The caller is responsible for allocating the context where 116 * appropriate. Context initialisation and usage incurs no dynamic 117 * allocation, so there is no release function. 118 */ 119 typedef struct { 120 #ifndef BR_DOXYGEN_IGNORE 121 union { 122 br_hmac_context hmac_ctx; 123 br_hmac_key_context prk_ctx; 124 } u; 125 unsigned char buf[64]; 126 size_t ptr; 127 size_t dig_len; 128 unsigned chunk_num; 129 #endif 130 } br_hkdf_context; 131 132 /** 133 * \brief HKDF context initialization. 134 * 135 * The underlying hash function and salt value are provided. Arbitrary 136 * salt lengths can be used. 137 * 138 * HKDF makes a difference between a salt of length zero, and an 139 * absent salt (the latter being equivalent to a salt consisting of 140 * bytes of value zero, of the same length as the hash function output). 141 * If `salt_len` is zero, then this function assumes that the salt is 142 * present but of length zero. To specify an _absent_ salt, use 143 * `BR_HKDF_NO_SALT` as `salt` parameter (`salt_len` is then ignored). 144 * 145 * \param hc HKDF context to initialise. 146 * \param digest_vtable pointer to the hash function implementation vtable. 147 * \param salt HKDF-Extract salt. 148 * \param salt_len HKDF-Extract salt length (in bytes). 149 */ 150 void br_hkdf_init(br_hkdf_context *hc, const br_hash_class *digest_vtable, 151 const void *salt, size_t salt_len); 152 153 /** 154 * \brief The special "absent salt" value for HKDF. 155 */ 156 #define BR_HKDF_NO_SALT (&br_hkdf_no_salt) 157 158 #ifndef BR_DOXYGEN_IGNORE 159 extern const unsigned char br_hkdf_no_salt; 160 #endif 161 162 /** 163 * \brief HKDF input injection (HKDF-Extract). 164 * 165 * This function injects some more input bytes ("key material") into 166 * HKDF. This function may be called several times, after `br_hkdf_init()` 167 * but before `br_hkdf_flip()`. 168 * 169 * \param hc HKDF context. 170 * \param ikm extra input bytes. 171 * \param ikm_len number of extra input bytes. 172 */ 173 void br_hkdf_inject(br_hkdf_context *hc, const void *ikm, size_t ikm_len); 174 175 /** 176 * \brief HKDF switch to the HKDF-Expand phase. 177 * 178 * This call terminates the HKDF-Extract process (input injection), and 179 * starts the HKDF-Expand process (output production). 180 * 181 * \param hc HKDF context. 182 */ 183 void br_hkdf_flip(br_hkdf_context *hc); 184 185 /** 186 * \brief HKDF output production (HKDF-Expand). 187 * 188 * Produce more output bytes from the current state. This function may be 189 * called several times, but only after `br_hkdf_flip()`. 190 * 191 * Returned value is the number of actually produced bytes. The total 192 * output length is limited to 255 times the output length of the 193 * underlying hash function. 194 * 195 * \param hc HKDF context. 196 * \param info application specific information string. 197 * \param info_len application specific information string length (in bytes). 198 * \param out destination buffer for the HKDF output. 199 * \param out_len the length of the requested output (in bytes). 200 * \return the produced output length (in bytes). 201 */ 202 size_t br_hkdf_produce(br_hkdf_context *hc, 203 const void *info, size_t info_len, void *out, size_t out_len); 204 205 /** 206 * \brief SHAKE context. 207 * 208 * The HKDF context is initialized with a "security level". The internal 209 * notion is called "capacity"; the capacity is twice the security level 210 * (for instance, SHAKE128 has capacity 256). 211 * 212 * The caller is responsible for allocating the context where 213 * appropriate. Context initialisation and usage incurs no dynamic 214 * allocation, so there is no release function. 215 */ 216 typedef struct { 217 #ifndef BR_DOXYGEN_IGNORE 218 unsigned char dbuf[200]; 219 size_t dptr; 220 size_t rate; 221 uint64_t A[25]; 222 #endif 223 } br_shake_context; 224 225 /** 226 * \brief SHAKE context initialization. 227 * 228 * The context is initialized for the provided "security level". 229 * Internally, this sets the "capacity" to twice the security level; 230 * thus, for SHAKE128, the `security_level` parameter should be 128, 231 * which corresponds to a 256-bit capacity. 232 * 233 * Allowed security levels are all multiples of 32, from 32 to 768, 234 * inclusive. Larger security levels imply lower performance; levels 235 * beyond 256 bits don't make much sense. Standard levels are 128 236 * and 256 bits (for SHAKE128 and SHAKE256, respectively). 237 * 238 * \param sc SHAKE context to initialise. 239 * \param security_level security level (in bits). 240 */ 241 void br_shake_init(br_shake_context *sc, int security_level); 242 243 /** 244 * \brief SHAKE input injection. 245 * 246 * This function injects some more input bytes ("key material") into 247 * SHAKE. This function may be called several times, after `br_shake_init()` 248 * but before `br_shake_flip()`. 249 * 250 * \param sc SHAKE context. 251 * \param data extra input bytes. 252 * \param len number of extra input bytes. 253 */ 254 void br_shake_inject(br_shake_context *sc, const void *data, size_t len); 255 256 /** 257 * \brief SHAKE switch to production phase. 258 * 259 * This call terminates the input injection process, and starts the 260 * output production process. 261 * 262 * \param sc SHAKE context. 263 */ 264 void br_shake_flip(br_shake_context *hc); 265 266 /** 267 * \brief SHAKE output production. 268 * 269 * Produce more output bytes from the current state. This function may be 270 * called several times, but only after `br_shake_flip()`. 271 * 272 * There is no practical limit to the number of bytes that may be produced. 273 * 274 * \param sc SHAKE context. 275 * \param out destination buffer for the SHAKE output. 276 * \param len the length of the requested output (in bytes). 277 */ 278 void br_shake_produce(br_shake_context *sc, void *out, size_t len); 279 280 #ifdef __cplusplus 281 } 282 #endif 283 284 #endif 285