BearSSL: bearssl_rand.h Source File

BearSSL

bearssl_rand.h
Go to the documentation of this file.
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
35extern "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 */
134typedef 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 */
213extern 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 */
279static inline const br_hash_class *
280br_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 */
342extern 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
bearssl_block.h
bearssl_hash.h
br_hmac_drbg_vtable
const br_prng_class br_hmac_drbg_vtable
Statically allocated, constant vtable for HMAC_DRBG.
br_aesctr_drbg_generate
void br_aesctr_drbg_generate(br_aesctr_drbg_context *ctx, void *out, size_t len)
Random bytes generation with AESCTR_DRBG.
br_hmac_drbg_update
void br_hmac_drbg_update(br_hmac_drbg_context *ctx, const void *seed, size_t seed_len)
Inject additional seed bytes in HMAC_DRBG.
br_hmac_drbg_generate
void br_hmac_drbg_generate(br_hmac_drbg_context *ctx, void *out, size_t len)
Random bytes generation with HMAC_DRBG.
br_hmac_drbg_init
void br_hmac_drbg_init(br_hmac_drbg_context *ctx, const br_hash_class *digest_class, const void *seed, size_t seed_len)
HMAC_DRBG initialisation.
br_aesctr_drbg_vtable
const br_prng_class br_aesctr_drbg_vtable
Statically allocated, constant vtable for AESCTR_DRBG.
br_prng_seeder_system
br_prng_seeder br_prng_seeder_system(const char **name)
Get a seeder backed by the operating system or hardware.
br_hmac_drbg_get_hash
static const br_hash_class * br_hmac_drbg_get_hash(const br_hmac_drbg_context *ctx)
Get the hash function implementation used by a given instance of HMAC_DRBG.
Definition: bearssl_rand.h:280
br_prng_seeder
int(* br_prng_seeder)(const br_prng_class **ctx)
Type for a provider of entropy seeds.
Definition: bearssl_rand.h:301
br_aesctr_drbg_update
void br_aesctr_drbg_update(br_aesctr_drbg_context *ctx, const void *seed, size_t seed_len)
Inject additional seed bytes in AESCTR_DRBG.
br_aesctr_drbg_init
void br_aesctr_drbg_init(br_aesctr_drbg_context *ctx, const br_block_ctr_class *aesctr, const void *seed, size_t seed_len)
AESCTR_DRBG initialisation.
br_aesctr_drbg_context
Context for AESCTR_DRBG.
Definition: bearssl_rand.h:326
br_aesctr_drbg_context::vtable
const br_prng_class * vtable
Pointer to the vtable.
Definition: bearssl_rand.h:332
br_hmac_drbg_context
Context for HMAC_DRBG.
Definition: bearssl_rand.h:196
br_hmac_drbg_context::vtable
const br_prng_class * vtable
Pointer to the vtable.
Definition: bearssl_rand.h:202
br_prng_class_
Class type for PRNG implementations.
Definition: bearssl_rand.h:135
br_prng_class_::init
void(* init)(const br_prng_class **ctx, const void *params, const void *seed, size_t seed_len)
Initialisation method.
Definition: bearssl_rand.h:161
br_prng_class_::context_size
size_t context_size
Size (in bytes) of the context structure appropriate for running this PRNG.
Definition: bearssl_rand.h:140
br_prng_class_::update
void(* update)(const br_prng_class **ctx, const void *seed, size_t seed_len)
Inject additional seed bytes.
Definition: bearssl_rand.h:186
br_prng_class_::generate
void(* generate)(const br_prng_class **ctx, void *out, size_t len)
Random bytes generation.
Definition: bearssl_rand.h:174
br_aes_gen_ctr_keys
Aggregate structure large enough to be used as context for subkeys (CTR encryption and decryption) fo...
Definition: bearssl_block.h:2186