/src/BearSSL/inc/bearssl_rand.h

Source (jump to first uncovered line)
/*
 * Copyright (c) 2016 Thomas Pornin <pornin@bolet.org>
 *
 * Permission is hereby granted, free of charge, to any person obtaining 
 * a copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, sublicense, and/or sell copies of the Software, and to
 * permit persons to whom the Software is furnished to do so, subject to
 * the following conditions:
 *
 * The above copyright notice and this permission notice shall be 
 * included in all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 
 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */

#ifndef BR_BEARSSL_RAND_H__
#define BR_BEARSSL_RAND_H__

#include <stddef.h>
#include <stdint.h>

#include "bearssl_block.h"
#include "bearssl_hash.h"

#ifdef __cplusplus
extern "C" {
#endif

/** \file bearssl_rand.h
 *
 * # Pseudo-Random Generators
 *
 * A PRNG is a state-based engine that outputs pseudo-random bytes on
 * demand. It is initialized with an initial seed, and additional seed
 * bytes can be added afterwards. Bytes produced depend on the seeds and
 * also on the exact sequence of calls (including sizes requested for
 * each call).
 *
 *
 * ## Procedural and OOP API
 *
 * For the PRNG of name "`xxx`", two API are provided. The _procedural_
 * API defined a context structure `br_xxx_context` and three functions:
 *
 *   - `br_xxx_init()`
 *
 *     Initialise the context with an initial seed.
 *
 *   - `br_xxx_generate()`
 *
 *     Produce some pseudo-random bytes.
 *
 *   - `br_xxx_update()`
 *
 *     Inject some additional seed.
 *
 * The initialisation function sets the first context field (`vtable`)
 * to a pointer to the vtable that supports the OOP API. The OOP API
 * provides access to the same functions through function pointers,
 * named `init()`, `generate()` and `update()`.
 *
 * Note that the context initialisation method may accept additional
 * parameters, provided as a 'const void *' pointer at API level. These
 * additional parameters depend on the implemented PRNG.
 *
 *
 * ## HMAC_DRBG
 *
 * HMAC_DRBG is defined in [NIST SP 800-90A Revision
 * 1](http://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-90Ar1.pdf).
 * It uses HMAC repeatedly, over some configurable underlying hash
 * function. In BearSSL, it is implemented under the "`hmac_drbg`" name.
 * The "extra parameters" pointer for context initialisation should be
 * set to a pointer to the vtable for the underlying hash function (e.g.
 * pointer to `br_sha256_vtable` to use HMAC_DRBG with SHA-256).
 *
 * According to the NIST standard, each request shall produce up to
 * 2<sup>19</sup> bits (i.e. 64 kB of data); moreover, the context shall
 * be reseeded at least once every 2<sup>48</sup> requests. This
 * implementation does not maintain the reseed counter (the threshold is
 * too high to be reached in practice) and does not object to producing
 * more than 64 kB in a single request; thus, the code cannot fail,
 * which corresponds to the fact that the API has no room for error
 * codes. However, this implies that requesting more than 64 kB in one
 * `generate()` request, or making more than 2<sup>48</sup> requests
 * without reseeding, is formally out of NIST specification. There is
 * no currently known security penalty for exceeding the NIST limits,
 * and, in any case, HMAC_DRBG usage in implementing SSL/TLS always
 * stays much below these thresholds.
 *
 *
 * ## AESCTR_DRBG
 *
 * AESCTR_DRBG is a custom PRNG based on AES-128 in CTR mode. This is
 * meant to be used only in situations where you are desperate for
 * speed, and have an hardware-optimized AES/CTR implementation. Whether
 * this will yield perceptible improvements depends on what you use the
 * pseudorandom bytes for, and how many you want; for instance, RSA key
 * pair generation uses a substantial amount of randomness, and using
 * AESCTR_DRBG instead of HMAC_DRBG yields a 15 to 20% increase in key
 * generation speed on a recent x86 CPU (Intel Core i7-6567U at 3.30 GHz).
 *
 * Internally, it uses CTR mode with successive counter values, starting
 * at zero (counter value expressed over 128 bits, big-endian convention).
 * The counter is not allowed to reach 32768; thus, every 32768*16 bytes
 * at most, the `update()` function is run (on an empty seed, if none is
 * provided). The `update()` function computes the new AES-128 key by
 * applying a custom hash function to the concatenation of a state-dependent
 * word (encryption of an all-one block with the current key) and the new
 * seed. The custom hash function uses Hirose's construction over AES-256;
 * see the comments in `aesctr_drbg.c` for details.
 *
 * This DRBG does not follow an existing standard, and thus should be
 * considered as inadequate for production use until it has been properly
 * analysed.
 */

/**
 * \brief Class type for PRNG implementations.
 *
 * A `br_prng_class` instance references the methods implementing a PRNG.
 * Constant instances of this structure are defined for each implemented
 * PRNG. Such instances are also called "vtables".
 */
typedef struct br_prng_class_ br_prng_class;
struct br_prng_class_ {
  /**
   * \brief Size (in bytes) of the context structure appropriate for
   * running this PRNG.
   */
  size_t context_size;

  /**
   * \brief Initialisation method.
   *
   * The context to initialise is provided as a pointer to its
   * first field (the vtable pointer); this function sets that
   * first field to a pointer to the vtable.
   *
   * The extra parameters depend on the implementation; each
   * implementation defines what kind of extra parameters it
   * expects (if any).
   *
   * Requirements on the initial seed depend on the implemented
   * PRNG.
   *
   * \param ctx        PRNG context to initialise.
   * \param params     extra parameters for the PRNG.
   * \param seed       initial seed.
   * \param seed_len   initial seed length (in bytes).
   */
  void (*init)(const br_prng_class **ctx, const void *params,
    const void *seed, size_t seed_len);

  /**
   * \brief Random bytes generation.
   *
   * This method produces `len` pseudorandom bytes, in the `out`
   * buffer. The context is updated accordingly.
   *
   * \param ctx   PRNG context.
   * \param out   output buffer.
   * \param len   number of pseudorandom bytes to produce.
   */
  void (*generate)(const br_prng_class **ctx, void *out, size_t len);

  /**
   * \brief Inject additional seed bytes.
   *
   * The provided seed bytes are added into the PRNG internal
   * entropy pool.
   *
   * \param ctx        PRNG context.
   * \param seed       additional seed.
   * \param seed_len   additional seed length (in bytes).
   */
  void (*update)(const br_prng_class **ctx,
    const void *seed, size_t seed_len);
};

/**
 * \brief Context for HMAC_DRBG.
 *
 * The context contents are opaque, except the first field, which
 * supports OOP.
 */
typedef struct {
  /**
   * \brief Pointer to the vtable.
   *
   * This field is set with the initialisation method/function.
   */
  const br_prng_class *vtable;
#ifndef BR_DOXYGEN_IGNORE
  unsigned char K[64];
  unsigned char V[64];
  const br_hash_class *digest_class;
#endif
} br_hmac_drbg_context;

/**
 * \brief Statically allocated, constant vtable for HMAC_DRBG.
 */
extern const br_prng_class br_hmac_drbg_vtable;

/**
 * \brief HMAC_DRBG initialisation.
 *
 * The context to initialise is provided as a pointer to its first field
 * (the vtable pointer); this function sets that first field to a
 * pointer to the vtable.
 *
 * The `seed` value is what is called, in NIST terminology, the
 * concatenation of the "seed", "nonce" and "personalization string", in
 * that order.
 *
 * The `digest_class` parameter defines the underlying hash function.
 * Formally, the NIST standard specifies that the hash function shall
 * be only SHA-1 or one of the SHA-2 functions. This implementation also
 * works with any other implemented hash function (such as MD5), but
 * this is non-standard and therefore not recommended.
 *
 * \param ctx            HMAC_DRBG context to initialise.
 * \param digest_class   vtable for the underlying hash function.
 * \param seed           initial seed.
 * \param seed_len       initial seed length (in bytes).
 */
void br_hmac_drbg_init(br_hmac_drbg_context *ctx,
  const br_hash_class *digest_class, const void *seed, size_t seed_len);

/**
 * \brief Random bytes generation with HMAC_DRBG.
 *
 * This method produces `len` pseudorandom bytes, in the `out`
 * buffer. The context is updated accordingly. Formally, requesting
 * more than 65536 bytes in one request falls out of specification
 * limits (but it won't fail).
 *
 * \param ctx   HMAC_DRBG context.
 * \param out   output buffer.
 * \param len   number of pseudorandom bytes to produce.
 */
void br_hmac_drbg_generate(br_hmac_drbg_context *ctx, void *out, size_t len);

/**
 * \brief Inject additional seed bytes in HMAC_DRBG.
 *
 * The provided seed bytes are added into the HMAC_DRBG internal
 * entropy pool. The process does not _replace_ existing entropy,
 * thus pushing non-random bytes (i.e. bytes which are known to the
 * attackers) does not degrade the overall quality of generated bytes.
 *
 * \param ctx        HMAC_DRBG context.
 * \param seed       additional seed.
 * \param seed_len   additional seed length (in bytes).
 */
void br_hmac_drbg_update(br_hmac_drbg_context *ctx,
  const void *seed, size_t seed_len);

/**
 * \brief Get the hash function implementation used by a given instance of
 * HMAC_DRBG.
 *
 * This calls MUST NOT be performed on a context which was not
 * previously initialised.
 *
 * \param ctx   HMAC_DRBG context.
 * \return  the hash function vtable.
 */
static inline const br_hash_class *
br_hmac_drbg_get_hash(const br_hmac_drbg_context *ctx)
{
  return ctx->digest_class;
}

/**
 * \brief Type for a provider of entropy seeds.
 *
 * A "seeder" is a function that is able to obtain random values from
 * some source and inject them as entropy seed in a PRNG. A seeder
 * shall guarantee that the total entropy of the injected seed is large
 * enough to seed a PRNG for purposes of cryptographic key generation
 * (i.e. at least 128 bits).
 *
 * A seeder may report a failure to obtain adequate entropy. Seeders
 * shall endeavour to fix themselves transient errors by trying again;
 * thus, callers may consider reported errors as permanent.
 *
 * \param ctx   PRNG context to seed.
 * \return  1 on success, 0 on error.
 */
typedef int (*br_prng_seeder)(const br_prng_class **ctx);

/**
 * \brief Get a seeder backed by the operating system or hardware.
 *
 * Get a seeder that feeds on RNG facilities provided by the current
 * operating system or hardware. If no such facility is known, then 0
 * is returned.
 *
 * If `name` is not `NULL`, then `*name` is set to a symbolic string
 * that identifies the seeder implementation. If no seeder is returned
 * and `name` is not `NULL`, then `*name` is set to a pointer to the
 * constant string `"none"`.
 *
 * \param name   receiver for seeder name, or `NULL`.
 * \return  the system seeder, if available, or 0.
 */
br_prng_seeder br_prng_seeder_system(const char **name);

/**
 * \brief Context for AESCTR_DRBG.
 *
 * The context contents are opaque, except the first field, which
 * supports OOP.
 */
typedef struct {
  /**
   * \brief Pointer to the vtable.
   *
   * This field is set with the initialisation method/function.
   */
  const br_prng_class *vtable;
#ifndef BR_DOXYGEN_IGNORE
  br_aes_gen_ctr_keys sk;
  uint32_t cc;
#endif
} br_aesctr_drbg_context;

/**
 * \brief Statically allocated, constant vtable for AESCTR_DRBG.
 */
extern const br_prng_class br_aesctr_drbg_vtable;

/**
 * \brief AESCTR_DRBG initialisation.
 *
 * The context to initialise is provided as a pointer to its first field
 * (the vtable pointer); this function sets that first field to a
 * pointer to the vtable.
 *
 * The internal AES key is first set to the all-zero key; then, the
 * `br_aesctr_drbg_update()` function is called with the provided `seed`.
 * The call is performed even if the seed length (`seed_len`) is zero.
 *
 * The `aesctr` parameter defines the underlying AES/CTR implementation.
 *
 * \param ctx        AESCTR_DRBG context to initialise.
 * \param aesctr     vtable for the AES/CTR implementation.
 * \param seed       initial seed (can be `NULL` if `seed_len` is zero).
 * \param seed_len   initial seed length (in bytes).
 */
void br_aesctr_drbg_init(br_aesctr_drbg_context *ctx,
  const br_block_ctr_class *aesctr, const void *seed, size_t seed_len);

/**
 * \brief Random bytes generation with AESCTR_DRBG.
 *
 * This method produces `len` pseudorandom bytes, in the `out`
 * buffer. The context is updated accordingly.
 *
 * \param ctx   AESCTR_DRBG context.
 * \param out   output buffer.
 * \param len   number of pseudorandom bytes to produce.
 */
void br_aesctr_drbg_generate(br_aesctr_drbg_context *ctx,
  void *out, size_t len);

/**
 * \brief Inject additional seed bytes in AESCTR_DRBG.
 *
 * The provided seed bytes are added into the AESCTR_DRBG internal
 * entropy pool. The process does not _replace_ existing entropy,
 * thus pushing non-random bytes (i.e. bytes which are known to the
 * attackers) does not degrade the overall quality of generated bytes.
 *
 * \param ctx        AESCTR_DRBG context.
 * \param seed       additional seed.
 * \param seed_len   additional seed length (in bytes).
 */
void br_aesctr_drbg_update(br_aesctr_drbg_context *ctx,
  const void *seed, size_t seed_len);

#ifdef __cplusplus
}
#endif

