|
Packit |
c4476c |
=pod
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 NAME
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
RAND_DRBG - the deterministic random bit generator
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 SYNOPSIS
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
#include <openssl/rand_drbg.h>
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 DESCRIPTION
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
The default OpenSSL RAND method is based on the RAND_DRBG class,
|
|
Packit |
c4476c |
which implements a deterministic random bit generator (DRBG).
|
|
Packit |
c4476c |
A DRBG is a certain type of cryptographically-secure pseudo-random
|
|
Packit |
c4476c |
number generator (CSPRNG), which is described in
|
|
Packit |
c4476c |
[NIST SP 800-90A Rev. 1].
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
While the RAND API is the 'frontend' which is intended to be used by
|
|
Packit |
c4476c |
application developers for obtaining random bytes, the RAND_DRBG API
|
|
Packit |
c4476c |
serves as the 'backend', connecting the former with the operating
|
|
Packit |
c4476c |
systems's entropy sources and providing access to the DRBG's
|
|
Packit |
c4476c |
configuration parameters.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head2 Disclaimer
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Unless you have very specific requirements for your random generator,
|
|
Packit |
c4476c |
it is in general not necessary to utilize the RAND_DRBG API directly.
|
|
Packit |
c4476c |
The usual way to obtain random bytes is to use L<RAND_bytes(3)> or
|
|
Packit |
c4476c |
L<RAND_priv_bytes(3)>, see also L<RAND(7)>.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head2 Typical Use Cases
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Typical examples for such special use cases are the following:
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=over 2
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=item *
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
You want to use your own private DRBG instances.
|
|
Packit |
c4476c |
Multiple DRBG instances which are accessed only by a single thread provide
|
|
Packit |
c4476c |
additional security (because their internal states are independent) and
|
|
Packit |
c4476c |
better scalability in multithreaded applications (because they don't need
|
|
Packit |
c4476c |
to be locked).
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=item *
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
You need to integrate a previously unsupported entropy source.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=item *
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
You need to change the default settings of the standard OpenSSL RAND
|
|
Packit |
c4476c |
implementation to meet specific requirements.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=back
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 CHAINING
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
A DRBG instance can be used as the entropy source of another DRBG instance,
|
|
Packit |
c4476c |
provided it has itself access to a valid entropy source.
|
|
Packit |
c4476c |
The DRBG instance which acts as entropy source is called the I<parent> DRBG,
|
|
Packit |
c4476c |
the other instance the I<child> DRBG.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
This is called chaining. A chained DRBG instance is created by passing
|
|
Packit |
c4476c |
a pointer to the parent DRBG as argument to the RAND_DRBG_new() call.
|
|
Packit |
c4476c |
It is possible to create chains of more than two DRBG in a row.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 THE THREE SHARED DRBG INSTANCES
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Currently, there are three shared DRBG instances,
|
|
Packit |
c4476c |
the <master>, <public>, and <private> DRBG.
|
|
Packit |
c4476c |
While the <master> DRBG is a single global instance, the <public> and <private>
|
|
Packit |
c4476c |
DRBG are created per thread and accessed through thread-local storage.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
By default, the functions L<RAND_bytes(3)> and L<RAND_priv_bytes(3)> use
|
|
Packit |
c4476c |
the thread-local <public> and <private> DRBG instance, respectively.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head2 The <master> DRBG instance
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
The <master> DRBG is not used directly by the application, only for reseeding
|
|
Packit |
c4476c |
the two other two DRBG instances. It reseeds itself by obtaining randomness
|
|
Packit |
c4476c |
either from os entropy sources or by consuming randomness which was added
|
|
Packit |
c4476c |
previously by L<RAND_add(3)>.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head2 The <public> DRBG instance
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
This instance is used per default by L<RAND_bytes(3)>.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head2 The <private> DRBG instance
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
This instance is used per default by L<RAND_priv_bytes(3)>
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 LOCKING
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
The <master> DRBG is intended to be accessed concurrently for reseeding
|
|
Packit |
c4476c |
by its child DRBG instances. The necessary locking is done internally.
|
|
Packit |
c4476c |
It is I<not> thread-safe to access the <master> DRBG directly via the
|
|
Packit |
c4476c |
RAND_DRBG interface.
|
|
Packit |
c4476c |
The <public> and <private> DRBG are thread-local, i.e. there is an
|
|
Packit |
c4476c |
instance of each per thread. So they can safely be accessed without
|
|
Packit |
c4476c |
locking via the RAND_DRBG interface.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Pointers to these DRBG instances can be obtained using
|
|
Packit |
c4476c |
RAND_DRBG_get0_master(),
|
|
Packit |
c4476c |
RAND_DRBG_get0_public(), and
|
|
Packit |
c4476c |
RAND_DRBG_get0_private(), respectively.
|
|
Packit |
c4476c |
Note that it is not allowed to store a pointer to one of the thread-local
|
|
Packit |
c4476c |
DRBG instances in a variable or other memory location where it will be
|
|
Packit |
c4476c |
accessed and used by multiple threads.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
All other DRBG instances created by an application don't support locking,
|
|
Packit |
c4476c |
because they are intended to be used by a single thread.
|
|
Packit |
c4476c |
Instead of accessing a single DRBG instance concurrently from different
|
|
Packit |
c4476c |
threads, it is recommended to instantiate a separate DRBG instance per
|
|
Packit |
c4476c |
thread. Using the <master> DRBG as entropy source for multiple DRBG
|
|
Packit |
c4476c |
instances on different threads is thread-safe, because the DRBG instance
|
|
Packit |
c4476c |
will lock the <master> DRBG automatically for obtaining random input.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 THE OVERALL PICTURE
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
The following picture gives an overview over how the DRBG instances work
|
|
Packit |
c4476c |
together and are being used.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
+--------------------+
|
|
Packit |
c4476c |
| os entropy sources |
|
|
Packit |
c4476c |
+--------------------+
|
|
Packit |
c4476c |
|
|
|
Packit |
c4476c |
v +-----------------------------+
|
|
Packit |
c4476c |
RAND_add() ==> <master> <-| shared DRBG (with locking) |
|
|
Packit |
c4476c |
/ \ +-----------------------------+
|
|
Packit |
c4476c |
/ \ +---------------------------+
|
|
Packit |
c4476c |
<public> <private> <- | per-thread DRBG instances |
|
|
Packit |
c4476c |
| | +---------------------------+
|
|
Packit |
c4476c |
v v
|
|
Packit |
c4476c |
RAND_bytes() RAND_priv_bytes()
|
|
Packit |
c4476c |
| ^
|
|
Packit |
c4476c |
| |
|
|
Packit |
c4476c |
+------------------+ +------------------------------------+
|
|
Packit |
c4476c |
| general purpose | | used for secrets like session keys |
|
|
Packit |
c4476c |
| random generator | | and private keys for certificates |
|
|
Packit |
c4476c |
+------------------+ +------------------------------------+
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
The usual way to obtain random bytes is to call RAND_bytes(...) or
|
|
Packit |
c4476c |
RAND_priv_bytes(...). These calls are roughly equivalent to calling
|
|
Packit |
c4476c |
RAND_DRBG_bytes(<public>, ...) and RAND_DRBG_bytes(<private>, ...),
|
|
Packit |
c4476c |
respectively. The method L<RAND_DRBG_bytes(3)> is a convenience method
|
|
Packit |
c4476c |
wrapping the L<RAND_DRBG_generate(3)> function, which serves the actual
|
|
Packit |
c4476c |
request for random data.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 RESEEDING
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
A DRBG instance seeds itself automatically, pulling random input from
|
|
Packit |
c4476c |
its entropy source. The entropy source can be either a trusted operating
|
|
Packit |
c4476c |
system entropy source, or another DRBG with access to such a source.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Automatic reseeding occurs after a predefined number of generate requests.
|
|
Packit |
c4476c |
The selection of the trusted entropy sources is configured at build
|
|
Packit |
c4476c |
time using the --with-rand-seed option. The following sections explain
|
|
Packit |
c4476c |
the reseeding process in more detail.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head2 Automatic Reseeding
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Before satisfying a generate request (L<RAND_DRBG_generate(3)>), the DRBG
|
|
Packit |
c4476c |
reseeds itself automatically, if one of the following conditions holds:
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
- the DRBG was not instantiated (=seeded) yet or has been uninstantiated.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
- the number of generate requests since the last reseeding exceeds a
|
|
Packit |
c4476c |
certain threshold, the so called I<reseed_interval>.
|
|
Packit |
c4476c |
This behaviour can be disabled by setting the I<reseed_interval> to 0.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
- the time elapsed since the last reseeding exceeds a certain time
|
|
Packit |
c4476c |
interval, the so called I<reseed_time_interval>.
|
|
Packit |
c4476c |
This can be disabled by setting the I<reseed_time_interval> to 0.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
- the DRBG is in an error state.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
B<Note>: An error state is entered if the entropy source fails while
|
|
Packit |
c4476c |
the DRBG is seeding or reseeding.
|
|
Packit |
c4476c |
The last case ensures that the DRBG automatically recovers
|
|
Packit |
c4476c |
from the error as soon as the entropy source is available again.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head2 Manual Reseeding
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
In addition to automatic reseeding, the caller can request an immediate
|
|
Packit |
c4476c |
reseeding of the DRBG with fresh entropy by setting the
|
|
Packit |
c4476c |
I<prediction resistance> parameter to 1 when calling L<RAND_DRBG_generate(3)>.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
The document [NIST SP 800-90C] describes prediction resistance requests
|
|
Packit |
c4476c |
in detail and imposes strict conditions on the entropy sources that are
|
|
Packit |
c4476c |
approved for providing prediction resistance.
|
|
Packit |
c4476c |
Since the default DRBG implementation does not have access to such an approved
|
|
Packit |
c4476c |
entropy source, a request for prediction resistance will currently always fail.
|
|
Packit |
c4476c |
In other words, prediction resistance is currently not supported yet by the DRBG.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
For the three shared DRBGs (and only for these) there is another way to
|
|
Packit |
c4476c |
reseed them manually:
|
|
Packit |
c4476c |
If L<RAND_add(3)> is called with a positive I<randomness> argument
|
|
Packit |
c4476c |
(or L<RAND_seed(3)>), then this will immediately reseed the <master> DRBG.
|
|
Packit |
c4476c |
The <public> and <private> DRBG will detect this on their next generate
|
|
Packit |
c4476c |
call and reseed, pulling randomness from <master>.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
The last feature has been added to support the common practice used with
|
|
Packit |
c4476c |
previous OpenSSL versions to call RAND_add() before calling RAND_bytes().
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head2 Entropy Input vs. Additional Data
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
The DRBG distinguishes two different types of random input: I<entropy>,
|
|
Packit |
c4476c |
which comes from a trusted source, and I<additional input>',
|
|
Packit |
c4476c |
which can optionally be added by the user and is considered untrusted.
|
|
Packit |
c4476c |
It is possible to add I<additional input> not only during reseeding,
|
|
Packit |
c4476c |
but also for every generate request.
|
|
Packit |
c4476c |
This is in fact done automatically by L<RAND_DRBG_bytes(3)>.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head2 Configuring the Random Seed Source
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
In most cases OpenSSL will automatically choose a suitable seed source
|
|
Packit |
c4476c |
for automatically seeding and reseeding its <master> DRBG. In some cases
|
|
Packit |
c4476c |
however, it will be necessary to explicitly specify a seed source during
|
|
Packit |
c4476c |
configuration, using the --with-rand-seed option. For more information,
|
|
Packit |
c4476c |
see the INSTALL instructions. There are also operating systems where no
|
|
Packit |
c4476c |
seed source is available and automatic reseeding is disabled by default.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
The following two sections describe the reseeding process of the master
|
|
Packit |
c4476c |
DRBG, depending on whether automatic reseeding is available or not.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head2 Reseeding the master DRBG with automatic seeding enabled
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Calling RAND_poll() or RAND_add() is not necessary, because the DRBG
|
|
Packit |
c4476c |
pulls the necessary entropy from its source automatically.
|
|
Packit |
c4476c |
However, both calls are permitted, and do reseed the RNG.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
RAND_add() can be used to add both kinds of random input, depending on the
|
|
Packit |
c4476c |
value of the B<randomness> argument:
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=over 4
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=item randomness == 0:
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
The random bytes are mixed as additional input into the current state of
|
|
Packit |
c4476c |
the DRBG.
|
|
Packit |
c4476c |
Mixing in additional input is not considered a full reseeding, hence the
|
|
Packit |
c4476c |
reseed counter is not reset.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=item randomness > 0:
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
The random bytes are used as entropy input for a full reseeding
|
|
Packit |
c4476c |
(resp. reinstantiation) if the DRBG is instantiated
|
|
Packit |
c4476c |
(resp. uninstantiated or in an error state).
|
|
Packit |
c4476c |
The number of random bits required for reseeding is determined by the
|
|
Packit |
c4476c |
security strength of the DRBG. Currently it defaults to 256 bits (32 bytes).
|
|
Packit |
c4476c |
It is possible to provide less randomness than required.
|
|
Packit |
c4476c |
In this case the missing randomness will be obtained by pulling random input
|
|
Packit |
c4476c |
from the trusted entropy sources.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=back
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head2 Reseeding the master DRBG with automatic seeding disabled
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Calling RAND_poll() will always fail.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
RAND_add() needs to be called for initial seeding and periodic reseeding.
|
|
Packit |
c4476c |
At least 48 bytes (384 bits) of randomness have to be provided, otherwise
|
|
Packit |
c4476c |
the (re-)seeding of the DRBG will fail. This corresponds to one and a half
|
|
Packit |
c4476c |
times the security strength of the DRBG. The extra half is used for the
|
|
Packit |
c4476c |
nonce during instantiation.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
More precisely, the number of bytes needed for seeding depend on the
|
|
Packit |
c4476c |
I<security strength> of the DRBG, which is set to 256 by default.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 SEE ALSO
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
L<RAND_DRBG_bytes(3)>,
|
|
Packit |
c4476c |
L<RAND_DRBG_generate(3)>,
|
|
Packit |
c4476c |
L<RAND_DRBG_reseed(3)>,
|
|
Packit |
c4476c |
L<RAND_DRBG_get0_master(3)>,
|
|
Packit |
c4476c |
L<RAND_DRBG_get0_public(3)>,
|
|
Packit |
c4476c |
L<RAND_DRBG_get0_private(3)>,
|
|
Packit |
c4476c |
L<RAND_DRBG_set_reseed_interval(3)>,
|
|
Packit |
c4476c |
L<RAND_DRBG_set_reseed_time_interval(3)>,
|
|
Packit |
c4476c |
L<RAND_DRBG_set_reseed_defaults(3)>,
|
|
Packit |
c4476c |
L<RAND(7)>,
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 COPYRIGHT
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Licensed under the OpenSSL license (the "License"). You may not use
|
|
Packit |
c4476c |
this file except in compliance with the License. You can obtain a copy
|
|
Packit |
c4476c |
in the file LICENSE in the source distribution or at
|
|
Packit |
c4476c |
L<https://www.openssl.org/source/license.html>.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=cut
|