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 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 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 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 Information functions
202 EVP_RAND_get_strength() returns the security strength of the RAND ctx.
203 EVP_RAND_get_state() returns the current state of the RAND ctx. States
205 defined by the OpenSSL RNGs are:
206 • EVP_RAND_STATE_UNINITIALISED: this RNG is currently uninitialised.
208 The instantiate call will change this to the ready state.
209 • EVP_RAND_STATE_READY: this RNG is currently ready to generate
211 output.
212 • EVP_RAND_STATE_ERROR: this RNG is in an error state.
214 EVP_RAND_is_a() returns 1 if rand is an implementation of an algorithm
216 that's identifiable with name, otherwise 0.
217 EVP_RAND_get0_provider() returns the provider that holds the
219 implementation of the given rand.
220 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 EVP_RAND_get0_name() returns the canonical name of rand.
227 EVP_RAND_names_do_all() traverses all names for rand, and calls fn with
229 each name and data.
230 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 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
240 The standard parameter names are:
241 "state" (OSSL_RAND_PARAM_STATE) <integer>
243 Returns the state of the random number generator.
244 "strength" (OSSL_RAND_PARAM_STRENGTH) <unsigned integer>
246 Returns the bit strength of the random number generator.
247 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 "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 "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 "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 "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 "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 "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 "reseed_counter" (OSSL_DRBG_PARAM_RESEED_COUNTER) <unsigned integer>
280 Specifies the number of times the DRBG has been seeded or reseeded.
281 "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 The value is always the name of the intended algorithm, or the
291 properties in the case of OSSL_RAND_PARAM_PROPERTIES.
292
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 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
303 EVP_RAND_fetch() returns a pointer to a newly fetched EVP_RAND, or NULL
304 if allocation failed.
305 EVP_RAND_get0_provider() returns a pointer to the provider for the
307 RAND, or NULL on error.
308 EVP_RAND_CTX_get0_rand() returns a pointer to the EVP_RAND associated
310 with the context.
311 EVP_RAND_get0_name() returns the name of the random number generation
313 algorithm.
314 EVP_RAND_up_ref() returns 1 on success, 0 on error.
316 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 EVP_RAND_CTX_new() returns either the newly allocated EVP_RAND_CTX
322 structure or NULL if an error occurred.
323 EVP_RAND_CTX_free() does not return a value.
325 EVP_RAND_nonce() returns the length of the nonce.
327 EVP_RAND_get_strength() returns the strength of the random number
329 generator in bits.
330 EVP_RAND_gettable_params(), EVP_RAND_gettable_ctx_params() and
332 EVP_RAND_settable_ctx_params() return an array of OSSL_PARAMs.
333 EVP_RAND_verify_zeroization() returns 1 if the internal DRBG state is
335 currently zeroed, and 0 if not.
336 The remaining functions return 1 for success and 0 or a negative value
338 for failure.
339
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
346 This functionality was added to OpenSSL 3.0.
347
349 Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
350 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>.
3553.0.5 2022-07-05 EVP_RAND(3ossl)