1EVP_RAND(3ossl)                     OpenSSL                    EVP_RAND(3ossl)
2
3
4

NAME

6       EVP_RAND, EVP_RAND_fetch, EVP_RAND_free, EVP_RAND_up_ref, EVP_RAND_CTX,
7       EVP_RAND_CTX_new, EVP_RAND_CTX_free, EVP_RAND_instantiate,
8       EVP_RAND_uninstantiate, EVP_RAND_generate, EVP_RAND_reseed,
9       EVP_RAND_nonce, EVP_RAND_enable_locking, EVP_RAND_verify_zeroization,
10       EVP_RAND_get_strength, EVP_RAND_get_state, EVP_RAND_get0_provider,
11       EVP_RAND_CTX_get0_rand, EVP_RAND_is_a, EVP_RAND_get0_name,
12       EVP_RAND_names_do_all, EVP_RAND_get0_description,
13       EVP_RAND_CTX_get_params, EVP_RAND_CTX_set_params,
14       EVP_RAND_do_all_provided, EVP_RAND_get_params,
15       EVP_RAND_gettable_ctx_params, EVP_RAND_settable_ctx_params,
16       EVP_RAND_CTX_gettable_params, EVP_RAND_CTX_settable_params,
17       EVP_RAND_gettable_params, EVP_RAND_STATE_UNINITIALISED,
18       EVP_RAND_STATE_READY, EVP_RAND_STATE_ERROR - EVP RAND routines
19

SYNOPSIS

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
26        EVP_RAND *EVP_RAND_fetch(OSSL_LIB_CTX *libctx, const char *algorithm,
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_get0_rand(EVP_RAND_CTX *ctx);
33        int EVP_RAND_get_params(EVP_RAND *rand, OSSL_PARAM params[]);
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[]);
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);
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);
41        const char *EVP_RAND_get0_name(const EVP_RAND *rand);
42        const char *EVP_RAND_get0_description(const EVP_RAND *rand);
43        int EVP_RAND_is_a(const EVP_RAND *rand, const char *name);
44        const OSSL_PROVIDER *EVP_RAND_get0_provider(const EVP_RAND *rand);
45        void EVP_RAND_do_all_provided(OSSL_LIB_CTX *libctx,
46                                      void (*fn)(EVP_RAND *rand, void *arg),
47                                      void *arg);
48        int EVP_RAND_names_do_all(const EVP_RAND *rand,
49                                  void (*fn)(const char *name, void *data),
50                                  void *data);
51
52        int EVP_RAND_instantiate(EVP_RAND_CTX *ctx, unsigned int strength,
53                                 int prediction_resistance,
54                                 const unsigned char *pstr, size_t pstr_len,
55                                 const OSSL_PARAM params[]);
56        int EVP_RAND_uninstantiate(EVP_RAND_CTX *ctx);
57        int EVP_RAND_generate(EVP_RAND_CTX *ctx, unsigned char *out, size_t outlen,
58                              unsigned int strength, int prediction_resistance,
59                              const unsigned char *addin, size_t addin_len);
60        int EVP_RAND_reseed(EVP_RAND_CTX *ctx, int prediction_resistance,
61                            const unsigned char *ent, size_t ent_len,
62                            const unsigned char *addin, size_t addin_len);
63        int EVP_RAND_nonce(EVP_RAND_CTX *ctx, unsigned char *out, size_t outlen);
64        int EVP_RAND_enable_locking(EVP_RAND_CTX *ctx);
65        int EVP_RAND_verify_zeroization(EVP_RAND_CTX *ctx);
66        unsigned int EVP_RAND_get_strength(EVP_RAND_CTX *ctx);
67        int EVP_RAND_get_state(EVP_RAND_CTX *ctx);
68
69        #define EVP_RAND_STATE_UNINITIALISED    0
70        #define EVP_RAND_STATE_READY            1
71        #define EVP_RAND_STATE_ERROR            2
72

DESCRIPTION

