1EVP_RAND(7ossl)                     OpenSSL                    EVP_RAND(7ossl)
2
3
4

NAME

6       EVP_RAND - the random bit generator
7

SYNOPSIS

9        #include <openssl/evp.h>
10        #include <rand.h>
11

DESCRIPTION

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

EVP_RAND CHAINING

47       An EVP_RAND instance can be used as the entropy source of another
48       EVP_RAND instance, provided it has itself access to a valid entropy
49       source.  The EVP_RAND instance which acts as entropy source is called
50       the parent, the other instance the child.  Typically, the child will be
51       a DRBG because it does not make sense for the child to be an entropy
52       source.
53
54       This is called chaining. A chained EVP_RAND instance is created by
55       passing a pointer to the parent EVP_RAND_CTX as argument to the
56       EVP_RAND_CTX_new() call.  It is possible to create chains of more than
57       two DRBG in a row.  It is also possible to use any EVP_RAND_CTX class
58       as the parent, however, only a live entropy source may ignore and not
59       use its parent.
60

THE THREE SHARED DRBG INSTANCES

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

LOCKING

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

THE OVERALL PICTURE

106       The following picture gives an overview over how the DRBG instances
107       work together and are being used.
108
109                      +--------------------+
110                      | os entropy sources |
111                      +--------------------+
112                               |
113                               v           +-----------------------------+
114            RAND_add() ==> <primary>     <-| shared DRBG (with locking)  |
115                             /   \         +-----------------------------+
116                            /     \              +---------------------------+
117                     <public>     <private>   <- | per-thread DRBG instances |
118                        |             |          +---------------------------+
119                        v             v
120                      RAND_bytes()   RAND_priv_bytes()
121                           |               ^
122                           |               |
123           +------------------+      +------------------------------------+
124           | general purpose  |      | used for secrets like session keys |
125           | random generator |      | and private keys for certificates  |
126           +------------------+      +------------------------------------+
127
128       The usual way to obtain random bytes is to call RAND_bytes(...) or
129       RAND_priv_bytes(...). These calls are roughly equivalent to calling
130       EVP_RAND_generate(<public>, ...) and EVP_RAND_generate(<private>, ...),
131       respectively.
132

RESEEDING

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

SEE ALSO

253       RAND(7), EVP_RAND(3)
254

HISTORY

256       This functionality was added in OpenSSL 3.0.
257
259       Copyright 2017-2020 The OpenSSL Project Authors. All Rights Reserved.
260
261       Licensed under the Apache License 2.0 (the "License").  You may not use
262       this file except in compliance with the License.  You can obtain a copy
263       in the file LICENSE in the source distribution or at
264       <https://www.openssl.org/source/license.html>.
265
266
267
2683.0.5                             2022-11-01                   EVP_RAND(7ossl)
Impressum