37379d2bf8da1f0ed568e437a6df2c82ad6f7690
[BearSSL] / inc / bearssl_rand.h
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 #ifdef __cplusplus
32 extern "C" {
33 #endif
34
35 /** \file bearssl_rand.h
36 *
37 * # Pseudo-Random Generators
38 *
39 * A PRNG is a state-based engine that outputs pseudo-random bytes on
40 * demand. It is initialized with an initial seed, and additional seed
41 * bytes can be added afterwards. Bytes produced depend on the seeds and
42 * also on the exact sequence of calls (including sizes requested for
43 * each call).
44 *
45 *
46 * ## Procedural and OOP API
47 *
48 * For the PRNG of name "`xxx`", two API are provided. The _procedural_
49 * API defined a context structure `br_xxx_context` and three functions:
50 *
51 * - `br_xxx_init()`
52 *
53 * Initialise the context with an initial seed.
54 *
55 * - `br_xxx_generate()`
56 *
57 * Produce some pseudo-random bytes.
58 *
59 * - `br_xxx_update()`
60 *
61 * Inject some additional seed.
62 *
63 * The initialisation function sets the first context field (`vtable`)
64 * to a pointer to the vtable that supports the OOP API. The OOP API
65 * provides access to the same functions through function pointers,
66 * named `init()`, `generate()` and `update()`.
67 *
68 * Note that the context initialisation method may accept additional
69 * parameters, provided as a 'const void *' pointer at API level. These
70 * additional parameters depend on the implemented PRNG.
71 *
72 *
73 * ## HMAC_DRBG
74 *
75 * HMAC_DRBG is defined in [NIST SP 800-90A Revision
76 * 1](http://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-90Ar1.pdf).
77 * It uses HMAC repeatedly, over some configurable underlying hash
78 * function. In BearSSL, it is implemented under the "`hmac_drbg`" name.
79 * The "extra parameters" pointer for context initialisation should be
80 * set to a pointer to the vtable for the underlying hash function (e.g.
81 * pointer to `br_sha256_vtable` to use HMAC_DRBG with SHA-256).
82 *
83 * According to the NIST standard, each request shall produce up to
84 * 2<sup>19</sup> bits (i.e. 64 kB of data); moreover, the context shall
85 * be reseeded at least once every 2<sup>48</sup> requests. This
86 * implementation does not maintain the reseed counter (the threshold is
87 * too high to be reached in practice) and does not object to producing
88 * more than 64 kB in a single request; thus, the code cannot fail,
89 * which corresponds to the fact that the API has no room for error
90 * codes. However, this implies that requesting more than 64 kB in one
91 * `generate()` request, or making more than 2<sup>48</sup> requests
92 * without reseeding, is formally out of NIST specification. There is
93 * no currently known security penalty for exceeding the NIST limits,
94 * and, in any case, HMAC_DRBG usage in implementing SSL/TLS always
95 * stays much below these thresholds.
96 */
97
98 /**
99 * \brief Class type for PRNG implementations.
100 *
101 * A `br_prng_class` instance references the methods implementing a PRNG.
102 * Constant instances of this structure are defined for each implemented
103 * PRNG. Such instances are also called "vtables".
104 */
105 typedef struct br_prng_class_ br_prng_class;
106 struct br_prng_class_ {
107 /**
108 * \brief Size (in bytes) of the context structure appropriate for
109 * running this PRNG.
110 */
111 size_t context_size;
112
113 /**
114 * \brief Initialisation method.
115 *
116 * The context to initialise is provided as a pointer to its
117 * first field (the vtable pointer); this function sets that
118 * first field to a pointer to the vtable.
119 *
120 * The extra parameters depend on the implementation; each
121 * implementation defines what kind of extra parameters it
122 * expects (if any).
123 *
124 * Requirements on the initial seed depend on the implemented
125 * PRNG.
126 *
127 * \param ctx PRNG context to initialise.
128 * \param params extra parameters for the PRNG.
129 * \param seed initial seed.
130 * \param seed_len initial seed length (in bytes).
131 */
132 void (*init)(const br_prng_class **ctx, const void *params,
133 const void *seed, size_t seed_len);
134
135 /**
136 * \brief Random bytes generation.
137 *
138 * This method produces `len` pseudorandom bytes, in the `out`
139 * buffer. The context is updated accordingly.
140 *
141 * \param ctx PRNG context.
142 * \param out output buffer.
143 * \param len number of pseudorandom bytes to produce.
144 */
145 void (*generate)(const br_prng_class **ctx, void *out, size_t len);
146
147 /**
148 * \brief Inject additional seed bytes.
149 *
150 * The provided seed bytes are added into the PRNG internal
151 * entropy pool.
152 *
153 * \param ctx PRNG context.
154 * \param seed additional seed.
155 * \param seed_len additional seed length (in bytes).
156 */
157 void (*update)(const br_prng_class **ctx,
158 const void *seed, size_t seed_len);
159 };
160
161 /**
162 * \brief Context for HMAC_DRBG.
163 *
164 * The context contents are opaque, except the first field, which
165 * supports OOP.
166 */
167 typedef struct {
168 /**
169 * \brief Pointer to the vtable.
170 *
171 * This field is set with the initialisation method/function.
172 */
173 const br_prng_class *vtable;
174 #ifndef BR_DOXYGEN_IGNORE
175 unsigned char K[64];
176 unsigned char V[64];
177 const br_hash_class *digest_class;
178 #endif
179 } br_hmac_drbg_context;
180
181 /**
182 * \brief Statically allocated, constant vtable for HMAC_DRBG.
183 */
184 extern const br_prng_class br_hmac_drbg_vtable;
185
186 /**
187 * \brief HMAC_DRBG initialisation.
188 *
189 * The context to initialise is provided as a pointer to its first field
190 * (the vtable pointer); this function sets that first field to a
191 * pointer to the vtable.
192 *
193 * The `seed` value is what is called, in NIST terminology, the
194 * concatenation of the "seed", "nonce" and "personalization string", in
195 * that order.
196 *
197 * The `digest_class` parameter defines the underlying hash function.
198 * Formally, the NIST standard specifies that the hash function shall
199 * be only SHA-1 or one of the SHA-2 functions. This implementation also
200 * works with any other implemented hash function (such as MD5), but
201 * this is non-standard and therefore not recommended.
202 *
203 * \param ctx HMAC_DRBG context to initialise.
204 * \param digest_class vtable for the underlying hash function.
205 * \param seed initial seed.
206 * \param seed_len initial seed length (in bytes).
207 */
208 void br_hmac_drbg_init(br_hmac_drbg_context *ctx,
209 const br_hash_class *digest_class, const void *seed, size_t seed_len);
210
211 /**
212 * \brief Random bytes generation with HMAC_DRBG.
213 *
214 * This method produces `len` pseudorandom bytes, in the `out`
215 * buffer. The context is updated accordingly. Formally, requesting
216 * more than 65536 bytes in one request falls out of specification
217 * limits (but it won't fail).
218 *
219 * \param ctx HMAC_DRBG context.
220 * \param out output buffer.
221 * \param len number of pseudorandom bytes to produce.
222 */
223 void br_hmac_drbg_generate(br_hmac_drbg_context *ctx, void *out, size_t len);
224
225 /**
226 * \brief Inject additional seed bytes in HMAC_DRBG.
227 *
228 * The provided seed bytes are added into the HMAC_DRBG internal
229 * entropy pool. The process does not _replace_ existing entropy,
230 * thus pushing non-random bytes (i.e. bytes which are known to the
231 * attackers) does not degrade the overall quality of generated bytes.
232 *
233 * \param ctx HMAC_DRBG context.
234 * \param seed additional seed.
235 * \param seed_len additional seed length (in bytes).
236 */
237 void br_hmac_drbg_update(br_hmac_drbg_context *ctx,
238 const void *seed, size_t seed_len);
239
240 /**
241 * \brief Get the hash function implementation used by a given instance of
242 * HMAC_DRBG.
243 *
244 * This calls MUST NOT be performed on a context which was not
245 * previously initialised.
246 *
247 * \param ctx HMAC_DRBG context.
248 * \return the hash function vtable.
249 */
250 static inline const br_hash_class *
251 br_hmac_drbg_get_hash(const br_hmac_drbg_context *ctx)
252 {
253 return ctx->digest_class;
254 }
255
256 /**
257 * \brief Type for a provider of entropy seeds.
258 *
259 * A "seeder" is a function that is able to obtain random values from
260 * some source and inject them as entropy seed in a PRNG. A seeder
261 * shall guarantee that the total entropy of the injected seed is large
262 * enough to seed a PRNG for purposes of cryptographic key generation
263 * (i.e. at least 128 bits).
264 *
265 * A seeder may report a failure to obtain adequate entropy. Seeders
266 * shall endeavour to fix themselves transient errors by trying again;
267 * thus, callers may consider reported errors as permanent.
268 *
269 * \param ctx PRNG context to seed.
270 * \return 1 on success, 0 on error.
271 */
272 typedef int (*br_prng_seeder)(const br_prng_class **ctx);
273
274 /**
275 * \brief Get a seeder backed by the operating system or hardware.
276 *
277 * Get a seeder that feeds on RNG facilities provided by the current
278 * operating system or hardware. If no such facility is known, then 0
279 * is returned.
280 *
281 * If `name` is not `NULL`, then `*name` is set to a symbolic string
282 * that identifies the seeder implemention. If no seeder is returned
283 * and `name` is not `NULL`, then `*name` is set to a pointer to the
284 * constant string `"none"`.
285 *
286 * \param name receiver for seeder name, or `NULL`.
287 * \return the system seeder, if available, or 0.
288 */
289 br_prng_seeder br_prng_seeder_system(const char **name);
290
291 #ifdef __cplusplus
292 }
293 #endif
294
295 #endif