74       The EVP RAND routines are a high-level interface to random number
75       generators both deterministic and not.  If you just want to generate
76       random bytes then you don't need to use these functions: just call
77       RAND_bytes() or RAND_priv_bytes().  If you want to do more, these calls
78       should be used instead of the older RAND and RAND_DRBG functions.
79
80       After creating a EVP_RAND_CTX for the required algorithm using
81       EVP_RAND_CTX_new(), inputs to the algorithm are supplied either by
82       passing them as part of the EVP_RAND_instantiate() call or using calls
83       to EVP_RAND_CTX_set_params() before calling EVP_RAND_instantiate().
84       Finally, call EVP_RAND_generate() to produce cryptographically secure
85       random bytes.
86
87   Types
88       EVP_RAND is a type that holds the implementation of a RAND.
89
90       EVP_RAND_CTX is a context type that holds the algorithm inputs.
91       EVP_RAND_CTX structures are reference counted.
92
93   Algorithm implementation fetching
94       EVP_RAND_fetch() fetches an implementation of a RAND algorithm, given a
95       library context libctx and a set of properties.  See "ALGORITHM
96       FETCHING" in crypto(7) for further information.
97
98       The returned value must eventually be freed with EVP_RAND_free(3).
99
100       EVP_RAND_up_ref() increments the reference count of an already fetched
101       RAND.
102
103       EVP_RAND_free() frees a fetched algorithm.  NULL is a valid parameter,
104       for which this function is a no-op.
105
106   Context manipulation functions
107       EVP_RAND_CTX_new() creates a new context for the RAND implementation
108       rand.  If not NULL, parent specifies the seed source for this
109       implementation.  Not all random number generators need to have a seed
110       source specified.  If a parent is required, a NULL parent will utilise
111       the operating system entropy sources.  It is recommended to minimise
112       the number of random number generators that rely on the operating
113       system for their randomness because this is often scarce.
114
115       EVP_RAND_CTX_free() frees up the context ctx.  If ctx is NULL, nothing
116       is done.
117
118       EVP_RAND_CTX_get0_rand() returns the EVP_RAND associated with the
119       context ctx.
120
121   Random Number Generator Functions
122       EVP_RAND_instantiate() processes any parameters in params and then
123       instantiates the RAND ctx with a minimum security strength of
124       <strength> and personalisation string pstr of length <pstr_len>.  If
125       prediction_resistance is specified, fresh entropy from a live source
126       will be sought.  This call operates as per NIST SP 800-90A and SP
127       800-90C.
128
129       EVP_RAND_uninstantiate() uninstantiates the RAND ctx as per NIST SP
130       800-90A and SP 800-90C.  Subsequent to this call, the RAND cannot be
131       used to generate bytes.  It can only be freed or instantiated again.
132
133       EVP_RAND_generate() produces random bytes from the RAND ctx with the
134       additional input addin of length addin_len.  The bytes produced will
135       meet the security strength.  If prediction_resistance is specified,
136       fresh entropy from a live source will be sought.  This call operates as
137       per NIST SP 800-90A and SP 800-90C.
138
139       EVP_RAND_reseed() reseeds the RAND with new entropy.  Entropy ent of
140       length ent_len bytes can be supplied as can additional input addin of
141       length addin_len bytes.  In the FIPS provider, both are treated as
142       additional input as per NIST SP-800-90Ar1, Sections 9.1 and 9.2.
143       Additional seed material is also drawn from the RAND's parent or the
144       operating system.  If prediction_resistance is specified, fresh entropy
145       from a live source will be sought.  This call operates as per NIST SP
146       800-90A and SP 800-90C.
147
148       EVP_RAND_nonce() creates a nonce in out of maximum length outlen bytes
149       from the RAND ctx. The function returns the length of the generated
150       nonce. If out is NULL, the length is still returned but no generation
151       takes place. This allows a caller to dynamically allocate a buffer of
152       the appropriate size.
153
154       EVP_RAND_enable_locking() enables locking for the RAND ctx and all of
155       its parents.  After this ctx will operate in a thread safe manner,
156       albeit more slowly. This function is not itself thread safe if called
157       with the same ctx from multiple threads. Typically locking should be
158       enabled before a ctx is shared across multiple threads.
159
160       EVP_RAND_get_params() retrieves details about the implementation rand.
161       The set of parameters given with params determine exactly what
162       parameters should be retrieved.  Note that a parameter that is unknown
163       in the underlying context is simply ignored.
164
165       EVP_RAND_CTX_get_params() retrieves chosen parameters, given the
166       context ctx and its underlying context.  The set of parameters given
167       with params determine exactly what parameters should be retrieved.
168       Note that a parameter that is unknown in the underlying context is
169       simply ignored.
170
171       EVP_RAND_CTX_set_params() passes chosen parameters to the underlying
172       context, given a context ctx.  The set of parameters given with params
173       determine exactly what parameters are passed down.  Note that a
174       parameter that is unknown in the underlying context is simply ignored.
175       Also, what happens when a needed parameter isn't passed down is defined
176       by the implementation.
177
178       EVP_RAND_gettable_params() returns an OSSL_PARAM array that describes
179       the retrievable and settable parameters.  EVP_RAND_gettable_params()
180       returns parameters that can be used with EVP_RAND_get_params().  See
181       OSSL_PARAM(3) for the use of OSSL_PARAM as a parameter descriptor.
182
183       EVP_RAND_gettable_ctx_params() and EVP_RAND_CTX_gettable_params()
184       return constant OSSL_PARAM arrays that describe the retrievable
185       parameters that can be used with EVP_RAND_CTX_get_params().
186       EVP_RAND_gettable_ctx_params() returns the parameters that can be
187       retrieved from the algorithm, whereas EVP_RAND_CTX_gettable_params()
188       returns the parameters that can be retrieved in the context's current
189       state.  See OSSL_PARAM(3) for the use of OSSL_PARAM as a parameter
190       descriptor.
191
192       EVP_RAND_settable_ctx_params() and EVP_RAND_CTX_settable_params()
193       return constant OSSL_PARAM arrays that describe the settable parameters
194       that can be used with EVP_RAND_CTX_set_params().
195       EVP_RAND_settable_ctx_params() returns the parameters that can be
196       retrieved from the algorithm, whereas EVP_RAND_CTX_settable_params()
197       returns the parameters that can be retrieved in the context's current
198       state.  See OSSL_PARAM(3) for the use of OSSL_PARAM as a parameter
199       descriptor.
200
201   Information functions
202       EVP_RAND_get_strength() returns the security strength of the RAND ctx.
203
204       EVP_RAND_get_state() returns the current state of the RAND ctx.  States
205       defined by the OpenSSL RNGs are:
206
207       •   EVP_RAND_STATE_UNINITIALISED: this RNG is currently uninitialised.
208           The instantiate call will change this to the ready state.
209
210       •   EVP_RAND_STATE_READY: this RNG is currently ready to generate
211           output.
212
213       •   EVP_RAND_STATE_ERROR: this RNG is in an error state.
214
215       EVP_RAND_is_a() returns 1 if rand is an implementation of an algorithm
216       that's identifiable with name, otherwise 0.
217
218       EVP_RAND_get0_provider() returns the provider that holds the
219       implementation of the given rand.
220
221       EVP_RAND_do_all_provided() traverses all RAND implemented by all
222       activated providers in the given library context libctx, and for each
223       of the implementations, calls the given function fn with the
224       implementation method and the given arg as argument.
225
226       EVP_RAND_get0_name() returns the canonical name of rand.
227
228       EVP_RAND_names_do_all() traverses all names for rand, and calls fn with
229       each name and data.
230
231       EVP_RAND_get0_description() returns a description of the rand, meant
232       for display and human consumption.  The description is at the
233       discretion of the rand implementation.
234
235       EVP_RAND_verify_zeroization() confirms if the internal DRBG state is
236       currently zeroed.  This is used by the FIPS provider to support the
237       mandatory self tests.
238

