RAND_DRBG - the deterministic random bit generator
#include <openssl/rand_drbg.h>
The default OpenSSL RAND method is based on the RAND_DRBG class, which
implements a deterministic random bit generator (DRBG). A DRBG is a certain
type of cryptographically-secure pseudo-random number generator (CSPRNG),
which is described in [NIST SP 800-90A Rev. 1].
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.
Unless you have very specific requirements for your random generator, it is in
general not necessary to utilize the RAND_DRBG API directly. The usual way to
obtain random bytes is to use
RAND_bytes(3) or
RAND_priv_bytes(3), see also
RAND(7).
Typical examples for such special use cases are the following:
- •
- You want to use your own private DRBG instances. Multiple DRBG instances
which are accessed only by a single thread provide additional security
(because their internal states are independent) and better scalability in
multithreaded applications (because they don't need to be locked).
- •
- You need to integrate a previously unsupported entropy source.
- •
- You need to change the default settings of the standard OpenSSL RAND
implementation to meet specific requirements.
A DRBG instance can be used as the entropy source of another DRBG instance,
provided it has itself access to a valid entropy source. The DRBG instance
which acts as entropy source is called the
parent DRBG, the other
instance the
child DRBG.
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.
Currently, there are three shared DRBG instances, the <master>,
<public>, and <private> DRBG. While the <master> DRBG is a
single global instance, the <public> and <private> DRBG are
created per thread and accessed through thread-local storage.
By default, the functions
RAND_bytes(3) and
RAND_priv_bytes(3) use
the thread-local <public> and <private> DRBG instance,
respectively.
The <master> DRBG is not used directly by the application, only for
reseeding the two other two DRBG instances. It reseeds itself by obtaining
randomness either from os entropy sources or by consuming randomness which was
added previously by
RAND_add(3).
This instance is used per default by
RAND_bytes(3).
This instance is used per default by
RAND_priv_bytes(3)
The <master> DRBG is intended to be accessed concurrently for reseeding by
its child DRBG instances. The necessary locking is done internally. It is
not thread-safe to access the <master> DRBG directly via the
RAND_DRBG interface. The <public> and <private> DRBG are
thread-local, i.e. there is an instance of each per thread. So they can safely
be accessed without locking via the RAND_DRBG interface.
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.
The following picture gives an overview over how the DRBG instances work
together and are being used.
+--------------------+
| 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.
A DRBG instance seeds itself automatically, pulling random input from its
entropy source. The entropy source can be either a trusted operating system
entropy source, or another DRBG with access to such a source.
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.
Before satisfying a generate request (
RAND_DRBG_generate(3)), the DRBG
reseeds itself automatically, if one of the following conditions holds:
- 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.
In addition to automatic reseeding, the caller can request an immediate
reseeding of the DRBG with fresh entropy by setting the
prediction
resistance parameter to 1 when calling
RAND_DRBG_generate(3).
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 DRBG distinguishes two different types of random input:
entropy,
which comes from a trusted source, and
additional input', which can
optionally be added by the user and is considered untrusted. It is possible to
add
additional input not only during reseeding, but also for every
generate request. This is in fact done automatically by
RAND_DRBG_bytes(3).
In most cases OpenSSL will automatically choose a suitable seed source for
automatically seeding and reseeding its <master> DRBG. In some cases
however, it will be necessary to explicitly specify a seed source during
configuration, using the --with-rand-seed option. For more information, see
the INSTALL instructions. There are also operating systems where no seed
source is available and automatic reseeding is disabled by default.
The following two sections describe the reseeding process of the master DRBG,
depending on whether automatic reseeding is available or not.
Calling
RAND_poll() or
RAND_add() is not necessary, because the
DRBG pulls the necessary entropy from its source automatically. However, both
calls are permitted, and do reseed the RNG.
RAND_add() can be used to add both kinds of random input, depending on
the value of the
randomness argument:
- randomness == 0:
- The random bytes are mixed as additional input into the current state of
the DRBG. Mixing in additional input is not considered a full reseeding,
hence the reseed counter is not reset.
- randomness > 0:
- The random bytes are used as entropy input for a full reseeding (resp.
reinstantiation) if the DRBG is instantiated (resp. uninstantiated or in
an error state). The number of random bits required for reseeding is
determined by the security strength of the DRBG. Currently it defaults to
256 bits (32 bytes). It is possible to provide less randomness than
required. In this case the missing randomness will be obtained by pulling
random input from the trusted entropy sources.
Calling
RAND_poll() will always fail.
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.
RAND_DRBG_bytes(3),
RAND_DRBG_generate(3),
RAND_DRBG_reseed(3),
RAND_DRBG_get0_master(3),
RAND_DRBG_get0_public(3),
RAND_DRBG_get0_private(3),
RAND_DRBG_set_reseed_interval(3),
RAND_DRBG_set_reseed_time_interval(3),
RAND_DRBG_set_reseed_defaults(3),
RAND(7),
Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
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>.