1 /* 2 * Copyright (c) 2016 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_RAND_H__ 26 #define BR_BEARSSL_RAND_H__ 27 28 #include <stddef.h> 29 #include <stdint.h> 30 31 #include "bearssl_block.h" 32 #include "bearssl_hash.h" 33 34 #ifdef __cplusplus 35 extern "C" { 36 #endif 37 38 /** \file bearssl_rand.h 39 * 40 * # Pseudo-Random Generators 41 * 42 * A PRNG is a state-based engine that outputs pseudo-random bytes on 43 * demand. It is initialized with an initial seed, and additional seed 44 * bytes can be added afterwards. Bytes produced depend on the seeds and 45 * also on the exact sequence of calls (including sizes requested for 46 * each call). 47 * 48 * 49 * ## Procedural and OOP API 50 * 51 * For the PRNG of name "`xxx`", two API are provided. The _procedural_ 52 * API defined a context structure `br_xxx_context` and three functions: 53 * 54 * - `br_xxx_init()` 55 * 56 * Initialise the context with an initial seed. 57 * 58 * - `br_xxx_generate()` 59 * 60 * Produce some pseudo-random bytes. 61 * 62 * - `br_xxx_update()` 63 * 64 * Inject some additional seed. 65 * 66 * The initialisation function sets the first context field (`vtable`) 67 * to a pointer to the vtable that supports the OOP API. The OOP API 68 * provides access to the same functions through function pointers, 69 * named `init()`, `generate()` and `update()`. 70 * 71 * Note that the context initialisation method may accept additional 72 * parameters, provided as a 'const void *' pointer at API level. These 73 * additional parameters depend on the implemented PRNG. 74 * 75 * 76 * ## HMAC_DRBG 77 * 78 * HMAC_DRBG is defined in [NIST SP 800-90A Revision 79 * 1](http://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-90Ar1.pdf). 80 * It uses HMAC repeatedly, over some configurable underlying hash 81 * function. In BearSSL, it is implemented under the "`hmac_drbg`" name. 82 * The "extra parameters" pointer for context initialisation should be 83 * set to a pointer to the vtable for the underlying hash function (e.g. 84 * pointer to `br_sha256_vtable` to use HMAC_DRBG with SHA-256). 85 * 86 * According to the NIST standard, each request shall produce up to 87 * 2<sup>19</sup> bits (i.e. 64 kB of data); moreover, the context shall 88 * be reseeded at least once every 2<sup>48</sup> requests. This 89 * implementation does not maintain the reseed counter (the threshold is 90 * too high to be reached in practice) and does not object to producing 91 * more than 64 kB in a single request; thus, the code cannot fail, 92 * which corresponds to the fact that the API has no room for error 93 * codes. However, this implies that requesting more than 64 kB in one 94 * `generate()` request, or making more than 2<sup>48</sup> requests 95 * without reseeding, is formally out of NIST specification. There is 96 * no currently known security penalty for exceeding the NIST limits, 97 * and, in any case, HMAC_DRBG usage in implementing SSL/TLS always 98 * stays much below these thresholds. 99 * 100 * 101 * ## AESCTR_DRBG 102 * 103 * AESCTR_DRBG is a custom PRNG based on AES-128 in CTR mode. This is 104 * meant to be used only in situations where you are desperate for 105 * speed, and have an hardware-optimized AES/CTR implementation. Whether 106 * this will yield perceptible improvements depends on what you use the 107 * pseudorandom bytes for, and how many you want; for instance, RSA key 108 * pair generation uses a substantial amount of randomness, and using 109 * AESCTR_DRBG instead of HMAC_DRBG yields a 15 to 20% increase in key 110 * generation speed on a recent x86 CPU (Intel Core i7-6567U at 3.30 GHz). 111 * 112 * Internally, it uses CTR mode with successive counter values, starting 113 * at zero (counter value expressed over 128 bits, big-endian convention). 114 * The counter is not allowed to reach 32768; thus, every 32768*16 bytes 115 * at most, the `update()` function is run (on an empty seed, if none is 116 * provided). The `update()` function computes the new AES-128 key by 117 * applying a custom hash function to the concatenation of a state-dependent 118 * word (encryption of an all-one block with the current key) and the new 119 * seed. The custom hash function uses Hirose's construction over AES-256; 120 * see the comments in `aesctr_drbg.c` for details. 121 * 122 * This DRBG does not follow an existing standard, and thus should be 123 * considered as inadequate for production use until it has been properly 124 * analysed. 125 */ 126 127 /** 128 * \brief Class type for PRNG implementations. 129 * 130 * A `br_prng_class` instance references the methods implementing a PRNG. 131 * Constant instances of this structure are defined for each implemented 132 * PRNG. Such instances are also called "vtables". 133 */ 134 typedef struct br_prng_class_ br_prng_class; 135 struct br_prng_class_ { 136 /** 137 * \brief Size (in bytes) of the context structure appropriate for 138 * running this PRNG. 139 */ 140 size_t context_size; 141 142 /** 143 * \brief Initialisation method. 144 * 145 * The context to initialise is provided as a pointer to its 146 * first field (the vtable pointer); this function sets that 147 * first field to a pointer to the vtable. 148 * 149 * The extra parameters depend on the implementation; each 150 * implementation defines what kind of extra parameters it 151 * expects (if any). 152 * 153 * Requirements on the initial seed depend on the implemented 154 * PRNG. 155 * 156 * \param ctx PRNG context to initialise. 157 * \param params extra parameters for the PRNG. 158 * \param seed initial seed. 159 * \param seed_len initial seed length (in bytes). 160 */ 161 void (*init)(const br_prng_class **ctx, const void *params, 162 const void *seed, size_t seed_len); 163 164 /** 165 * \brief Random bytes generation. 166 * 167 * This method produces `len` pseudorandom bytes, in the `out` 168 * buffer. The context is updated accordingly. 169 * 170 * \param ctx PRNG context. 171 * \param out output buffer. 172 * \param len number of pseudorandom bytes to produce. 173 */ 174 void (*generate)(const br_prng_class **ctx, void *out, size_t len); 175 176 /** 177 * \brief Inject additional seed bytes. 178 * 179 * The provided seed bytes are added into the PRNG internal 180 * entropy pool. 181 * 182 * \param ctx PRNG context. 183 * \param seed additional seed. 184 * \param seed_len additional seed length (in bytes). 185 */ 186 void (*update)(const br_prng_class **ctx, 187 const void *seed, size_t seed_len); 188 }; 189 190 /** 191 * \brief Context for HMAC_DRBG. 192 * 193 * The context contents are opaque, except the first field, which 194 * supports OOP. 195 */ 196 typedef struct { 197 /** 198 * \brief Pointer to the vtable. 199 * 200 * This field is set with the initialisation method/function. 201 */ 202 const br_prng_class *vtable; 203 #ifndef BR_DOXYGEN_IGNORE 204 unsigned char K[64]; 205 unsigned char V[64]; 206 const br_hash_class *digest_class; 207 #endif 208 } br_hmac_drbg_context; 209 210 /** 211 * \brief Statically allocated, constant vtable for HMAC_DRBG. 212 */ 213 extern const br_prng_class br_hmac_drbg_vtable; 214 215 /** 216 * \brief HMAC_DRBG initialisation. 217 * 218 * The context to initialise is provided as a pointer to its first field 219 * (the vtable pointer); this function sets that first field to a 220 * pointer to the vtable. 221 * 222 * The `seed` value is what is called, in NIST terminology, the 223 * concatenation of the "seed", "nonce" and "personalization string", in 224 * that order. 225 * 226 * The `digest_class` parameter defines the underlying hash function. 227 * Formally, the NIST standard specifies that the hash function shall 228 * be only SHA-1 or one of the SHA-2 functions. This implementation also 229 * works with any other implemented hash function (such as MD5), but 230 * this is non-standard and therefore not recommended. 231 * 232 * \param ctx HMAC_DRBG context to initialise. 233 * \param digest_class vtable for the underlying hash function. 234 * \param seed initial seed. 235 * \param seed_len initial seed length (in bytes). 236 */ 237 void br_hmac_drbg_init(br_hmac_drbg_context *ctx, 238 const br_hash_class *digest_class, const void *seed, size_t seed_len); 239 240 /** 241 * \brief Random bytes generation with HMAC_DRBG. 242 * 243 * This method produces `len` pseudorandom bytes, in the `out` 244 * buffer. The context is updated accordingly. Formally, requesting 245 * more than 65536 bytes in one request falls out of specification 246 * limits (but it won't fail). 247 * 248 * \param ctx HMAC_DRBG context. 249 * \param out output buffer. 250 * \param len number of pseudorandom bytes to produce. 251 */ 252 void br_hmac_drbg_generate(br_hmac_drbg_context *ctx, void *out, size_t len); 253 254 /** 255 * \brief Inject additional seed bytes in HMAC_DRBG. 256 * 257 * The provided seed bytes are added into the HMAC_DRBG internal 258 * entropy pool. The process does not _replace_ existing entropy, 259 * thus pushing non-random bytes (i.e. bytes which are known to the 260 * attackers) does not degrade the overall quality of generated bytes. 261 * 262 * \param ctx HMAC_DRBG context. 263 * \param seed additional seed. 264 * \param seed_len additional seed length (in bytes). 265 */ 266 void br_hmac_drbg_update(br_hmac_drbg_context *ctx, 267 const void *seed, size_t seed_len); 268 269 /** 270 * \brief Get the hash function implementation used by a given instance of 271 * HMAC_DRBG. 272 * 273 * This calls MUST NOT be performed on a context which was not 274 * previously initialised. 275 * 276 * \param ctx HMAC_DRBG context. 277 * \return the hash function vtable. 278 */ 279 static inline const br_hash_class * 280 br_hmac_drbg_get_hash(const br_hmac_drbg_context *ctx) 281 { 282 return ctx->digest_class; 283 } 284 285 /** 286 * \brief Type for a provider of entropy seeds. 287 * 288 * A "seeder" is a function that is able to obtain random values from 289 * some source and inject them as entropy seed in a PRNG. A seeder 290 * shall guarantee that the total entropy of the injected seed is large 291 * enough to seed a PRNG for purposes of cryptographic key generation 292 * (i.e. at least 128 bits). 293 * 294 * A seeder may report a failure to obtain adequate entropy. Seeders 295 * shall endeavour to fix themselves transient errors by trying again; 296 * thus, callers may consider reported errors as permanent. 297 * 298 * \param ctx PRNG context to seed. 299 * \return 1 on success, 0 on error. 300 */ 301 typedef int (*br_prng_seeder)(const br_prng_class **ctx); 302 303 /** 304 * \brief Get a seeder backed by the operating system or hardware. 305 * 306 * Get a seeder that feeds on RNG facilities provided by the current 307 * operating system or hardware. If no such facility is known, then 0 308 * is returned. 309 * 310 * If `name` is not `NULL`, then `*name` is set to a symbolic string 311 * that identifies the seeder implementation. If no seeder is returned 312 * and `name` is not `NULL`, then `*name` is set to a pointer to the 313 * constant string `"none"`. 314 * 315 * \param name receiver for seeder name, or `NULL`. 316 * \return the system seeder, if available, or 0. 317 */ 318 br_prng_seeder br_prng_seeder_system(const char **name); 319 320 /** 321 * \brief Context for AESCTR_DRBG. 322 * 323 * The context contents are opaque, except the first field, which 324 * supports OOP. 325 */ 326 typedef struct { 327 /** 328 * \brief Pointer to the vtable. 329 * 330 * This field is set with the initialisation method/function. 331 */ 332 const br_prng_class *vtable; 333 #ifndef BR_DOXYGEN_IGNORE 334 br_aes_gen_ctr_keys sk; 335 uint32_t cc; 336 #endif 337 } br_aesctr_drbg_context; 338 339 /** 340 * \brief Statically allocated, constant vtable for AESCTR_DRBG. 341 */ 342 extern const br_prng_class br_aesctr_drbg_vtable; 343 344 /** 345 * \brief AESCTR_DRBG initialisation. 346 * 347 * The context to initialise is provided as a pointer to its first field 348 * (the vtable pointer); this function sets that first field to a 349 * pointer to the vtable. 350 * 351 * The internal AES key is first set to the all-zero key; then, the 352 * `br_aesctr_drbg_update()` function is called with the provided `seed`. 353 * The call is performed even if the seed length (`seed_len`) is zero. 354 * 355 * The `aesctr` parameter defines the underlying AES/CTR implementation. 356 * 357 * \param ctx AESCTR_DRBG context to initialise. 358 * \param aesctr vtable for the AES/CTR implementation. 359 * \param seed initial seed (can be `NULL` if `seed_len` is zero). 360 * \param seed_len initial seed length (in bytes). 361 */ 362 void br_aesctr_drbg_init(br_aesctr_drbg_context *ctx, 363 const br_block_ctr_class *aesctr, const void *seed, size_t seed_len); 364 365 /** 366 * \brief Random bytes generation with AESCTR_DRBG. 367 * 368 * This method produces `len` pseudorandom bytes, in the `out` 369 * buffer. The context is updated accordingly. 370 * 371 * \param ctx AESCTR_DRBG context. 372 * \param out output buffer. 373 * \param len number of pseudorandom bytes to produce. 374 */ 375 void br_aesctr_drbg_generate(br_aesctr_drbg_context *ctx, 376 void *out, size_t len); 377 378 /** 379 * \brief Inject additional seed bytes in AESCTR_DRBG. 380 * 381 * The provided seed bytes are added into the AESCTR_DRBG internal 382 * entropy pool. The process does not _replace_ existing entropy, 383 * thus pushing non-random bytes (i.e. bytes which are known to the 384 * attackers) does not degrade the overall quality of generated bytes. 385 * 386 * \param ctx AESCTR_DRBG context. 387 * \param seed additional seed. 388 * \param seed_len additional seed length (in bytes). 389 */ 390 void br_aesctr_drbg_update(br_aesctr_drbg_context *ctx, 391 const void *seed, size_t seed_len); 392 393 #ifdef __cplusplus 394 } 395 #endif 396 397 #endif 398