1RAND_DRBG(7)                        OpenSSL                       RAND_DRBG(7)
2
3
4

NAME

6       RAND_DRBG - the deterministic random bit generator
7

SYNOPSIS

9        #include <openssl/rand_drbg.h>
10

DESCRIPTION

12       The default OpenSSL RAND method is based on the RAND_DRBG class, which
13       implements a deterministic random bit generator (DRBG).  A DRBG is a
14       certain type of cryptographically-secure pseudo-random number generator
15       (CSPRNG), which is described in [NIST SP 800-90A Rev. 1].
16
17       While the RAND API is the 'frontend' which is intended to be used by
18       application developers for obtaining random bytes, the RAND_DRBG API
19       serves as the 'backend', connecting the former with the operating
20       systems's entropy sources and providing access to the DRBG's
21       configuration parameters.
22
23   Disclaimer
24       Unless you have very specific requirements for your random generator,
25       it is in general not necessary to utilize the RAND_DRBG API directly.
26       The usual way to obtain random bytes is to use RAND_bytes(3) or
27       RAND_priv_bytes(3), see also RAND(7).
28
29   Typical Use Cases
30       Typical examples for such special use cases are the following:
31
32       · You want to use your own private DRBG instances.  Multiple DRBG
33         instances which are accessed only by a single thread provide
34         additional security (because their internal states are independent)
35         and better scalability in multithreaded applications (because they
36         don't need to be locked).
37
38       · You need to integrate a previously unsupported entropy source.
39
40       · You need to change the default settings of the standard OpenSSL RAND
41         implementation to meet specific requirements.
42

CHAINING

44       A DRBG instance can be used as the entropy source of another DRBG
45       instance, provided it has itself access to a valid entropy source.  The
46       DRBG instance which acts as entropy source is called the parent DRBG,
47       the other instance the child DRBG.
48
49       This is called chaining. A chained DRBG instance is created by passing
50       a pointer to the parent DRBG as argument to the RAND_DRBG_new() call.
51       It is possible to create chains of more than two DRBG in a row.
52

THE THREE SHARED DRBG INSTANCES

54       Currently, there are three shared DRBG instances, the <master>,
55       <public>, and <private> DRBG.  While the <master> DRBG is a single
56       global instance, the <public> and <private> DRBG are created per thread
57       and accessed through thread-local storage.
58
59       By default, the functions RAND_bytes(3) and RAND_priv_bytes(3) use the
60       thread-local <public> and <private> DRBG instance, respectively.
61
62   The <master> DRBG instance
63       The <master> DRBG is not used directly by the application, only for
64       reseeding the two other two DRBG instances. It reseeds itself by
65       obtaining randomness either from os entropy sources or by consuming
66       randomness which was added previously by RAND_add(3).
67
68   The <public> DRBG instance
69       This instance is used per default by RAND_bytes(3).
70
71   The <private> DRBG instance
72       This instance is used per default by RAND_priv_bytes(3)
73

LOCKING

75       The <master> DRBG is intended to be accessed concurrently for reseeding
76       by its child DRBG instances. The necessary locking is done internally.
77       It is not thread-safe to access the <master> DRBG directly via the
78       RAND_DRBG interface.  The <public> and <private> DRBG are thread-local,
79       i.e. there is an instance of each per thread. So they can safely be
80       accessed without locking via the RAND_DRBG interface.
81
82       Pointers to these DRBG instances can be obtained using
83       RAND_DRBG_get0_master(), RAND_DRBG_get0_public(), and
84       RAND_DRBG_get0_private(), respectively.  Note that it is not allowed to
85       store a pointer to one of the thread-local DRBG instances in a variable
86       or other memory location where it will be accessed and used by multiple
87       threads.
88
89       All other DRBG instances created by an application don't support
90       locking, because they are intended to be used by a single thread.
91       Instead of accessing a single DRBG instance concurrently from different
92       threads, it is recommended to instantiate a separate DRBG instance per
93       thread. Using the <master> DRBG as entropy source for multiple DRBG
94       instances on different threads is thread-safe, because the DRBG
95       instance will lock the <master> DRBG automatically for obtaining random
96       input.
97

THE OVERALL PICTURE

99       The following picture gives an overview over how the DRBG instances
100       work together and are being used.
101
102                      +--------------------+
103                      | os entropy sources |
104                      +--------------------+
105                               |
106                               v           +-----------------------------+
107             RAND_add() ==> <master>     <-| shared DRBG (with locking)  |
108                             /   \         +-----------------------------+
109                            /     \              +---------------------------+
110                     <public>     <private>   <- | per-thread DRBG instances |
111                        |             |          +---------------------------+
112                        v             v
113                      RAND_bytes()   RAND_priv_bytes()
114                           |               ^
115                           |               |
116           +------------------+      +------------------------------------+
117           | general purpose  |      | used for secrets like session keys |
118           | random generator |      | and private keys for certificates  |
119           +------------------+      +------------------------------------+
120
121       The usual way to obtain random bytes is to call RAND_bytes(...) or
122       RAND_priv_bytes(...). These calls are roughly equivalent to calling
123       RAND_DRBG_bytes(<public>, ...) and RAND_DRBG_bytes(<private>, ...),
124       respectively. The method RAND_DRBG_bytes(3) is a convenience method
125       wrapping the RAND_DRBG_generate(3) function, which serves the actual
126       request for random data.
127

RESEEDING

129       A DRBG instance seeds itself automatically, pulling random input from
130       its entropy source. The entropy source can be either a trusted
131       operating system entropy source, or another DRBG with access to such a
132       source.
133
134       Automatic reseeding occurs after a predefined number of generate
135       requests.  The selection of the trusted entropy sources is configured
136       at build time using the --with-rand-seed option. The following sections
137       explain the reseeding process in more detail.
138
139   Automatic Reseeding
140       Before satisfying a generate request (RAND_DRBG_generate(3)), the DRBG
141       reseeds itself automatically, if one of the following conditions holds:
142
143       - the DRBG was not instantiated (=seeded) yet or has been
144       uninstantiated.
145
146       - the number of generate requests since the last reseeding exceeds a
147       certain threshold, the so called reseed_interval.  This behaviour can
148       be disabled by setting the reseed_interval to 0.
149
150       - the time elapsed since the last reseeding exceeds a certain time
151       interval, the so called reseed_time_interval.  This can be disabled by
152       setting the reseed_time_interval to 0.
153
154       - the DRBG is in an error state.
155
156       Note: An error state is entered if the entropy source fails while the
157       DRBG is seeding or reseeding.  The last case ensures that the DRBG
158       automatically recovers from the error as soon as the entropy source is
159       available again.
160
161   Manual Reseeding
162       In addition to automatic reseeding, the caller can request an immediate
163       reseeding of the DRBG with fresh entropy by setting the prediction
164       resistance parameter to 1 when calling RAND_DRBG_generate(3).
165
166       The document [NIST SP 800-90C] describes prediction resistance requests
167       in detail and imposes strict conditions on the entropy sources that are
168       approved for providing prediction resistance.  Since the default DRBG
169       implementation does not have access to such an approved entropy source,
170       a request for prediction resistance will currently always fail.  In
171       other words, prediction resistance is currently not supported yet by
172       the DRBG.
173
174       For the three shared DRBGs (and only for these) there is another way to
175       reseed them manually: If RAND_add(3) is called with a positive
176       randomness argument (or RAND_seed(3)), then this will immediately
177       reseed the <master> DRBG.  The <public> and <private> DRBG will detect
178       this on their next generate call and reseed, pulling randomness from
179       <master>.
180
181       The last feature has been added to support the common practice used
182       with previous OpenSSL versions to call RAND_add() before calling
183       RAND_bytes().
184
185   Entropy Input vs. Additional Data
186       The DRBG distinguishes two different types of random input: entropy,
187       which comes from a trusted source, and additional input', which can
188       optionally be added by the user and is considered untrusted.  It is
189       possible to add additional input not only during reseeding, but also
190       for every generate request.  This is in fact done automatically by
191       RAND_DRBG_bytes(3).
192
193   Configuring the Random Seed Source
194       In most cases OpenSSL will automatically choose a suitable seed source
195       for automatically seeding and reseeding its <master> DRBG. In some
196       cases however, it will be necessary to explicitly specify a seed source
197       during configuration, using the --with-rand-seed option. For more
198       information, see the INSTALL instructions. There are also operating
199       systems where no seed source is available and automatic reseeding is
200       disabled by default.
201
202       The following two sections describe the reseeding process of the master
203       DRBG, depending on whether automatic reseeding is available or not.
204
205   Reseeding the master DRBG with automatic seeding enabled
206       Calling RAND_poll() or RAND_add() is not necessary, because the DRBG
207       pulls the necessary entropy from its source automatically.  However,
208       both calls are permitted, and do reseed the RNG.
209
210       RAND_add() can be used to add both kinds of random input, depending on
211       the value of the randomness argument:
212
213       randomness == 0:
214           The random bytes are mixed as additional input into the current
215           state of the DRBG.  Mixing in additional input is not considered a
216           full reseeding, hence the reseed counter is not reset.
217
218       randomness > 0:
219           The random bytes are used as entropy input for a full reseeding
220           (resp. reinstantiation) if the DRBG is instantiated (resp.
221           uninstantiated or in an error state).  The number of random bits
222           required for reseeding is determined by the security strength of
223           the DRBG. Currently it defaults to 256 bits (32 bytes).  It is
224           possible to provide less randomness than required.  In this case
225           the missing randomness will be obtained by pulling random input
226           from the trusted entropy sources.
227
228   Reseeding the master DRBG with automatic seeding disabled
229       Calling RAND_poll() will always fail.
230
231       RAND_add() needs to be called for initial seeding and periodic
232       reseeding.  At least 48 bytes (384 bits) of randomness have to be
233       provided, otherwise the (re-)seeding of the DRBG will fail. This
234       corresponds to one and a half times the security strength of the DRBG.
235       The extra half is used for the nonce during instantiation.
236
237       More precisely, the number of bytes needed for seeding depend on the
238       security strength of the DRBG, which is set to 256 by default.
239

SEE ALSO

241       RAND_DRBG_bytes(3), RAND_DRBG_generate(3), RAND_DRBG_reseed(3),
242       RAND_DRBG_get0_master(3), RAND_DRBG_get0_public(3),
243       RAND_DRBG_get0_private(3), RAND_DRBG_set_reseed_interval(3),
244       RAND_DRBG_set_reseed_time_interval(3),
245       RAND_DRBG_set_reseed_defaults(3), RAND(7),
246
248       Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
249
250       Licensed under the OpenSSL license (the "License").  You may not use
251       this file except in compliance with the License.  You can obtain a copy
252       in the file LICENSE in the source distribution or at
253       <https://www.openssl.org/source/license.html>.
254
255
256
2571.1.1c                            2019-05-28                      RAND_DRBG(7)
Impressum