1EVP_RAND(3ossl) OpenSSL EVP_RAND(3ossl)
2
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
21 #include <openssl/evp.h>
22 typedef struct evp_rand_st EVP_RAND;
24 typedef struct evp_rand_ctx_st EVP_RAND_CTX;
25 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 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 #define EVP_RAND_STATE_UNINITIALISED 0
70 #define EVP_RAND_STATE_READY 1
71 #define EVP_RAND_STATE_ERROR 2
72
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 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 Types
88 EVP_RAND is a type that holds the implementation of a RAND.
89 EVP_RAND_CTX is a context type that holds the algorithm inputs.
91 EVP_RAND_CTX structures are reference counted.
92 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 The returned value must eventually be freed with EVP_RAND_free(3).
99 EVP_RAND_up_ref() increments the reference count of an already fetched
101 RAND.
102 EVP_RAND_free() frees a fetched algorithm. NULL is a valid parameter,
104 for which this function is a no-op.
105 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 EVP_RAND_CTX_free() frees up the context ctx. If ctx is NULL, nothing
116 is done.
117 EVP_RAND_CTX_get0_rand() returns the EVP_RAND associated with the
119 context ctx.
120 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 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 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 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 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 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 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 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 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 EVP_RAND_gettable_params() returns an OSSL_PARAM(3) array that
179 describes the retrievable and settable parameters.
180 EVP_RAND_gettable_params() returns parameters that can be used with
181 EVP_RAND_get_params().
182 EVP_RAND_gettable_ctx_params() and EVP_RAND_CTX_gettable_params()
184 return constant OSSL_PARAM(3) 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.
190 EVP_RAND_settable_ctx_params() and EVP_RAND_CTX_settable_params()
192 return constant OSSL_PARAM(3) arrays that describe the settable
193 parameters that can be used with EVP_RAND_CTX_set_params().
194 EVP_RAND_settable_ctx_params() returns the parameters that can be
195 retrieved from the algorithm, whereas EVP_RAND_CTX_settable_params()
196 returns the parameters that can be retrieved in the context's current
197 state.
198 Information functions
200 EVP_RAND_get_strength() returns the security strength of the RAND ctx.
201 EVP_RAND_get_state() returns the current state of the RAND ctx. States
203 defined by the OpenSSL RNGs are:
204 • EVP_RAND_STATE_UNINITIALISED: this RNG is currently uninitialised.
206 The instantiate call will change this to the ready state.
207 • EVP_RAND_STATE_READY: this RNG is currently ready to generate
209 output.
210 • EVP_RAND_STATE_ERROR: this RNG is in an error state.
212 EVP_RAND_is_a() returns 1 if rand is an implementation of an algorithm
214 that's identifiable with name, otherwise 0.
215 EVP_RAND_get0_provider() returns the provider that holds the
217 implementation of the given rand.
218 EVP_RAND_do_all_provided() traverses all RAND implemented by all
220 activated providers in the given library context libctx, and for each
221 of the implementations, calls the given function fn with the
222 implementation method and the given arg as argument.
223 EVP_RAND_get0_name() returns the canonical name of rand.
225 EVP_RAND_names_do_all() traverses all names for rand, and calls fn with
227 each name and data.
228 EVP_RAND_get0_description() returns a description of the rand, meant
230 for display and human consumption. The description is at the
231 discretion of the rand implementation.
232 EVP_RAND_verify_zeroization() confirms if the internal DRBG state is
234 currently zeroed. This is used by the FIPS provider to support the
235 mandatory self tests.
236
238 The standard parameter names are:
239 "state" (OSSL_RAND_PARAM_STATE) <integer>
241 Returns the state of the random number generator.
242 "strength" (OSSL_RAND_PARAM_STRENGTH) <unsigned integer>
244 Returns the bit strength of the random number generator.
245 For rands that are also deterministic random bit generators (DRBGs),
247 these additional parameters are recognised. Not all parameters are
248 relevant to, or are understood by all DRBG rands:
249 "reseed_requests" (OSSL_DRBG_PARAM_RESEED_REQUESTS) <unsigned integer>
251 Reads or set the number of generate requests before reseeding the
252 associated RAND ctx.
253 "reseed_time_interval" (OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL) <integer>
255 Reads or set the number of elapsed seconds before reseeding the
256 associated RAND ctx.
257 "max_request" (OSSL_DRBG_PARAM_RESEED_REQUESTS) <unsigned integer>
259 Specifies the maximum number of bytes that can be generated in a
260 single call to OSSL_FUNC_rand_generate.
261 "min_entropylen" (OSSL_DRBG_PARAM_MIN_ENTROPYLEN) <unsigned integer>
263 "max_entropylen" (OSSL_DRBG_PARAM_MAX_ENTROPYLEN) <unsigned integer>
264 Specify the minimum and maximum number of bytes of random material
265 that can be used to seed the DRBG.
266 "min_noncelen" (OSSL_DRBG_PARAM_MIN_NONCELEN) <unsigned integer>
268 "max_noncelen" (OSSL_DRBG_PARAM_MAX_NONCELEN) <unsigned integer>
269 Specify the minimum and maximum number of bytes of nonce that can
270 be used to seed the DRBG.
271 "max_perslen" (OSSL_DRBG_PARAM_MAX_PERSLEN) <unsigned integer>
273 "max_adinlen" (OSSL_DRBG_PARAM_MAX_ADINLEN) <unsigned integer>
274 Specify the minimum and maximum number of bytes of personalisation
275 string that can be used with the DRBG.
276 "reseed_counter" (OSSL_DRBG_PARAM_RESEED_COUNTER) <unsigned integer>
278 Specifies the number of times the DRBG has been seeded or reseeded.
279 "properties" (OSSL_RAND_PARAM_PROPERTIES) <UTF8 string>
281 "mac" (OSSL_RAND_PARAM_MAC) <UTF8 string>
282 "digest" (OSSL_RAND_PARAM_DIGEST) <UTF8 string>
283 "cipher" (OSSL_RAND_PARAM_CIPHER) <UTF8 string>
284 For RAND implementations that use an underlying computation MAC,
285 digest or cipher, these parameters set what the algorithm should
286 be.
287 The value is always the name of the intended algorithm, or the
289 properties in the case of OSSL_RAND_PARAM_PROPERTIES.
290
292 The use of a nonzero value for the prediction_resistance argument to
293 EVP_RAND_instantiate(), EVP_RAND_generate() or EVP_RAND_reseed() should
294 be used sparingly. In the default setup, this will cause all public
295 and private DRBGs to be reseeded on next use. Since, by default,
296 public and private DRBGs are allocated on a per thread basis, this can
297 result in significant overhead for highly multi-threaded applications.
298 For normal use-cases, the default "reseed_requests" and
299 "reseed_time_interval" thresholds ensure sufficient prediction
300 resistance over time and you can reduce those values if you think they
301 are too high. Explicitly requesting prediction resistance is intended
302 for more special use-cases like generating long-term secrets.
303 An EVP_RAND_CTX needs to have locking enabled if it acts as the parent
305 of more than one child and the children can be accessed concurrently.
306 This must be done by explicitly calling EVP_RAND_enable_locking().
307 The RAND life-cycle is described in life_cycle-rand(7). In the future,
309 the transitions described there will be enforced. When this is done,
310 it will not be considered a breaking change to the API.
311
313 EVP_RAND_fetch() returns a pointer to a newly fetched EVP_RAND, or NULL
314 if allocation failed.
315 EVP_RAND_get0_provider() returns a pointer to the provider for the
317 RAND, or NULL on error.
318 EVP_RAND_CTX_get0_rand() returns a pointer to the EVP_RAND associated
320 with the context.
321 EVP_RAND_get0_name() returns the name of the random number generation
323 algorithm.
324 EVP_RAND_up_ref() returns 1 on success, 0 on error.
326 EVP_RAND_names_do_all() returns 1 if the callback was called for all
328 names. A return value of 0 means that the callback was not called for
329 any names.
330 EVP_RAND_CTX_new() returns either the newly allocated EVP_RAND_CTX
332 structure or NULL if an error occurred.
333 EVP_RAND_CTX_free() does not return a value.
335 EVP_RAND_nonce() returns the length of the nonce.
337 EVP_RAND_get_strength() returns the strength of the random number
339 generator in bits.
340 EVP_RAND_gettable_params(), EVP_RAND_gettable_ctx_params() and
342 EVP_RAND_settable_ctx_params() return an array of OSSL_PARAMs.
343 EVP_RAND_verify_zeroization() returns 1 if the internal DRBG state is
345 currently zeroed, and 0 if not.
346 The remaining functions return 1 for success and 0 or a negative value
348 for failure.
349
351 RAND_bytes(3), EVP_RAND-CTR-DRBG(7), EVP_RAND-HASH-DRBG(7),
352 EVP_RAND-HMAC-DRBG(7), EVP_RAND-TEST-RAND(7), provider-rand(7),
353 life_cycle-rand(7)
354
356 This functionality was added to OpenSSL 3.0.
357
359 Copyright 2020-2023 The OpenSSL Project Authors. All Rights Reserved.
360 Licensed under the Apache License 2.0 (the "License"). You may not use
362 this file except in compliance with the License. You can obtain a copy
363 in the file LICENSE in the source distribution or at
364 <https://www.openssl.org/source/license.html>.
3653.0.9 2023-07-27 EVP_RAND(3ossl)