RAND_DRBG(7) | OpenSSL | RAND_DRBG(7) |
#include <openssl/rand_drbg.h>
While the RAND API is the 'frontend' which is intended to be used by application developers for obtaining random bytes, the RAND_DRBG API serves as the 'backend', connecting the former with the operating systems's entropy sources and providing access to the DRBG's configuration parameters.
This is called chaining. A chained DRBG instance is created by passing a pointer to the parent DRBG as argument to the RAND_DRBG_new() call. It is possible to create chains of more than two DRBG in a row.
By default, the functions RAND_bytes(3) and RAND_priv_bytes(3) use the thread-local <public> and <private> DRBG instance, respectively.
Pointers to these DRBG instances can be obtained using RAND_DRBG_get0_master(), RAND_DRBG_get0_public(), and RAND_DRBG_get0_private(), respectively. Note that it is not allowed to store a pointer to one of the thread-local DRBG instances in a variable or other memory location where it will be accessed and used by multiple threads.
All other DRBG instances created by an application don't support locking, because they are intended to be used by a single thread. Instead of accessing a single DRBG instance concurrently from different threads, it is recommended to instantiate a separate DRBG instance per thread. Using the <master> DRBG as entropy source for multiple DRBG instances on different threads is thread-safe, because the DRBG instance will lock the <master> DRBG automatically for obtaining random input.
+--------------------+ | os entropy sources | +--------------------+ | v +-----------------------------+ RAND_add() ==> <master> <-| shared DRBG (with locking) | / \ +-----------------------------+ / \ +---------------------------+ <public> <private> <- | per-thread DRBG instances | | | +---------------------------+ v v RAND_bytes() RAND_priv_bytes() | ^ | | +------------------+ +------------------------------------+ | general purpose | | used for secrets like session keys | | random generator | | and private keys for certificates | +------------------+ +------------------------------------+
The usual way to obtain random bytes is to call RAND_bytes(...) or RAND_priv_bytes(...). These calls are roughly equivalent to calling RAND_DRBG_bytes(<public>, ...) and RAND_DRBG_bytes(<private>, ...), respectively. The method RAND_DRBG_bytes(3) is a convenience method wrapping the RAND_DRBG_generate(3) function, which serves the actual request for random data.
Automatic reseeding occurs after a predefined number of generate requests. The selection of the trusted entropy sources is configured at build time using the --with-rand-seed option. The following sections explain the reseeding process in more detail.
- the DRBG was not instantiated (=seeded) yet or has been uninstantiated.
- the number of generate requests since the last reseeding exceeds a certain threshold, the so called reseed_interval. This behaviour can be disabled by setting the reseed_interval to 0.
- the time elapsed since the last reseeding exceeds a certain time interval, the so called reseed_time_interval. This can be disabled by setting the reseed_time_interval to 0.
- the DRBG is in an error state.
Note: An error state is entered if the entropy source fails while the DRBG is seeding or reseeding. The last case ensures that the DRBG automatically recovers from the error as soon as the entropy source is available again.
The document [NIST SP 800-90C] describes prediction resistance requests in detail and imposes strict conditions on the entropy sources that are approved for providing prediction resistance. Since the default DRBG implementation does not have access to such an approved entropy source, a request for prediction resistance will currently always fail. In other words, prediction resistance is currently not supported yet by the DRBG.
For the three shared DRBGs (and only for these) there is another way to reseed them manually: If RAND_add(3) is called with a positive randomness argument (or RAND_seed(3)), then this will immediately reseed the <master> DRBG. The <public> and <private> DRBG will detect this on their next generate call and reseed, pulling randomness from <master>.
The last feature has been added to support the common practice used with previous OpenSSL versions to call RAND_add() before calling RAND_bytes().
The following two sections describe the reseeding process of the master DRBG, depending on whether automatic reseeding is available or not.
RAND_add() can be used to add both kinds of random input, depending on the value of the randomness argument:
RAND_add() needs to be called for initial seeding and periodic reseeding. At least 48 bytes (384 bits) of randomness have to be provided, otherwise the (re-)seeding of the DRBG will fail. This corresponds to one and a half times the security strength of the DRBG. The extra half is used for the nonce during instantiation.
More precisely, the number of bytes needed for seeding depend on the security strength of the DRBG, which is set to 256 by default.
Licensed under the OpenSSL license (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.
2023-02-07 | 1.1.1t |