#endif

Coverage Report

Created: 2024-11-21 06:38

Line	Count	Source (jump to first uncovered line)
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	0	{
282	0	return ctx->digest_class;
283	0	} Unexecuted instantiation: module.cpp:br_hmac_drbg_get_hash(br_hmac_drbg_context const*) Unexecuted instantiation: poly1305_ctmul.c:br_hmac_drbg_get_hash Unexecuted instantiation: chacha20_sse2.c:br_hmac_drbg_get_hash Unexecuted instantiation: chacha20_ct.c:br_hmac_drbg_get_hash Unexecuted instantiation: aes_x86ni_ctrcbc.c:br_hmac_drbg_get_hash Unexecuted instantiation: aes_x86ni.c:br_hmac_drbg_get_hash Unexecuted instantiation: aes_small_ctrcbc.c:br_hmac_drbg_get_hash Unexecuted instantiation: aes_ct_ctrcbc.c:br_hmac_drbg_get_hash Unexecuted instantiation: aes_ct_ctr.c:br_hmac_drbg_get_hash Unexecuted instantiation: aes_ct64_ctrcbc.c:br_hmac_drbg_get_hash Unexecuted instantiation: aes_ct64.c:br_hmac_drbg_get_hash Unexecuted instantiation: aes_ct.c:br_hmac_drbg_get_hash Unexecuted instantiation: aes_common.c:br_hmac_drbg_get_hash Unexecuted instantiation: aes_big_ctrcbc.c:br_hmac_drbg_get_hash Unexecuted instantiation: prf_md5sha1.c:br_hmac_drbg_get_hash Unexecuted instantiation: prf.c:br_hmac_drbg_get_hash Unexecuted instantiation: sysrng.c:br_hmac_drbg_get_hash Unexecuted instantiation: hmac_drbg.c:br_hmac_drbg_get_hash Unexecuted instantiation: hmac.c:br_hmac_drbg_get_hash Unexecuted instantiation: shake.c:br_hmac_drbg_get_hash Unexecuted instantiation: hkdf.c:br_hmac_drbg_get_hash Unexecuted instantiation: sha2small.c:br_hmac_drbg_get_hash Unexecuted instantiation: sha2big.c:br_hmac_drbg_get_hash Unexecuted instantiation: sha1.c:br_hmac_drbg_get_hash Unexecuted instantiation: md5sha1.c:br_hmac_drbg_get_hash Unexecuted instantiation: md5.c:br_hmac_drbg_get_hash Unexecuted instantiation: ghash_ctmul32.c:br_hmac_drbg_get_hash Unexecuted instantiation: ecdsa_i31_vrfy_raw.c:br_hmac_drbg_get_hash Unexecuted instantiation: ecdsa_i31_sign_raw.c:br_hmac_drbg_get_hash Unexecuted instantiation: ecdsa_i31_bits.c:br_hmac_drbg_get_hash Unexecuted instantiation: ecdsa_i15_vrfy_raw.c:br_hmac_drbg_get_hash Unexecuted instantiation: ecdsa_i15_sign_raw.c:br_hmac_drbg_get_hash Unexecuted instantiation: ecdsa_i15_bits.c:br_hmac_drbg_get_hash Unexecuted instantiation: ec_secp521r1.c:br_hmac_drbg_get_hash Unexecuted instantiation: ec_secp384r1.c:br_hmac_drbg_get_hash Unexecuted instantiation: ec_secp256r1.c:br_hmac_drbg_get_hash Unexecuted instantiation: ec_pubkey.c:br_hmac_drbg_get_hash Unexecuted instantiation: ec_prime_i31.c:br_hmac_drbg_get_hash Unexecuted instantiation: ec_prime_i15.c:br_hmac_drbg_get_hash Unexecuted instantiation: ec_p256_m64.c:br_hmac_drbg_get_hash Unexecuted instantiation: ec_p256_m62.c:br_hmac_drbg_get_hash Unexecuted instantiation: ec_p256_m31.c:br_hmac_drbg_get_hash Unexecuted instantiation: ec_p256_m15.c:br_hmac_drbg_get_hash Unexecuted instantiation: ec_keygen.c:br_hmac_drbg_get_hash Unexecuted instantiation: ec_default.c:br_hmac_drbg_get_hash Unexecuted instantiation: ec_c25519_m64.c:br_hmac_drbg_get_hash Unexecuted instantiation: ec_c25519_m62.c:br_hmac_drbg_get_hash Unexecuted instantiation: ec_c25519_m31.c:br_hmac_drbg_get_hash Unexecuted instantiation: ec_c25519_m15.c:br_hmac_drbg_get_hash Unexecuted instantiation: ec_c25519_i31.c:br_hmac_drbg_get_hash Unexecuted instantiation: ec_c25519_i15.c:br_hmac_drbg_get_hash Unexecuted instantiation: ec_all_m31.c:br_hmac_drbg_get_hash Unexecuted instantiation: enc64be.c:br_hmac_drbg_get_hash Unexecuted instantiation: enc32le.c:br_hmac_drbg_get_hash Unexecuted instantiation: enc32be.c:br_hmac_drbg_get_hash Unexecuted instantiation: dec64be.c:br_hmac_drbg_get_hash Unexecuted instantiation: dec32le.c:br_hmac_drbg_get_hash Unexecuted instantiation: dec32be.c:br_hmac_drbg_get_hash Unexecuted instantiation: ccopy.c:br_hmac_drbg_get_hash Unexecuted instantiation: gcm.c:br_hmac_drbg_get_hash Unexecuted instantiation: ccm.c:br_hmac_drbg_get_hash Unexecuted instantiation: aes_small_enc.c:br_hmac_drbg_get_hash Unexecuted instantiation: aes_ct_enc.c:br_hmac_drbg_get_hash Unexecuted instantiation: aes_ct64_enc.c:br_hmac_drbg_get_hash Unexecuted instantiation: aes_big_enc.c:br_hmac_drbg_get_hash Unexecuted instantiation: i31_sub.c:br_hmac_drbg_get_hash Unexecuted instantiation: i31_rshift.c:br_hmac_drbg_get_hash Unexecuted instantiation: i31_ninv31.c:br_hmac_drbg_get_hash Unexecuted instantiation: i31_montmul.c:br_hmac_drbg_get_hash Unexecuted instantiation: i31_modpow.c:br_hmac_drbg_get_hash Unexecuted instantiation: i31_iszero.c:br_hmac_drbg_get_hash Unexecuted instantiation: i31_fmont.c:br_hmac_drbg_get_hash Unexecuted instantiation: i31_encode.c:br_hmac_drbg_get_hash Unexecuted instantiation: i31_decode.c:br_hmac_drbg_get_hash Unexecuted instantiation: i31_decmod.c:br_hmac_drbg_get_hash Unexecuted instantiation: i31_bitlen.c:br_hmac_drbg_get_hash Unexecuted instantiation: i31_add.c:br_hmac_drbg_get_hash Unexecuted instantiation: i15_sub.c:br_hmac_drbg_get_hash Unexecuted instantiation: i15_rshift.c:br_hmac_drbg_get_hash Unexecuted instantiation: i15_ninv15.c:br_hmac_drbg_get_hash Unexecuted instantiation: i15_montmul.c:br_hmac_drbg_get_hash Unexecuted instantiation: i15_modpow.c:br_hmac_drbg_get_hash Unexecuted instantiation: i15_iszero.c:br_hmac_drbg_get_hash Unexecuted instantiation: i15_fmont.c:br_hmac_drbg_get_hash Unexecuted instantiation: i15_encode.c:br_hmac_drbg_get_hash Unexecuted instantiation: i15_decode.c:br_hmac_drbg_get_hash Unexecuted instantiation: i15_decmod.c:br_hmac_drbg_get_hash Unexecuted instantiation: i15_bitlen.c:br_hmac_drbg_get_hash Unexecuted instantiation: i15_add.c:br_hmac_drbg_get_hash Unexecuted instantiation: i31_tmont.c:br_hmac_drbg_get_hash Unexecuted instantiation: i31_muladd.c:br_hmac_drbg_get_hash Unexecuted instantiation: i15_tmont.c:br_hmac_drbg_get_hash Unexecuted instantiation: i15_muladd.c:br_hmac_drbg_get_hash Unexecuted instantiation: i32_div32.c:br_hmac_drbg_get_hash
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