]>
Commit | Line | Data |
---|---|---|
dc4e74ef P |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | EVP_RAND, EVP_RAND_fetch, EVP_RAND_free, EVP_RAND_up_ref, EVP_RAND_CTX, | |
6 | EVP_RAND_CTX_new, EVP_RAND_CTX_free, EVP_RAND_instantiate, | |
03888233 RL |
7 | EVP_RAND_uninstantiate, EVP_RAND_generate, EVP_RAND_reseed, EVP_RAND_nonce, |
8 | EVP_RAND_enable_locking, EVP_RAND_verify_zeroization, EVP_RAND_strength, | |
9 | EVP_RAND_state, | |
dc4e74ef | 10 | EVP_RAND_provider, EVP_RAND_CTX_rand, EVP_RAND_is_a, EVP_RAND_number, |
03888233 | 11 | EVP_RAND_name, EVP_RAND_names_do_all, EVP_RAND_description, |
e494fac7 P |
12 | EVP_RAND_CTX_get_params, |
13 | EVP_RAND_CTX_set_params, EVP_RAND_do_all_provided, EVP_RAND_get_params, | |
dc4e74ef | 14 | EVP_RAND_gettable_ctx_params, EVP_RAND_settable_ctx_params, |
90fec26d | 15 | EVP_RAND_CTX_gettable_params, EVP_RAND_CTX_settable_params, |
dc4e74ef P |
16 | EVP_RAND_gettable_params, EVP_RAND_STATE_UNINITIALISED, EVP_RAND_STATE_READY, |
17 | EVP_RAND_STATE_ERROR - EVP RAND routines | |
18 | ||
19 | =head1 SYNOPSIS | |
20 | ||
21 | #include <openssl/evp.h> | |
22 | ||
23 | typedef struct evp_rand_st EVP_RAND; | |
24 | typedef struct evp_rand_ctx_st EVP_RAND_CTX; | |
25 | ||
b4250010 | 26 | EVP_RAND *EVP_RAND_fetch(OSSL_LIB_CTX *libctx, const char *algorithm, |
dc4e74ef P |
27 | const char *properties); |
28 | int EVP_RAND_up_ref(EVP_RAND *rand); | |
29 | void EVP_RAND_free(EVP_RAND *rand); | |
30 | EVP_RAND_CTX *EVP_RAND_CTX_new(EVP_RAND *rand, EVP_RAND_CTX *parent); | |
31 | void EVP_RAND_CTX_free(EVP_RAND_CTX *ctx); | |
32 | EVP_RAND *EVP_RAND_CTX_rand(EVP_RAND_CTX *ctx); | |
33 | int EVP_RAND_get_params(EVP_RAND *rand, OSSL_PARAM params[]); | |
e494fac7 P |
34 | int EVP_RAND_CTX_get_params(EVP_RAND_CTX *ctx, OSSL_PARAM params[]); |
35 | int EVP_RAND_CTX_set_params(EVP_RAND_CTX *ctx, const OSSL_PARAM params[]); | |
dc4e74ef P |
36 | const OSSL_PARAM *EVP_RAND_gettable_params(const EVP_RAND *rand); |
37 | const OSSL_PARAM *EVP_RAND_gettable_ctx_params(const EVP_RAND *rand); | |
38 | const OSSL_PARAM *EVP_RAND_settable_ctx_params(const EVP_RAND *rand); | |
90fec26d P |
39 | const OSSL_PARAM *EVP_RAND_CTX_gettable_params(EVP_RAND_CTX *ctx); |
40 | const OSSL_PARAM *EVP_RAND_CTX_settable_params(EVP_RAND_CTX *ctx); | |
dc4e74ef P |
41 | int EVP_RAND_number(const EVP_RAND *rand); |
42 | const char *EVP_RAND_name(const EVP_RAND *rand); | |
03888233 | 43 | const char *EVP_RAND_description(const EVP_RAND *rand); |
dc4e74ef P |
44 | int EVP_RAND_is_a(const EVP_RAND *rand, const char *name); |
45 | const OSSL_PROVIDER *EVP_RAND_provider(const EVP_RAND *rand); | |
b4250010 | 46 | void EVP_RAND_do_all_provided(OSSL_LIB_CTX *libctx, |
dc4e74ef P |
47 | void (*fn)(EVP_RAND *rand, void *arg), |
48 | void *arg); | |
d84f5515 MC |
49 | int EVP_RAND_names_do_all(const EVP_RAND *rand, |
50 | void (*fn)(const char *name, void *data), | |
51 | void *data); | |
dc4e74ef P |
52 | |
53 | int EVP_RAND_instantiate(EVP_RAND_CTX *ctx, unsigned int strength, | |
54 | int prediction_resistance, | |
671ff5c7 P |
55 | const unsigned char *pstr, size_t pstr_len, |
56 | const OSSL_PARAM params[]); | |
dc4e74ef P |
57 | int EVP_RAND_uninstantiate(EVP_RAND_CTX *ctx); |
58 | int EVP_RAND_generate(EVP_RAND_CTX *ctx, unsigned char *out, size_t outlen, | |
59 | unsigned int strength, int prediction_resistance, | |
60 | const unsigned char *addin, size_t addin_len); | |
61 | int EVP_RAND_reseed(EVP_RAND_CTX *ctx, int prediction_resistance, | |
62 | const unsigned char *ent, size_t ent_len, | |
63 | const unsigned char *addin, size_t addin_len); | |
64 | int EVP_RAND_nonce(EVP_RAND_CTX *ctx, unsigned char *out, size_t outlen); | |
65 | int EVP_RAND_enable_locking(EVP_RAND_CTX *ctx); | |
dc4e74ef P |
66 | int EVP_RAND_verify_zeroization(EVP_RAND_CTX *ctx); |
67 | unsigned int EVP_RAND_strength(EVP_RAND_CTX *ctx); | |
68 | int EVP_RAND_state(EVP_RAND_CTX *ctx); | |
69 | ||
70 | #define EVP_RAND_STATE_UNINITIALISED 0 | |
71 | #define EVP_RAND_STATE_READY 1 | |
72 | #define EVP_RAND_STATE_ERROR 2 | |
73 | ||
74 | =head1 DESCRIPTION | |
75 | ||
8c1cbc72 | 76 | The EVP RAND routines are a high-level interface to random number generators |
dc4e74ef P |
77 | both deterministic and not. |
78 | If you just want to generate random bytes then you don't need to use | |
79 | these functions: just call RAND_bytes() or RAND_priv_bytes(). | |
80 | If you want to do more, these calls should be used instead of the older | |
81 | RAND and RAND_DRBG functions. | |
82 | ||
83 | After creating a B<EVP_RAND_CTX> for the required algorithm using | |
671ff5c7 P |
84 | EVP_RAND_CTX_new(), inputs to the algorithm are supplied either by |
85 | passing them as part of the EVP_RAND_instantiate() call or using calls to | |
e494fac7 | 86 | EVP_RAND_CTX_set_params() before calling EVP_RAND_instantiate(). Finally, |
671ff5c7 | 87 | call EVP_RAND_generate() to produce cryptographically secure random bytes. |
dc4e74ef P |
88 | |
89 | =head2 Types | |
90 | ||
91 | B<EVP_RAND> is a type that holds the implementation of a RAND. | |
92 | ||
93 | B<EVP_RAND_CTX> is a context type that holds the algorithm inputs. | |
4640cd00 | 94 | B<EVP_RAND_CTX> structures are reference counted. |
dc4e74ef P |
95 | |
96 | =head2 Algorithm implementation fetching | |
97 | ||
98 | EVP_RAND_fetch() fetches an implementation of a RAND I<algorithm>, given | |
99 | a library context I<libctx> and a set of I<properties>. | |
906bced1 | 100 | See L<crypto(7)/ALGORITHM FETCHING> for further information. |
dc4e74ef P |
101 | |
102 | The returned value must eventually be freed with | |
103 | L<EVP_RAND_free(3)>. | |
104 | ||
105 | EVP_RAND_up_ref() increments the reference count of an already fetched | |
106 | RAND. | |
107 | ||
108 | EVP_RAND_free() frees a fetched algorithm. | |
109 | NULL is a valid parameter, for which this function is a no-op. | |
110 | ||
111 | =head2 Context manipulation functions | |
112 | ||
113 | EVP_RAND_CTX_new() creates a new context for the RAND implementation I<rand>. | |
114 | If not NULL, I<parent> specifies the seed source for this implementation. | |
115 | Not all random number generators need to have a seed source specified. | |
116 | If a parent is required, a NULL I<parent> will utilise the operating | |
117 | system entropy sources. | |
118 | It is recommended to minimise the number of random number generators that | |
119 | rely on the operating system for their randomness because this is often scarce. | |
120 | ||
121 | EVP_RAND_CTX_free() frees up the context I<ctx>. If I<ctx> is NULL, nothing | |
122 | is done. | |
123 | ||
124 | EVP_RAND_CTX_rand() returns the B<EVP_RAND> associated with the context | |
125 | I<ctx>. | |
126 | ||
127 | =head2 Random Number Generator Functions | |
128 | ||
671ff5c7 P |
129 | EVP_RAND_instantiate() processes any parameters in I<params> and |
130 | then instantiates the RAND I<ctx> with a minimum security strength | |
131 | of <strength> and personalisation string I<pstr> of length <pstr_len>. | |
dc4e74ef P |
132 | If I<prediction_resistance> is specified, fresh entropy from a live source |
133 | will be sought. This call operates as per NIST SP 800-90A and SP 800-90C. | |
134 | ||
135 | EVP_RAND_uninstantiate() uninstantiates the RAND I<ctx> as per | |
136 | NIST SP 800-90A and SP 800-90C. Subsequent to this call, the RAND cannot | |
137 | be used to generate bytes. It can only be freed or instantiated again. | |
138 | ||
139 | EVP_RAND_generate() produces random bytes from the RAND I<ctx> with the | |
140 | additional input I<addin> of length I<addin_len>. The bytes | |
141 | produced will meet the security I<strength>. | |
142 | If I<prediction_resistance> is specified, fresh entropy from a live source | |
143 | will be sought. This call operates as per NIST SP 800-90A and SP 800-90C. | |
144 | ||
145 | EVP_RAND_reseed() reseeds the RAND with new entropy. | |
146 | Entropy I<ent> of length I<ent_len> bytes can be supplied as can additional | |
147 | input I<addin> of length I<addin_len> bytes. In the FIPS provider, both are | |
148 | treated as additional input as per NIST SP-800-90Ar1, Sections 9.1 and 9.2. | |
149 | Additional seed material is also drawn from the RAND's parent or the | |
150 | operating system. If I<prediction_resistance> is specified, fresh entropy | |
151 | from a live source will be sought. This call operates as per NIST SP 800-90A | |
152 | and SP 800-90C. | |
153 | ||
154 | EVP_RAND_nonce() creates a nonce in I<out> of maximum length I<outlen> | |
155 | bytes from the RAND I<ctx>. The function returns the length of the generated | |
156 | nonce. If I<out> is NULL, the length is still returned but no generation | |
157 | takes place. This allows a caller to dynamically allocate a buffer of the | |
158 | appropriate size. | |
159 | ||
160 | EVP_RAND_enable_locking() enables locking for the RAND I<ctx> and all of | |
161 | its parents. After this I<ctx> will operate in a thread safe manner, albeit | |
f5a50c2a MC |
162 | more slowly. This function is not itself thread safe if called with the same |
163 | I<ctx> from multiple threads. Typically locking should be enabled before a | |
164 | I<ctx> is shared across multiple threads. | |
dc4e74ef | 165 | |
dc4e74ef P |
166 | EVP_RAND_get_params() retrieves details about the implementation |
167 | I<rand>. | |
168 | The set of parameters given with I<params> determine exactly what | |
169 | parameters should be retrieved. | |
170 | Note that a parameter that is unknown in the underlying context is | |
171 | simply ignored. | |
172 | ||
e494fac7 | 173 | EVP_RAND_CTX_get_params() retrieves chosen parameters, given the |
dc4e74ef P |
174 | context I<ctx> and its underlying context. |
175 | The set of parameters given with I<params> determine exactly what | |
176 | parameters should be retrieved. | |
177 | Note that a parameter that is unknown in the underlying context is | |
178 | simply ignored. | |
179 | ||
e494fac7 | 180 | EVP_RAND_CTX_set_params() passes chosen parameters to the underlying |
dc4e74ef P |
181 | context, given a context I<ctx>. |
182 | The set of parameters given with I<params> determine exactly what | |
183 | parameters are passed down. | |
184 | Note that a parameter that is unknown in the underlying context is | |
185 | simply ignored. | |
186 | Also, what happens when a needed parameter isn't passed down is | |
187 | defined by the implementation. | |
188 | ||
90fec26d P |
189 | EVP_RAND_gettable_params() returns an B<OSSL_PARAM> array that describes |
190 | the retrievable and settable parameters. EVP_RAND_gettable_params() returns | |
191 | parameters that can be used with EVP_RAND_get_params(). See L<OSSL_PARAM(3)> | |
192 | for the use of B<OSSL_PARAM> as a parameter descriptor. | |
193 | ||
194 | EVP_RAND_gettable_ctx_params() and EVP_RAND_CTX_gettable_params() return | |
195 | constant B<OSSL_PARAM> arrays that describe the retrievable parameters that | |
196 | can be used with EVP_RAND_CTX_get_params(). EVP_RAND_gettable_ctx_params() | |
197 | returns the parameters that can be retrieved from the algorithm, whereas | |
198 | EVP_RAND_CTX_gettable_params() returns the parameters that can be retrieved | |
199 | in the context's current state. See L<OSSL_PARAM(3)> for the use of | |
200 | B<OSSL_PARAM> as a parameter descriptor. | |
201 | ||
202 | EVP_RAND_settable_ctx_params() and EVP_RAND_CTX_settable_params() return | |
203 | constant B<OSSL_PARAM> arrays that describe the settable parameters that | |
204 | can be used with EVP_RAND_CTX_set_params(). EVP_RAND_settable_ctx_params() | |
205 | returns the parameters that can be retrieved from the algorithm, whereas | |
206 | EVP_RAND_CTX_settable_params() returns the parameters that can be retrieved | |
207 | in the context's current state. See L<OSSL_PARAM(3)> for the use of | |
208 | B<OSSL_PARAM> as a parameter descriptor. | |
dc4e74ef P |
209 | |
210 | =head2 Information functions | |
211 | ||
212 | EVP_RAND_strength() returns the security strength of the RAND I<ctx>. | |
213 | ||
214 | EVP_RAND_state() returns the current state of the RAND I<ctx>. | |
7d615e21 | 215 | States defined by the OpenSSL RNGs are: |
dc4e74ef P |
216 | |
217 | =over 4 | |
218 | ||
219 | =item * | |
220 | ||
7d615e21 | 221 | EVP_RAND_STATE_UNINITIALISED: this RNG is currently uninitialised. |
dc4e74ef P |
222 | The instantiate call will change this to the ready state. |
223 | ||
224 | =item * | |
225 | ||
7d615e21 | 226 | EVP_RAND_STATE_READY: this RNG is currently ready to generate output. |
dc4e74ef P |
227 | |
228 | =item * | |
229 | ||
7d615e21 | 230 | EVP_RAND_STATE_ERROR: this RNG is in an error state. |
dc4e74ef P |
231 | |
232 | =back | |
233 | ||
234 | EVP_RAND_is_a() returns 1 if I<rand> is an implementation of an | |
235 | algorithm that's identifiable with I<name>, otherwise 0. | |
236 | ||
237 | EVP_RAND_provider() returns the provider that holds the implementation | |
238 | of the given I<rand>. | |
239 | ||
240 | EVP_RAND_do_all_provided() traverses all RAND implemented by all activated | |
241 | providers in the given library context I<libctx>, and for each of the | |
242 | implementations, calls the given function I<fn> with the implementation method | |
243 | and the given I<arg> as argument. | |
244 | ||
245 | EVP_RAND_number() returns the internal dynamic number assigned to | |
246 | I<rand>. | |
247 | ||
248 | EVP_RAND_name() returns the canonical name of I<rand>. | |
249 | ||
250 | EVP_RAND_names_do_all() traverses all names for I<rand>, and calls | |
251 | I<fn> with each name and I<data>. | |
252 | ||
03888233 RL |
253 | EVP_RAND_description() returns a description of the rand, meant for display |
254 | and human consumption. The description is at the discretion of the rand | |
255 | implementation. | |
256 | ||
dc4e74ef P |
257 | EVP_RAND_verify_zeroization() confirms if the internal DRBG state is |
258 | currently zeroed. This is used by the FIPS provider to support the mandatory | |
259 | self tests. | |
260 | ||
261 | =head1 PARAMETERS | |
262 | ||
263 | The standard parameter names are: | |
264 | ||
265 | =over 4 | |
266 | ||
267 | =item "state" (B<OSSL_RAND_PARAM_STATE>) <integer> | |
268 | ||
269 | Returns the state of the random number generator. | |
270 | ||
271 | =item "strength" (B<OSSL_RAND_PARAM_STRENGTH>) <unsigned integer> | |
272 | ||
273 | Returns the bit strength of the random number generator. | |
274 | ||
275 | =back | |
276 | ||
277 | For rands that are also deterministic random bit generators (DRBGs), these | |
278 | additional parameters are recognised. Not all | |
279 | parameters are relevant to, or are understood by all DRBG rands: | |
280 | ||
281 | =over 4 | |
282 | ||
283 | =item "reseed_requests" (B<OSSL_DRBG_PARAM_RESEED_REQUESTS>) <unsigned integer> | |
284 | ||
285 | Reads or set the number of generate requests before reseeding the | |
286 | associated RAND ctx. | |
287 | ||
288 | =item "reseed_time_interval" (B<OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL>) <integer> | |
289 | ||
290 | Reads or set the number of elapsed seconds before reseeding the | |
291 | associated RAND ctx. | |
292 | ||
293 | =item "max_request" (B<OSSL_DRBG_PARAM_RESEED_REQUESTS>) <unsigned integer> | |
294 | ||
295 | Specifies the maximum number of bytes that can be generated in a single | |
363b1e5d | 296 | call to OSSL_FUNC_rand_generate. |
dc4e74ef P |
297 | |
298 | =item "min_entropylen" (B<OSSL_DRBG_PARAM_MIN_ENTROPYLEN>) <unsigned integer> | |
299 | ||
300 | =item "max_entropylen" (B<OSSL_DRBG_PARAM_MAX_ENTROPYLEN>) <unsigned integer> | |
301 | ||
302 | Specify the minimum and maximum number of bytes of random material that | |
303 | can be used to seed the DRBG. | |
304 | ||
305 | =item "min_noncelen" (B<OSSL_DRBG_PARAM_MIN_NONCELEN>) <unsigned integer> | |
306 | ||
307 | =item "max_noncelen" (B<OSSL_DRBG_PARAM_MAX_NONCELEN>) <unsigned integer> | |
308 | ||
309 | Specify the minimum and maximum number of bytes of nonce that can be used to | |
310 | seed the DRBG. | |
311 | ||
312 | =item "max_perslen" (B<OSSL_DRBG_PARAM_MAX_PERSLEN>) <unsigned integer> | |
313 | ||
314 | =item "max_adinlen" (B<OSSL_DRBG_PARAM_MAX_ADINLEN>) <unsigned integer> | |
315 | ||
316 | Specify the minimum and maximum number of bytes of personalisation string | |
317 | that can be used with the DRBG. | |
318 | ||
b0614f0a | 319 | =item "reseed_counter" (B<OSSL_DRBG_PARAM_RESEED_COUNTER>) <unsigned integer> |
dc4e74ef P |
320 | |
321 | Specifies the number of times the DRBG has been seeded or reseeded. | |
322 | ||
323 | =item "properties" (B<OSSL_RAND_PARAM_PROPERTIES>) <UTF8 string> | |
324 | ||
325 | =item "mac" (B<OSSL_RAND_PARAM_MAC>) <UTF8 string> | |
326 | ||
327 | =item "digest" (B<OSSL_RAND_PARAM_DIGEST>) <UTF8 string> | |
328 | ||
329 | =item "cipher" (B<OSSL_RAND_PARAM_CIPHER>) <UTF8 string> | |
330 | ||
331 | For RAND implementations that use an underlying computation MAC, digest or | |
332 | cipher, these parameters set what the algorithm should be. | |
333 | ||
334 | The value is always the name of the intended algorithm, | |
335 | or the properties in the case of B<OSSL_RAND_PARAM_PROPERTIES>. | |
336 | ||
337 | =back | |
338 | ||
8b3facd7 P |
339 | =head1 NOTES |
340 | ||
341 | An B<EVP_RAND_CTX> needs to have locking enabled if it acts as the parent of | |
342 | more than one child and the children can be accessed concurrently. This must | |
343 | be done by explicitly calling EVP_RAND_enable_locking(). | |
344 | ||
632bc4df P |
345 | The RAND life-cycle is described in L<life_cycle-rand(7)>. In the future, |
346 | the transitions described there will be enforced. When this is done, it will | |
347 | not be considered a breaking change to the API. | |
348 | ||
dc4e74ef P |
349 | =head1 RETURN VALUES |
350 | ||
351 | EVP_RAND_fetch() returns a pointer to a newly fetched B<EVP_RAND>, or | |
352 | NULL if allocation failed. | |
353 | ||
354 | EVP_RAND_provider() returns a pointer to the provider for the RAND, or | |
355 | NULL on error. | |
356 | ||
357 | EVP_RAND_CTX_rand() returns a pointer to the B<EVP_RAND> associated with the | |
358 | context. | |
359 | ||
360 | EVP_RAND_name() returns the name of the random number generation algorithm. | |
361 | ||
362 | EVP_RAND_number() returns the provider specific identification number | |
363 | for the specified algorithm. | |
364 | ||
365 | EVP_RAND_up_ref() returns 1 on success, 0 on error. | |
366 | ||
d84f5515 MC |
367 | EVP_RAND_names_do_all() returns 1 if the callback was called for all names. A |
368 | return value of 0 means that the callback was not called for any names. | |
369 | ||
dc4e74ef P |
370 | EVP_RAND_CTX_new() returns either the newly allocated |
371 | B<EVP_RAND_CTX> structure or NULL if an error occurred. | |
372 | ||
373 | EVP_RAND_CTX_free() does not return a value. | |
374 | ||
375 | EVP_RAND_nonce() returns the length of the nonce. | |
376 | ||
8c1cbc72 | 377 | EVP_RAND_strength() returns the strength of the random number generator in bits. |
dc4e74ef P |
378 | |
379 | EVP_RAND_gettable_params(), EVP_RAND_gettable_ctx_params() and | |
380 | EVP_RAND_settable_ctx_params() return an array of OSSL_PARAMs. | |
381 | ||
382 | EVP_RAND_verify_zeroization() returns 1 if the internal DRBG state is | |
383 | currently zeroed, and 0 if not. | |
384 | ||
385 | The remaining functions return 1 for success and 0 or a negative value for | |
386 | failure. | |
387 | ||
388 | =head1 SEE ALSO | |
389 | ||
390 | L<RAND_bytes(3)>, | |
391 | L<EVP_RAND-CTR-DRBG(7)>, | |
392 | L<EVP_RAND-HASH-DRBG(7)>, | |
393 | L<EVP_RAND-HMAC-DRBG(7)>, | |
394 | L<EVP_RAND-TEST-RAND(7)>, | |
632bc4df P |
395 | L<provider-rand(7)>, |
396 | L<life_cycle-rand(7)> | |
dc4e74ef P |
397 | |
398 | =head1 HISTORY | |
399 | ||
400 | This functionality was added to OpenSSL 3.0. | |
401 | ||
402 | =head1 COPYRIGHT | |
403 | ||
4333b89f | 404 | Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved. |
dc4e74ef P |
405 | |
406 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
407 | this file except in compliance with the License. You can obtain a copy | |
408 | in the file LICENSE in the source distribution or at | |
409 | L<https://www.openssl.org/source/license.html>. | |
410 | ||
411 | =cut |