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