2 * Copyright (c) 2016 Thomas Pornin <pornin@bolet.org>
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:
12 * The above copyright notice and this permission notice shall be
13 * included in all copies or substantial portions of the Software.
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
25 #ifndef BR_BEARSSL_RAND_H__
26 #define BR_BEARSSL_RAND_H__
31 /** \file bearssl_rand.h
33 * # Pseudo-Random Generators
35 * A PRNG is a state-based engine that outputs pseudo-random bytes on
36 * demand. It is initialized with an initial seed, and additional seed
37 * bytes can be added afterwards. Bytes produced depend on the seeds and
38 * also on the exact sequence of calls (including sizes requested for
42 * ## Procedural and OOP API
44 * For the PRNG of name "`xxx`", two API are provided. The _procedural_
45 * API defined a context structure `br_xxx_context` and three functions:
49 * Initialise the context with an initial seed.
51 * - `br_xxx_generate()`
53 * Produce some pseudo-random bytes.
57 * Inject some additional seed.
59 * The initialisation function sets the first context field (`vtable`)
60 * to a pointer to the vtable that supports the OOP API. The OOP API
61 * provides access to the same functions through function pointers,
62 * named `init()`, `generate()` and `update()`.
64 * Note that the context initialisation method may accept additional
65 * parameters, provided as a 'const void *' pointer at API level. These
66 * additional parameters depend on the implemented PRNG.
71 * HMAC_DRBG is defined in [NIST SP 800-90A Revision
72 * 1](http://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-90Ar1.pdf).
73 * It uses HMAC repeatedly, over some configurable underlying hash
74 * function. In BearSSL, it is implemented under the "`hmac_drbg`" name.
75 * The "extra parameters" pointer for context initialisation should be
76 * set to a pointer to the vtable for the underlying hash function (e.g.
77 * pointer to `br_sha256_vtable` to use HMAC_DRBG with SHA-256).
79 * According to the NIST standard, each request shall produce up to
80 * 2<sup>19</sup> bits (i.e. 64 kB of data); moreover, the context shall
81 * be reseeded at least once every 2<sup>48</sup> requests. This
82 * implementation does not maintain the reseed counter (the threshold is
83 * too high to be reached in practice) and does not object to producing
84 * more than 64 kB in a single request; thus, the code cannot fail,
85 * which corresponds to the fact that the API has no room for error
86 * codes. However, this implies that requesting more than 64 kB in one
87 * `generate()` request, or making more than 2<sup>48</sup> requests
88 * without reseeding, is formally out of NIST specification. There is
89 * no currently known security penalty for exceeding the NIST limits,
90 * and, in any case, HMAC_DRBG usage in implementing SSL/TLS always
91 * stays much below these thresholds.
95 * \brief Class type for PRNG implementations.
97 * A `br_prng_class` instance references the methods implementing a PRNG.
98 * Constant instances of this structure are defined for each implemented
99 * PRNG. Such instances are also called "vtables".
101 typedef struct br_prng_class_ br_prng_class
;
102 struct br_prng_class_
{
104 * \brief Size (in bytes) of the context structure appropriate for
110 * \brief Initialisation method.
112 * The context to initialise is provided as a pointer to its
113 * first field (the vtable pointer); this function sets that
114 * first field to a pointer to the vtable.
116 * The extra parameters depend on the implementation; each
117 * implementation defines what kind of extra parameters it
120 * Requirements on the initial seed depend on the implemented
123 * \param ctx PRNG context to initialise.
124 * \param params extra parameters for the PRNG.
125 * \param seed initial seed.
126 * \param seed_len initial seed length (in bytes).
128 void (*init
)(const br_prng_class
**ctx
, const void *params
,
129 const void *seed
, size_t seed_len
);
132 * \brief Random bytes generation.
134 * This method produces `len` pseudorandom bytes, in the `out`
135 * buffer. The context is updated accordingly.
137 * \param ctx PRNG context.
138 * \param out output buffer.
139 * \param len number of pseudorandom bytes to produce.
141 void (*generate
)(const br_prng_class
**ctx
, void *out
, size_t len
);
144 * \brief Inject additional seed bytes.
146 * The provided seed bytes are added into the PRNG internal
149 * \param ctx PRNG context.
150 * \param seed additional seed.
151 * \param seed_len additional seed length (in bytes).
153 void (*update
)(const br_prng_class
**ctx
,
154 const void *seed
, size_t seed_len
);
158 * \brief Context for HMAC_DRBG.
160 * The context contents are opaque, except the first field, which
165 * \brief Pointer to the vtable.
167 * This field is set with the initialisation method/function.
169 const br_prng_class
*vtable
;
170 #ifndef BR_DOXYGEN_IGNORE
173 const br_hash_class
*digest_class
;
175 } br_hmac_drbg_context
;
178 * \brief Statically allocated, constant vtable for HMAC_DRBG.
180 extern const br_prng_class br_hmac_drbg_vtable
;
183 * \brief HMAC_DRBG initialisation.
185 * The context to initialise is provided as a pointer to its first field
186 * (the vtable pointer); this function sets that first field to a
187 * pointer to the vtable.
189 * The `seed` value is what is called, in NIST terminology, the
190 * concatenation of the "seed", "nonce" and "personalization string", in
193 * The `digest_class` parameter defines the underlying hash function.
194 * Formally, the NIST standard specifies that the hash function shall
195 * be only SHA-1 or one of the SHA-2 functions. This implementation also
196 * works with any other implemented hash function (such as MD5), but
197 * this is non-standard and therefore not recommended.
199 * \param ctx HMAC_DRBG context to initialise.
200 * \param digest_class vtable for the underlying hash function.
201 * \param seed initial seed.
202 * \param seed_len initial seed length (in bytes).
204 void br_hmac_drbg_init(br_hmac_drbg_context
*ctx
,
205 const br_hash_class
*digest_class
, const void *seed
, size_t seed_len
);
208 * \brief Random bytes generation with HMAC_DRBG.
210 * This method produces `len` pseudorandom bytes, in the `out`
211 * buffer. The context is updated accordingly. Formally, requesting
212 * more than 65536 bytes in one request falls out of specification
213 * limits (but it won't fail).
215 * \param ctx HMAC_DRBG context.
216 * \param out output buffer.
217 * \param len number of pseudorandom bytes to produce.
219 void br_hmac_drbg_generate(br_hmac_drbg_context
*ctx
, void *out
, size_t len
);
222 * \brief Inject additional seed bytes in HMAC_DRBG.
224 * The provided seed bytes are added into the HMAC_DRBG internal
225 * entropy pool. The process does not _replace_ existing entropy,
226 * thus pushing non-random bytes (i.e. bytes which are known to the
227 * attackers) does not degrade the overall quality of generated bytes.
229 * \param ctx HMAC_DRBG context.
230 * \param seed additional seed.
231 * \param seed_len additional seed length (in bytes).
233 void br_hmac_drbg_update(br_hmac_drbg_context
*ctx
,
234 const void *seed
, size_t seed_len
);
237 * \brief Get the hash function implementation used by a given instance of
240 * This calls MUST NOT be performed on a context which was not
241 * previously initialised.
243 * \param ctx HMAC_DRBG context.
244 * \return the hash function vtable.
246 static inline const br_hash_class
*
247 br_hmac_drbg_get_hash(const br_hmac_drbg_context
*ctx
)
249 return ctx
->digest_class
;