xref: /openssl/doc/man7/EVP_RAND.pod (revision 7ed6de99)
1=pod
2
3=head1 NAME
4
5EVP_RAND - the random bit generator
6
7=head1 SYNOPSIS
8
9 #include <openssl/evp.h>
10 #include <rand.h>
11
12=head1 DESCRIPTION
13
14The default OpenSSL RAND method is based on the EVP_RAND classes to provide
15non-deterministic inputs to other cryptographic algorithms.
16
17While the RAND API is the 'frontend' which is intended to be used by
18application developers for obtaining random bytes, the EVP_RAND API
19serves as the 'backend', connecting the former with the operating
20systems's entropy sources and providing access to deterministic random
21bit generators (DRBG) and their configuration parameters.
22A DRBG is a certain type of cryptographically-secure pseudo-random
23number generator (CSPRNG), which is described in
24[NIST SP 800-90A Rev. 1].
25
26=head2 Disclaimer
27
28Unless you have very specific requirements for your random generator,
29it is in general not necessary to utilize the EVP_RAND API directly.
30The usual way to obtain random bytes is to use L<RAND_bytes(3)> or
31L<RAND_priv_bytes(3)>, see also L<RAND(7)>.
32
33=head2 Typical Use Cases
34
35Typical examples for such special use cases are the following:
36
37=over 2
38
39=item *
40
41You want to use your own private DRBG instances.
42Multiple DRBG instances which are accessed only by a single thread provide
43additional security (because their internal states are independent) and
44better scalability in multithreaded applications (because they don't need
45to be locked).
46
47=item *
48
49You need to integrate a previously unsupported entropy source.
50Refer to L<provider-rand(7)> for the implementation details to support adding
51randomness sources to EVP_RAND.
52
53=item *
54
55You need to change the default settings of the standard OpenSSL RAND
56implementation to meet specific requirements.
57
58=back
59
60
61=head1 EVP_RAND CHAINING
62
63An EVP_RAND instance can be used as the entropy source of another
64EVP_RAND instance, provided it has itself access to a valid entropy source.
65The EVP_RAND instance which acts as entropy source is called the I<parent>,
66the other instance the I<child>.  Typically, the child will be a DRBG because
67it does not make sense for the child to be an entropy source.
68
69This is called chaining. A chained EVP_RAND instance is created by passing
70a pointer to the parent EVP_RAND_CTX as argument to the EVP_RAND_CTX_new() call.
71It is possible to create chains of more than two DRBG in a row.
72It is also possible to use any EVP_RAND_CTX class as the parent, however, only
73a live entropy source may ignore and not use its parent.
74
75=head1 THE THREE SHARED DRBG INSTANCES
76
77Currently, there are three shared DRBG instances,
78the <primary>, <public>, and <private> DRBG.
79While the <primary> DRBG is a single global instance, the <public> and <private>
80DRBG are created per thread and accessed through thread-local storage.
81
82By default, the functions L<RAND_bytes(3)> and L<RAND_priv_bytes(3)> use
83the thread-local <public> and <private> DRBG instance, respectively.
84
85=head2 The <primary> DRBG instance
86
87The <primary> DRBG is not used directly by the application, only for reseeding
88the two other two DRBG instances. It reseeds itself by obtaining randomness
89either from os entropy sources or by consuming randomness which was added
90previously by L<RAND_add(3)>.
91
92=head2 The <public> DRBG instance
93
94This instance is used per default by L<RAND_bytes(3)>.
95
96=head2 The <private> DRBG instance
97
98This instance is used per default by L<RAND_priv_bytes(3)>
99
100
101=head1 LOCKING
102
103The <primary> DRBG is intended to be accessed concurrently for reseeding
104by its child DRBG instances. The necessary locking is done internally.
105It is I<not> thread-safe to access the <primary> DRBG directly via the
106EVP_RAND interface.
107The <public> and <private> DRBG are thread-local, i.e. there is an
108instance of each per thread. So they can safely be accessed without
109locking via the EVP_RAND interface.
110
111Pointers to these DRBG instances can be obtained using
112RAND_get0_primary(), RAND_get0_public() and RAND_get0_private(), respectively.
113Note that it is not allowed to store a pointer to one of the thread-local
114DRBG instances in a variable or other memory location where it will be
115accessed and used by multiple threads.
116
117All other DRBG instances created by an application don't support locking,
118because they are intended to be used by a single thread.
119Instead of accessing a single DRBG instance concurrently from different
120threads, it is recommended to instantiate a separate DRBG instance per
121thread. Using the <primary> DRBG as entropy source for multiple DRBG
122instances on different threads is thread-safe, because the DRBG instance
123will lock the <primary> DRBG automatically for obtaining random input.
124
125=head1 THE OVERALL PICTURE
126
127The following picture gives an overview over how the DRBG instances work
128together and are being used.
129
130               +--------------------+
131               | os entropy sources |
132               +--------------------+
133                        |
134                        v           +-----------------------------+
135     RAND_add() ==> <primary>     <-| shared DRBG (with locking)  |
136                      /   \         +-----------------------------+
137                     /     \              +---------------------------+
138              <public>     <private>   <- | per-thread DRBG instances |
139                 |             |          +---------------------------+
140                 v             v
141               RAND_bytes()   RAND_priv_bytes()
142                    |               ^
143                    |               |
144    +------------------+      +------------------------------------+
145    | general purpose  |      | used for secrets like session keys |
146    | random generator |      | and private keys for certificates  |
147    +------------------+      +------------------------------------+
148
149
150The usual way to obtain random bytes is to call RAND_bytes(...) or
151RAND_priv_bytes(...). These calls are roughly equivalent to calling
152EVP_RAND_generate(<public>, ...) and
153EVP_RAND_generate(<private>, ...),
154respectively.
155
156=head1 RESEEDING
157
158A DRBG instance seeds itself automatically, pulling random input from
159its entropy source. The entropy source can be either a trusted operating
160system entropy source, or another DRBG with access to such a source.
161
162Automatic reseeding occurs after a predefined number of generate requests.
163The selection of the trusted entropy sources is configured at build
164time using the --with-rand-seed option. The following sections explain
165the reseeding process in more detail.
166
167=head2 Automatic Reseeding
168
169Before satisfying a generate request (L<EVP_RAND_generate(3)>), the DRBG
170reseeds itself automatically, if one of the following conditions holds:
171
172- the DRBG was not instantiated (=seeded) yet or has been uninstantiated.
173
174- the number of generate requests since the last reseeding exceeds a
175certain threshold, the so called I<reseed_interval>.
176This behaviour can be disabled by setting the I<reseed_interval> to 0.
177
178- the time elapsed since the last reseeding exceeds a certain time
179interval, the so called I<reseed_time_interval>.
180This can be disabled by setting the I<reseed_time_interval> to 0.
181
182- the DRBG is in an error state.
183
184B<Note>: An error state is entered if the entropy source fails while
185the DRBG is seeding or reseeding.
186The last case ensures that the DRBG automatically recovers
187from the error as soon as the entropy source is available again.
188
189=head2 Manual Reseeding
190
191In addition to automatic reseeding, the caller can request an immediate
192reseeding of the DRBG with fresh entropy by setting the
193I<prediction resistance> parameter to 1 when calling
194L<EVP_RAND_generate(3)>.
195
196The document [NIST SP 800-90C] describes prediction resistance requests
197in detail and imposes strict conditions on the entropy sources that are
198approved for providing prediction resistance.
199A request for prediction resistance can only be satisfied by pulling fresh
200entropy from a live entropy source (section 5.5.2 of [NIST SP 800-90C]).
201It is up to the user to ensure that a live entropy source is configured
202and is being used.
203
204For the three shared DRBGs (and only for these) there is another way to
205reseed them manually:
206If L<RAND_add(3)> is called with a positive I<randomness> argument
207(or L<RAND_seed(3)>), then this will immediately reseed the <primary> DRBG.
208The <public> and <private> DRBG will detect this on their next generate
209call and reseed, pulling randomness from <primary>.
210
211The last feature has been added to support the common practice used with
212previous OpenSSL versions to call RAND_add() before calling RAND_bytes().
213
214
215=head2 Entropy Input and Additional Data
216
217The DRBG distinguishes two different types of random input: I<entropy>,
218which comes from a trusted source, and I<additional input>',
219which can optionally be added by the user and is considered untrusted.
220It is possible to add I<additional input> not only during reseeding,
221but also for every generate request.
222
223
224=head2 Configuring the Random Seed Source
225
226In most cases OpenSSL will automatically choose a suitable seed source
227for automatically seeding and reseeding its <primary> DRBG. The
228default seed source can be configured when OpenSSL is compiled by
229setting B<-DOPENSSL_DEFAULT_SEED_SRC=SEED-SRC>. If not set then
230"SEED-SRC" is used. One can specify a third-party provider seed-source,
231or B<-DOPENSSL_DEFAULT_SEED_SRC=JITTER> if available.
232
233In some cases however, it will be necessary to explicitly specify a
234seed source used by "SEED-SRC" during configuration, using the
235--with-rand-seed option. For more information, see the INSTALL
236instructions. There are also operating systems where no seed source is
237available and automatic reseeding is disabled by default.
238
239The following two sections describe the reseeding process of the primary
240DRBG, depending on whether automatic reseeding is available or not.
241
242
243=head2 Reseeding the primary DRBG with automatic seeding enabled
244
245Calling RAND_poll() or RAND_add() is not necessary, because the DRBG
246pulls the necessary entropy from its source automatically.
247However, both calls are permitted, and do reseed the RNG.
248
249RAND_add() can be used to add both kinds of random input, depending on the
250value of the I<randomness> argument:
251
252=over 4
253
254=item randomness == 0:
255
256The random bytes are mixed as additional input into the current state of
257the DRBG.
258Mixing in additional input is not considered a full reseeding, hence the
259reseed counter is not reset.
260
261
262=item randomness > 0:
263
264The random bytes are used as entropy input for a full reseeding
265(resp. reinstantiation) if the DRBG is instantiated
266(resp. uninstantiated or in an error state).
267The number of random bits required for reseeding is determined by the
268security strength of the DRBG. Currently it defaults to 256 bits (32 bytes).
269It is possible to provide less randomness than required.
270In this case the missing randomness will be obtained by pulling random input
271from the trusted entropy sources.
272
273=back
274
275NOTE: Manual reseeding is *not allowed* in FIPS mode, because
276[NIST SP-800-90Ar1] mandates that entropy *shall not* be provided by
277the consuming application for instantiation (Section 9.1) or
278reseeding (Section 9.2). For that reason, the I<randomness>
279argument is ignored and the random bytes provided by the L<RAND_add(3)> and
280L<RAND_seed(3)> calls are treated as additional data.
281
282=head2 Reseeding the primary DRBG with automatic seeding disabled
283
284Calling RAND_poll() will always fail.
285
286RAND_add() needs to be called for initial seeding and periodic reseeding.
287At least 48 bytes (384 bits) of randomness have to be provided, otherwise
288the (re-)seeding of the DRBG will fail. This corresponds to one and a half
289times the security strength of the DRBG. The extra half is used for the
290nonce during instantiation.
291
292More precisely, the number of bytes needed for seeding depend on the
293I<security strength> of the DRBG, which is set to 256 by default.
294
295=head1 SEE ALSO
296
297L<RAND(7)>, L<EVP_RAND(3)>
298
299=head1 HISTORY
300
301This functionality was added in OpenSSL 3.0.
302
303=head1 COPYRIGHT
304
305Copyright 2017-2024 The OpenSSL Project Authors. All Rights Reserved.
306
307Licensed under the Apache License 2.0 (the "License").  You may not use
308this file except in compliance with the License.  You can obtain a copy
309in the file LICENSE in the source distribution or at
310L<https://www.openssl.org/source/license.html>.
311
312=cut
313