PARAMETERS

240       The standard parameter names are:
241
242       "state" (OSSL_RAND_PARAM_STATE) <integer>
243           Returns the state of the random number generator.
244
245       "strength" (OSSL_RAND_PARAM_STRENGTH) <unsigned integer>
246           Returns the bit strength of the random number generator.
247
248       For rands that are also deterministic random bit generators (DRBGs),
249       these additional parameters are recognised. Not all parameters are
250       relevant to, or are understood by all DRBG rands:
251
252       "reseed_requests" (OSSL_DRBG_PARAM_RESEED_REQUESTS) <unsigned integer>
253           Reads or set the number of generate requests before reseeding the
254           associated RAND ctx.
255
256       "reseed_time_interval" (OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL) <integer>
257           Reads or set the number of elapsed seconds before reseeding the
258           associated RAND ctx.
259
260       "max_request" (OSSL_DRBG_PARAM_RESEED_REQUESTS) <unsigned integer>
261           Specifies the maximum number of bytes that can be generated in a
262           single call to OSSL_FUNC_rand_generate.
263
264       "min_entropylen" (OSSL_DRBG_PARAM_MIN_ENTROPYLEN) <unsigned integer>
265       "max_entropylen" (OSSL_DRBG_PARAM_MAX_ENTROPYLEN) <unsigned integer>
266           Specify the minimum and maximum number of bytes of random material
267           that can be used to seed the DRBG.
268
269       "min_noncelen" (OSSL_DRBG_PARAM_MIN_NONCELEN) <unsigned integer>
270       "max_noncelen" (OSSL_DRBG_PARAM_MAX_NONCELEN) <unsigned integer>
271           Specify the minimum and maximum number of bytes of nonce that can
272           be used to seed the DRBG.
273
274       "max_perslen" (OSSL_DRBG_PARAM_MAX_PERSLEN) <unsigned integer>
275       "max_adinlen" (OSSL_DRBG_PARAM_MAX_ADINLEN) <unsigned integer>
276           Specify the minimum and maximum number of bytes of personalisation
277           string that can be used with the DRBG.
278
279       "reseed_counter" (OSSL_DRBG_PARAM_RESEED_COUNTER) <unsigned integer>
280           Specifies the number of times the DRBG has been seeded or reseeded.
281
282       "properties" (OSSL_RAND_PARAM_PROPERTIES) <UTF8 string>
283       "mac" (OSSL_RAND_PARAM_MAC) <UTF8 string>
284       "digest" (OSSL_RAND_PARAM_DIGEST) <UTF8 string>
285       "cipher" (OSSL_RAND_PARAM_CIPHER) <UTF8 string>
286           For RAND implementations that use an underlying computation MAC,
287           digest or cipher, these parameters set what the algorithm should
288           be.
289
290           The value is always the name of the intended algorithm, or the
291           properties in the case of OSSL_RAND_PARAM_PROPERTIES.
292

