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