Add prediction resistance capability to the DRBG reseeding process.
[openssl.git] / doc / man7 / RAND_DRBG.pod
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
40 You want to use your own private DRBG instances.
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
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
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
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.
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
192 The document [NIST SP 800-90C] describes prediction resistance requests
193 in detail and imposes strict conditions on the entropy sources that are
194 approved for providing prediction resistance.
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.
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
212 =head2 Entropy Input vs. Additional Data
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
226 however, it will be necessary to explicitly specify a seed source during
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
242 value of the B<randomness> argument:
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
267 =head2 Reseeding the master DRBG with automatic seeding disabled
268
269 Calling RAND_poll() will always fail.
270
271 RAND_add() needs to be called for initial seeding and periodic reseeding.
272 At least 48 bytes (384 bits) of randomness have to be provided, otherwise
273 the (re-)seeding of the DRBG will fail. This corresponds to one and a half
274 times the security strength of the DRBG. The extra half is used for the
275 nonce during instantiation.
276
277 More precisely, the number of bytes needed for seeding depend on the
278 I<security strength> of the DRBG, which is set to 256 by default.
279
280 =head1 SEE ALSO
281
282 L<RAND_DRBG_bytes(3)>,
283 L<RAND_DRBG_generate(3)>,
284 L<RAND_DRBG_reseed(3)>,
285 L<RAND_DRBG_get0_master(3)>,
286 L<RAND_DRBG_get0_public(3)>,
287 L<RAND_DRBG_get0_private(3)>,
288 L<RAND_DRBG_set_reseed_interval(3)>,
289 L<RAND_DRBG_set_reseed_time_interval(3)>,
290 L<RAND_DRBG_set_reseed_defaults(3)>,
291 L<RAND(7)>,
292
293 =head1 COPYRIGHT
294
295 Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
296
297 Licensed under the Apache License 2.0 (the "License").  You may not use
298 this file except in compliance with the License.  You can obtain a copy
299 in the file LICENSE in the source distribution or at
300 L<https://www.openssl.org/source/license.html>.
301
302 =cut