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_CTX_up_ref,
8 EVP_RAND_instantiate, EVP_RAND_uninstantiate, EVP_RAND_generate,
9 EVP_RAND_reseed, EVP_RAND_nonce, EVP_RAND_enable_locking,
10 EVP_RAND_verify_zeroization, EVP_RAND_get_strength, EVP_RAND_get_state,
11 EVP_RAND_get0_provider, EVP_RAND_CTX_get0_rand, EVP_RAND_is_a,
12 EVP_RAND_get0_name, 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 int EVP_RAND_CTX_up_ref(EVP_RAND_CTX *ctx);
33 EVP_RAND *EVP_RAND_CTX_get0_rand(EVP_RAND_CTX *ctx);
34 int EVP_RAND_get_params(EVP_RAND *rand, OSSL_PARAM params[]);
35 int EVP_RAND_CTX_get_params(EVP_RAND_CTX *ctx, OSSL_PARAM params[]);
36 int EVP_RAND_CTX_set_params(EVP_RAND_CTX *ctx, const OSSL_PARAM params[]);
37 const OSSL_PARAM *EVP_RAND_gettable_params(const EVP_RAND *rand);
38 const OSSL_PARAM *EVP_RAND_gettable_ctx_params(const EVP_RAND *rand);
39 const OSSL_PARAM *EVP_RAND_settable_ctx_params(const EVP_RAND *rand);
40 const OSSL_PARAM *EVP_RAND_CTX_gettable_params(EVP_RAND_CTX *ctx);
41 const OSSL_PARAM *EVP_RAND_CTX_settable_params(EVP_RAND_CTX *ctx);
42 const char *EVP_RAND_get0_name(const EVP_RAND *rand);
43 const char *EVP_RAND_get0_description(const EVP_RAND *rand);
44 int EVP_RAND_is_a(const EVP_RAND *rand, const char *name);
45 const OSSL_PROVIDER *EVP_RAND_get0_provider(const EVP_RAND *rand);
46 void EVP_RAND_do_all_provided(OSSL_LIB_CTX *libctx,
47 void (*fn)(EVP_RAND *rand, void *arg),
48 void *arg);
49 int EVP_RAND_names_do_all(const EVP_RAND *rand,
50 void (*fn)(const char *name, void *data),
51 void *data);
52 int EVP_RAND_instantiate(EVP_RAND_CTX *ctx, unsigned int strength,
54 int prediction_resistance,
55 const unsigned char *pstr, size_t pstr_len,
56 const OSSL_PARAM params[]);
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);
66 int EVP_RAND_verify_zeroization(EVP_RAND_CTX *ctx);
67 unsigned int EVP_RAND_get_strength(EVP_RAND_CTX *ctx);
68 int EVP_RAND_get_state(EVP_RAND_CTX *ctx);
69 #define EVP_RAND_STATE_UNINITIALISED 0
71 #define EVP_RAND_STATE_READY 1
72 #define EVP_RAND_STATE_ERROR 2
73
75 The EVP RAND routines are a high-level interface to random number
76 generators both deterministic and not. If you just want to generate
77 random bytes then you don't need to use these functions: just call
78 RAND_bytes() or RAND_priv_bytes(). If you want to do more, these calls
79 should be used instead of the older RAND and RAND_DRBG functions.
80 After creating a EVP_RAND_CTX for the required algorithm using
82 EVP_RAND_CTX_new(), inputs to the algorithm are supplied either by
83 passing them as part of the EVP_RAND_instantiate() call or using calls
84 to EVP_RAND_CTX_set_params() before calling EVP_RAND_instantiate().
85 Finally, call EVP_RAND_generate() to produce cryptographically secure
86 random bytes.
87 Types
89 EVP_RAND is a type that holds the implementation of a RAND.
90 EVP_RAND_CTX is a context type that holds the algorithm inputs.
92 EVP_RAND_CTX structures are reference counted.
93 Algorithm implementation fetching
95 EVP_RAND_fetch() fetches an implementation of a RAND algorithm, given a
96 library context libctx and a set of properties. See "ALGORITHM
97 FETCHING" in crypto(7) for further information.
98 The returned value must eventually be freed with EVP_RAND_free(3).
100 EVP_RAND_up_ref() increments the reference count of an already fetched
102 RAND.
103 EVP_RAND_free() frees a fetched algorithm. NULL is a valid parameter,
105 for which this function is a no-op.
106 Context manipulation functions
108 EVP_RAND_CTX_new() creates a new context for the RAND implementation
109 rand. If not NULL, parent specifies the seed source for this
110 implementation. Not all random number generators need to have a seed
111 source specified. If a parent is required, a NULL parent will utilise
112 the operating system entropy sources. It is recommended to minimise
113 the number of random number generators that rely on the operating
114 system for their randomness because this is often scarce.
115 EVP_RAND_CTX_free() frees up the context ctx. If ctx is NULL, nothing
117 is done.
118 EVP_RAND_CTX_get0_rand() returns the EVP_RAND associated with the
120 context ctx.
121 Random Number Generator Functions
123 EVP_RAND_instantiate() processes any parameters in params and then
124 instantiates the RAND ctx with a minimum security strength of
125 <strength> and personalisation string pstr of length <pstr_len>. If
126 prediction_resistance is specified, fresh entropy from a live source
127 will be sought. This call operates as per NIST SP 800-90A and SP
128 800-90C.
129 EVP_RAND_uninstantiate() uninstantiates the RAND ctx as per NIST SP
131 800-90A and SP 800-90C. Subsequent to this call, the RAND cannot be
132 used to generate bytes. It can only be freed or instantiated again.
133 EVP_RAND_generate() produces random bytes from the RAND ctx with the
135 additional input addin of length addin_len. The bytes produced will
136 meet the security strength. If prediction_resistance is specified,
137 fresh entropy from a live source will be sought. This call operates as
138 per NIST SP 800-90A and SP 800-90C.
139 EVP_RAND_reseed() reseeds the RAND with new entropy. Entropy ent of
141 length ent_len bytes can be supplied as can additional input addin of
142 length addin_len bytes. In the FIPS provider, both are treated as
143 additional input as per NIST SP-800-90Ar1, Sections 9.1 and 9.2.
144 Additional seed material is also drawn from the RAND's parent or the
145 operating system. If prediction_resistance is specified, fresh entropy
146 from a live source will be sought. This call operates as per NIST SP
147 800-90A and SP 800-90C.
148 EVP_RAND_nonce() creates a nonce in out of maximum length outlen bytes
150 from the RAND ctx. The function returns the length of the generated
151 nonce. If out is NULL, the length is still returned but no generation
152 takes place. This allows a caller to dynamically allocate a buffer of
153 the appropriate size.
154 EVP_RAND_enable_locking() enables locking for the RAND ctx and all of
156 its parents. After this ctx will operate in a thread safe manner,
157 albeit more slowly. This function is not itself thread safe if called
158 with the same ctx from multiple threads. Typically locking should be
159 enabled before a ctx is shared across multiple threads.
160 EVP_RAND_get_params() retrieves details about the implementation rand.
162 The set of parameters given with params determine exactly what
163 parameters should be retrieved. Note that a parameter that is unknown
164 in the underlying context is simply ignored.
165 EVP_RAND_CTX_get_params() retrieves chosen parameters, given the
167 context ctx and its underlying context. The set of parameters given
168 with params determine exactly what parameters should be retrieved.
169 Note that a parameter that is unknown in the underlying context is
170 simply ignored.
171 EVP_RAND_CTX_set_params() passes chosen parameters to the underlying
173 context, given a context ctx. The set of parameters given with params
174 determine exactly what parameters are passed down. Note that a
175 parameter that is unknown in the underlying context is simply ignored.
176 Also, what happens when a needed parameter isn't passed down is defined
177 by the implementation.
178 EVP_RAND_gettable_params() returns an OSSL_PARAM(3) array that
180 describes the retrievable and settable parameters.
181 EVP_RAND_gettable_params() returns parameters that can be used with
182 EVP_RAND_get_params().
183 EVP_RAND_gettable_ctx_params() and EVP_RAND_CTX_gettable_params()
185 return constant OSSL_PARAM(3) arrays that describe the retrievable
186 parameters that can be used with EVP_RAND_CTX_get_params().
187 EVP_RAND_gettable_ctx_params() returns the parameters that can be
188 retrieved from the algorithm, whereas EVP_RAND_CTX_gettable_params()
189 returns the parameters that can be retrieved in the context's current
190 state.
191 EVP_RAND_settable_ctx_params() and EVP_RAND_CTX_settable_params()
193 return constant OSSL_PARAM(3) arrays that describe the settable
194 parameters 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.
199 Information functions
201 EVP_RAND_get_strength() returns the security strength of the RAND ctx.
202 EVP_RAND_get_state() returns the current state of the RAND ctx. States
204 defined by the OpenSSL RNGs are:
205 • EVP_RAND_STATE_UNINITIALISED: this RNG is currently uninitialised.
207 The instantiate call will change this to the ready state.
208 • EVP_RAND_STATE_READY: this RNG is currently ready to generate
210 output.
211 • EVP_RAND_STATE_ERROR: this RNG is in an error state.
213 EVP_RAND_is_a() returns 1 if rand is an implementation of an algorithm
215 that's identifiable with name, otherwise 0.
216 EVP_RAND_get0_provider() returns the provider that holds the
218 implementation of the given rand.
219 EVP_RAND_do_all_provided() traverses all RAND implemented by all
221 activated providers in the given library context libctx, and for each
222 of the implementations, calls the given function fn with the
223 implementation method and the given arg as argument.
224 EVP_RAND_get0_name() returns the canonical name of rand.
226 EVP_RAND_names_do_all() traverses all names for rand, and calls fn with
228 each name and data.
229 EVP_RAND_get0_description() returns a description of the rand, meant
231 for display and human consumption. The description is at the
232 discretion of the rand implementation.
233 EVP_RAND_verify_zeroization() confirms if the internal DRBG state is
235 currently zeroed. This is used by the FIPS provider to support the
236 mandatory self tests.
237
239 The standard parameter names are:
240 "state" (OSSL_RAND_PARAM_STATE) <integer>
242 Returns the state of the random number generator.
243 "strength" (OSSL_RAND_PARAM_STRENGTH) <unsigned integer>
245 Returns the bit strength of the random number generator.
246 For rands that are also deterministic random bit generators (DRBGs),
248 these additional parameters are recognised. Not all parameters are
249 relevant to, or are understood by all DRBG rands:
250 "reseed_requests" (OSSL_DRBG_PARAM_RESEED_REQUESTS) <unsigned integer>
252 Reads or set the number of generate requests before reseeding the
253 associated RAND ctx.
254 "reseed_time_interval" (OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL) <integer>
256 Reads or set the number of elapsed seconds before reseeding the
257 associated RAND ctx.
258 "max_request" (OSSL_DRBG_PARAM_RESEED_REQUESTS) <unsigned integer>
260 Specifies the maximum number of bytes that can be generated in a
261 single call to OSSL_FUNC_rand_generate.
262 "min_entropylen" (OSSL_DRBG_PARAM_MIN_ENTROPYLEN) <unsigned integer>
264 "max_entropylen" (OSSL_DRBG_PARAM_MAX_ENTROPYLEN) <unsigned integer>
265 Specify the minimum and maximum number of bytes of random material
266 that can be used to seed the DRBG.
267 "min_noncelen" (OSSL_DRBG_PARAM_MIN_NONCELEN) <unsigned integer>
269 "max_noncelen" (OSSL_DRBG_PARAM_MAX_NONCELEN) <unsigned integer>
270 Specify the minimum and maximum number of bytes of nonce that can
271 be used to seed the DRBG.
272 "max_perslen" (OSSL_DRBG_PARAM_MAX_PERSLEN) <unsigned integer>
274 "max_adinlen" (OSSL_DRBG_PARAM_MAX_ADINLEN) <unsigned integer>
275 Specify the minimum and maximum number of bytes of personalisation
276 string that can be used with the DRBG.
277 "reseed_counter" (OSSL_DRBG_PARAM_RESEED_COUNTER) <unsigned integer>
279 Specifies the number of times the DRBG has been seeded or reseeded.
280 "properties" (OSSL_RAND_PARAM_PROPERTIES) <UTF8 string>
282 "mac" (OSSL_RAND_PARAM_MAC) <UTF8 string>
283 "digest" (OSSL_RAND_PARAM_DIGEST) <UTF8 string>
284 "cipher" (OSSL_RAND_PARAM_CIPHER) <UTF8 string>
285 For RAND implementations that use an underlying computation MAC,
286 digest or cipher, these parameters set what the algorithm should
287 be.
288 The value is always the name of the intended algorithm, or the
290 properties in the case of OSSL_RAND_PARAM_PROPERTIES.
291
293 The use of a nonzero value for the prediction_resistance argument to
294 EVP_RAND_instantiate(), EVP_RAND_generate() or EVP_RAND_reseed() should
295 be used sparingly. In the default setup, this will cause all public
296 and private DRBGs to be reseeded on next use. Since, by default,
297 public and private DRBGs are allocated on a per thread basis, this can
298 result in significant overhead for highly multi-threaded applications.
299 For normal use-cases, the default "reseed_requests" and
300 "reseed_time_interval" thresholds ensure sufficient prediction
301 resistance over time and you can reduce those values if you think they
302 are too high. Explicitly requesting prediction resistance is intended
303 for more special use-cases like generating long-term secrets.
304 An EVP_RAND_CTX needs to have locking enabled if it acts as the parent
306 of more than one child and the children can be accessed concurrently.
307 This must be done by explicitly calling EVP_RAND_enable_locking().
308 The RAND life-cycle is described in life_cycle-rand(7). In the future,
310 the transitions described there will be enforced. When this is done,
311 it will not be considered a breaking change to the API.
312
314 EVP_RAND_fetch() returns a pointer to a newly fetched EVP_RAND, or NULL
315 if allocation failed.
316 EVP_RAND_get0_provider() returns a pointer to the provider for the
318 RAND, or NULL on error.
319 EVP_RAND_CTX_get0_rand() returns a pointer to the EVP_RAND associated
321 with the context.
322 EVP_RAND_get0_name() returns the name of the random number generation
324 algorithm.
325 EVP_RAND_up_ref() returns 1 on success, 0 on error.
327 EVP_RAND_names_do_all() returns 1 if the callback was called for all
329 names. A return value of 0 means that the callback was not called for
330 any names.
331 EVP_RAND_CTX_new() returns either the newly allocated EVP_RAND_CTX
333 structure or NULL if an error occurred.
334 EVP_RAND_CTX_free() does not return a value.
336 EVP_RAND_CTX_up_ref() returns 1 on success, 0 on error.
338 EVP_RAND_nonce() returns the length of the nonce.
340 EVP_RAND_get_strength() returns the strength of the random number
342 generator in bits.
343 EVP_RAND_gettable_params(), EVP_RAND_gettable_ctx_params() and
345 EVP_RAND_settable_ctx_params() return an array of OSSL_PARAMs.
346 EVP_RAND_verify_zeroization() returns 1 if the internal DRBG state is
348 currently zeroed, and 0 if not.
349 The remaining functions return 1 for success and 0 or a negative value
351 for failure.
352
354 RAND_bytes(3), EVP_RAND-CTR-DRBG(7), EVP_RAND-HASH-DRBG(7),
355 EVP_RAND-HMAC-DRBG(7), EVP_RAND-TEST-RAND(7), provider-rand(7),
356 life_cycle-rand(7)
357
359 This functionality was added to OpenSSL 3.0.
360
362 Copyright 2020-2023 The OpenSSL Project Authors. All Rights Reserved.
363 Licensed under the Apache License 2.0 (the "License"). You may not use
365 this file except in compliance with the License. You can obtain a copy
366 in the file LICENSE in the source distribution or at
367 <https://www.openssl.org/source/license.html>.
3683.1.1 2023-08-31 EVP_RAND(3ossl)