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