Section: OpenSSL (7)
RAND_DRBG - the deterministic random bit generator
The default OpenSSL RAND
method is based on the RAND_DRBG
which implements a deterministic random bit generator (DRBG
is a certain type of cryptographically-secure pseudo-random
number generator (CSPRNG
), which is described in
[NIST SP 800-90A
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
Unless you have very specific requirements for your random generator,
it is in general not necessary to utilize the RAND_DRBG API
The usual way to obtain random bytes is to use RAND_bytes
(3), see also RAND
Typical Use Cases
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.
instance can be used as the entropy source of another DRBG
provided it has itself access to a valid entropy source.
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.
THE THREE SHARED DRBG INSTANCES
Currently, there are three shared DRBG
the <master>, <public>, and <private> DRBG.
While the <master> DRBG
is a single global instance, the <public> and <private>
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 instance
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
The <public> DRBG instance
This instance is used per default by RAND_bytes
The <private> DRBG instance
This instance is used per default by RAND_priv_bytes
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
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
Pointers to these DRBG instances can be obtained using
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 OVERALL PICTURE
The following picture gives an overview over how the DRBG
together and are being used.
| os entropy sources |
RAND_add() ==> <master> <-| shared DRBG (with locking) |
/ \ +-----------------------------+
/ \ +---------------------------+
<public> <private> <- | per-thread DRBG instances |
| | +---------------------------+
| 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.
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
parameter to 1 when calling RAND_DRBG_generate
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().
Entropy Input vs. Additional Data
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
Configuring the Random Seed Source
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.
Reseeding the master DRBG with automatic seeding enabled
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
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.
Reseeding the master DRBG with automatic seeding disabled
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.
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