NOTES

294       An EVP_RAND_CTX needs to have locking enabled if it acts as the parent
295       of more than one child and the children can be accessed concurrently.
296       This must be done by explicitly calling EVP_RAND_enable_locking().
297
298       The RAND life-cycle is described in life_cycle-rand(7).  In the future,
299       the transitions described there will be enforced.  When this is done,
300       it will not be considered a breaking change to the API.
301

RETURN VALUES

303       EVP_RAND_fetch() returns a pointer to a newly fetched EVP_RAND, or NULL
304       if allocation failed.
305
306       EVP_RAND_get0_provider() returns a pointer to the provider for the
307       RAND, or NULL on error.
308
309       EVP_RAND_CTX_get0_rand() returns a pointer to the EVP_RAND associated
310       with the context.
311
312       EVP_RAND_get0_name() returns the name of the random number generation
313       algorithm.
314
315       EVP_RAND_up_ref() returns 1 on success, 0 on error.
316
317       EVP_RAND_names_do_all() returns 1 if the callback was called for all
318       names. A return value of 0 means that the callback was not called for
319       any names.
320
321       EVP_RAND_CTX_new() returns either the newly allocated EVP_RAND_CTX
322       structure or NULL if an error occurred.
323
324       EVP_RAND_CTX_free() does not return a value.
325
326       EVP_RAND_nonce() returns the length of the nonce.
327
328       EVP_RAND_get_strength() returns the strength of the random number
329       generator in bits.
330
331       EVP_RAND_gettable_params(), EVP_RAND_gettable_ctx_params() and
332       EVP_RAND_settable_ctx_params() return an array of OSSL_PARAMs.
333
334       EVP_RAND_verify_zeroization() returns 1 if the internal DRBG state is
335       currently zeroed, and 0 if not.
336
337       The remaining functions return 1 for success and 0 or a negative value
338       for failure.
339

SEE ALSO

341       RAND_bytes(3), EVP_RAND-CTR-DRBG(7), EVP_RAND-HASH-DRBG(7),
342       EVP_RAND-HMAC-DRBG(7), EVP_RAND-TEST-RAND(7), provider-rand(7),
343       life_cycle-rand(7)
344

HISTORY

346       This functionality was added to OpenSSL 3.0.
347
349       Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
350
351       Licensed under the Apache License 2.0 (the "License").  You may not use
352       this file except in compliance with the License.  You can obtain a copy
353       in the file LICENSE in the source distribution or at
354       <https://www.openssl.org/source/license.html>.
355
356
357
3583.0.5                             2022-07-05                   EVP_RAND(3ossl)
Impressum