Debian Codegraph @

upstream/debian-unstable/man7/EVP_RAND.7ssl

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