5 EVP_RAND, EVP_RAND_fetch, EVP_RAND_free, EVP_RAND_up_ref, EVP_RAND_CTX,
6 EVP_RAND_CTX_new, EVP_RAND_CTX_free, EVP_RAND_instantiate,
7 EVP_RAND_uninstantiate, EVP_RAND_generate, EVP_RAND_reseed,
8 EVP_RAND_nonce, EVP_RAND_enable_locking, EVP_RAND_set_callbacks,
9 EVP_RAND_verify_zeroization, EVP_RAND_strength, EVP_RAND_state,
10 EVP_RAND_provider, EVP_RAND_CTX_rand, EVP_RAND_is_a, EVP_RAND_number,
11 EVP_RAND_name, EVP_RAND_names_do_all, EVP_RAND_get_ctx_params,
12 EVP_RAND_set_ctx_params, EVP_RAND_do_all_provided, EVP_RAND_get_params,
13 EVP_RAND_gettable_ctx_params, EVP_RAND_settable_ctx_params,
14 EVP_RAND_gettable_params, EVP_RAND_STATE_UNINITIALISED, EVP_RAND_STATE_READY,
15 EVP_RAND_STATE_ERROR - EVP RAND routines
19 #include <openssl/evp.h>
21 typedef struct evp_rand_st EVP_RAND;
22 typedef struct evp_rand_ctx_st EVP_RAND_CTX;
24 EVP_RAND *EVP_RAND_fetch(OPENSSL_CTX *libctx, const char *algorithm,
25 const char *properties);
26 int EVP_RAND_up_ref(EVP_RAND *rand);
27 void EVP_RAND_free(EVP_RAND *rand);
28 EVP_RAND_CTX *EVP_RAND_CTX_new(EVP_RAND *rand, EVP_RAND_CTX *parent);
29 void EVP_RAND_CTX_free(EVP_RAND_CTX *ctx);
30 EVP_RAND *EVP_RAND_CTX_rand(EVP_RAND_CTX *ctx);
31 int EVP_RAND_get_params(EVP_RAND *rand, OSSL_PARAM params[]);
32 int EVP_RAND_get_ctx_params(EVP_RAND_CTX *ctx, OSSL_PARAM params[]);
33 int EVP_RAND_set_ctx_params(EVP_RAND_CTX *ctx, const OSSL_PARAM params[]);
34 const OSSL_PARAM *EVP_RAND_gettable_params(const EVP_RAND *rand);
35 const OSSL_PARAM *EVP_RAND_gettable_ctx_params(const EVP_RAND *rand);
36 const OSSL_PARAM *EVP_RAND_settable_ctx_params(const EVP_RAND *rand);
37 int EVP_RAND_number(const EVP_RAND *rand);
38 const char *EVP_RAND_name(const EVP_RAND *rand);
39 int EVP_RAND_is_a(const EVP_RAND *rand, const char *name);
40 const OSSL_PROVIDER *EVP_RAND_provider(const EVP_RAND *rand);
41 void EVP_RAND_do_all_provided(OPENSSL_CTX *libctx,
42 void (*fn)(EVP_RAND *rand, void *arg),
44 void EVP_RAND_names_do_all(const EVP_RAND *rand,
45 void (*fn)(const char *name, void *data),
48 int EVP_RAND_instantiate(EVP_RAND_CTX *ctx, unsigned int strength,
49 int prediction_resistance,
50 const unsigned char *pstr, size_t pstr_len);
51 int EVP_RAND_uninstantiate(EVP_RAND_CTX *ctx);
52 int EVP_RAND_generate(EVP_RAND_CTX *ctx, unsigned char *out, size_t outlen,
53 unsigned int strength, int prediction_resistance,
54 const unsigned char *addin, size_t addin_len);
55 int EVP_RAND_reseed(EVP_RAND_CTX *ctx, int prediction_resistance,
56 const unsigned char *ent, size_t ent_len,
57 const unsigned char *addin, size_t addin_len);
58 int EVP_RAND_nonce(EVP_RAND_CTX *ctx, unsigned char *out, size_t outlen);
59 int EVP_RAND_enable_locking(EVP_RAND_CTX *ctx);
60 int EVP_RAND_set_callbacks(EVP_RAND_CTX *ctx, OSSL_CALLBACK *get_entropy,
61 OSSL_CALLBACK *cleanup_entropy,
62 OSSL_CALLBACK *get_nonce,
63 OSSL_CALLBACK *cleanup_nonce, void *arg);
64 int EVP_RAND_verify_zeroization(EVP_RAND_CTX *ctx);
65 unsigned int EVP_RAND_strength(EVP_RAND_CTX *ctx);
66 int EVP_RAND_state(EVP_RAND_CTX *ctx);
68 #define EVP_RAND_STATE_UNINITIALISED 0
69 #define EVP_RAND_STATE_READY 1
70 #define EVP_RAND_STATE_ERROR 2
74 The EVP RAND routines are a high level interface to random number generators
75 both deterministic and not.
76 If you just want to generate random bytes then you don't need to use
77 these functions: just call RAND_bytes() or RAND_priv_bytes().
78 If you want to do more, these calls should be used instead of the older
79 RAND and RAND_DRBG functions.
81 After creating a B<EVP_RAND_CTX> for the required algorithm using
82 EVP_RAND_CTX_new(), inputs to the algorithm are supplied
83 using calls to EVP_RAND_set_ctx_params() before
84 calling EVP_RAND_instantiate() and then EVP_RAND_generate() to produce
85 cryptographically secure random bytes.
89 B<EVP_RAND> is a type that holds the implementation of a RAND.
91 B<EVP_RAND_CTX> is a context type that holds the algorithm inputs.
93 =head2 Algorithm implementation fetching
95 EVP_RAND_fetch() fetches an implementation of a RAND I<algorithm>, given
96 a library context I<libctx> and a set of I<properties>.
97 See L<provider(7)/Fetching algorithms> for further information.
99 The returned value must eventually be freed with
102 EVP_RAND_up_ref() increments the reference count of an already fetched
105 EVP_RAND_free() frees a fetched algorithm.
106 NULL is a valid parameter, for which this function is a no-op.
108 =head2 Context manipulation functions
110 EVP_RAND_CTX_new() creates a new context for the RAND implementation I<rand>.
111 If not NULL, I<parent> specifies the seed source for this implementation.
112 Not all random number generators need to have a seed source specified.
113 If a parent is required, a NULL I<parent> will utilise the operating
114 system entropy sources.
115 It is recommended to minimise the number of random number generators that
116 rely on the operating system for their randomness because this is often scarce.
118 EVP_RAND_CTX_free() frees up the context I<ctx>. If I<ctx> is NULL, nothing
121 EVP_RAND_CTX_rand() returns the B<EVP_RAND> associated with the context
124 =head2 Random Number Generator Functions
126 EVP_RAND_instantiate() instantiates the RAND I<ctx> with a minimum security
127 strength of <strength> and personalisation string I<pstr> of length <pstr_len>.
128 If I<prediction_resistance> is specified, fresh entropy from a live source
129 will be sought. This call operates as per NIST SP 800-90A and SP 800-90C.
131 EVP_RAND_uninstantiate() uninstantiates the RAND I<ctx> as per
132 NIST SP 800-90A and SP 800-90C. Subsequent to this call, the RAND cannot
133 be used to generate bytes. It can only be freed or instantiated again.
135 EVP_RAND_generate() produces random bytes from the RAND I<ctx> with the
136 additional input I<addin> of length I<addin_len>. The bytes
137 produced will meet the security I<strength>.
138 If I<prediction_resistance> is specified, fresh entropy from a live source
139 will be sought. This call operates as per NIST SP 800-90A and SP 800-90C.
141 EVP_RAND_reseed() reseeds the RAND with new entropy.
142 Entropy I<ent> of length I<ent_len> bytes can be supplied as can additional
143 input I<addin> of length I<addin_len> bytes. In the FIPS provider, both are
144 treated as additional input as per NIST SP-800-90Ar1, Sections 9.1 and 9.2.
145 Additional seed material is also drawn from the RAND's parent or the
146 operating system. If I<prediction_resistance> is specified, fresh entropy
147 from a live source will be sought. This call operates as per NIST SP 800-90A
150 EVP_RAND_nonce() creates a nonce in I<out> of maximum length I<outlen>
151 bytes from the RAND I<ctx>. The function returns the length of the generated
152 nonce. If I<out> is NULL, the length is still returned but no generation
153 takes place. This allows a caller to dynamically allocate a buffer of the
156 EVP_RAND_enable_locking() enables locking for the RAND I<ctx> and all of
157 its parents. After this I<ctx> will operate in a thread safe manner, albeit
160 EVP_RAND_set_callbacks() sets callbacks on the RAND I<ctx> to accept
161 external entropy and nonce input. The callback I<get_entropy> fills a buffer
162 with new randomness and the callback I<cleanup_entropy> clears and frees the
163 buffer. Likewise for I<get_nonce> and I<cleanup_nonce>. In all cases the
164 callbacks are passed I<arg> in addition to an OSSL_PARAM array.
166 EVP_RAND_get_params() retrieves details about the implementation
168 The set of parameters given with I<params> determine exactly what
169 parameters should be retrieved.
170 Note that a parameter that is unknown in the underlying context is
173 EVP_RAND_get_ctx_params() retrieves chosen parameters, given the
174 context I<ctx> and its underlying context.
175 The set of parameters given with I<params> determine exactly what
176 parameters should be retrieved.
177 Note that a parameter that is unknown in the underlying context is
180 EVP_RAND_set_ctx_params() passes chosen parameters to the underlying
181 context, given a context I<ctx>.
182 The set of parameters given with I<params> determine exactly what
183 parameters are passed down.
184 Note that a parameter that is unknown in the underlying context is
186 Also, what happens when a needed parameter isn't passed down is
187 defined by the implementation.
189 EVP_RAND_gettable_params(), EVP_RAND_gettable_ctx_params() and
190 EVP_RAND_settable_ctx_params() get a constant B<OSSL_PARAM> array that
191 describes the retrievable and settable parameters, i.e. parameters that
192 can be used with EVP_RAND_get_params(), EVP_RAND_get_ctx_params()
193 and EVP_RAND_set_ctx_params(), respectively.
194 See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.
196 =head2 Information functions
198 EVP_RAND_strength() returns the security strength of the RAND I<ctx>.
200 EVP_RAND_state() returns the current state of the RAND I<ctx>.
201 States defined by the OpenSSL DRBGs are:
207 EVP_RAND_STATE_UNINITIALISED: this DRBG is currently uninitalised.
208 The instantiate call will change this to the ready state.
212 EVP_RAND_STATE_READY: this DRBG is currently ready to generate output.
216 EVP_RAND_STATE_ERROR: this DRBG is in an error state.
220 EVP_RAND_is_a() returns 1 if I<rand> is an implementation of an
221 algorithm that's identifiable with I<name>, otherwise 0.
223 EVP_RAND_provider() returns the provider that holds the implementation
224 of the given I<rand>.
226 EVP_RAND_do_all_provided() traverses all RAND implemented by all activated
227 providers in the given library context I<libctx>, and for each of the
228 implementations, calls the given function I<fn> with the implementation method
229 and the given I<arg> as argument.
231 EVP_RAND_number() returns the internal dynamic number assigned to
234 EVP_RAND_name() returns the canonical name of I<rand>.
236 EVP_RAND_names_do_all() traverses all names for I<rand>, and calls
237 I<fn> with each name and I<data>.
239 EVP_RAND_verify_zeroization() confirms if the internal DRBG state is
240 currently zeroed. This is used by the FIPS provider to support the mandatory
245 The standard parameter names are:
249 =item "state" (B<OSSL_RAND_PARAM_STATE>) <integer>
251 Returns the state of the random number generator.
253 =item "strength" (B<OSSL_RAND_PARAM_STRENGTH>) <unsigned integer>
255 Returns the bit strength of the random number generator.
259 For rands that are also deterministic random bit generators (DRBGs), these
260 additional parameters are recognised. Not all
261 parameters are relevant to, or are understood by all DRBG rands:
265 =item "reseed_requests" (B<OSSL_DRBG_PARAM_RESEED_REQUESTS>) <unsigned integer>
267 Reads or set the number of generate requests before reseeding the
270 =item "reseed_time_interval" (B<OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL>) <integer>
272 Reads or set the number of elapsed seconds before reseeding the
275 =item "max_request" (B<OSSL_DRBG_PARAM_RESEED_REQUESTS>) <unsigned integer>
277 Specifies the maximum number of bytes that can be generated in a single
278 call to OP_rand_generate.
280 =item "min_entropylen" (B<OSSL_DRBG_PARAM_MIN_ENTROPYLEN>) <unsigned integer>
282 =item "max_entropylen" (B<OSSL_DRBG_PARAM_MAX_ENTROPYLEN>) <unsigned integer>
284 Specify the minimum and maximum number of bytes of random material that
285 can be used to seed the DRBG.
287 =item "min_noncelen" (B<OSSL_DRBG_PARAM_MIN_NONCELEN>) <unsigned integer>
289 =item "max_noncelen" (B<OSSL_DRBG_PARAM_MAX_NONCELEN>) <unsigned integer>
291 Specify the minimum and maximum number of bytes of nonce that can be used to
294 =item "max_perslen" (B<OSSL_DRBG_PARAM_MAX_PERSLEN>) <unsigned integer>
296 =item "max_adinlen" (B<OSSL_DRBG_PARAM_MAX_ADINLEN>) <unsigned integer>
298 Specify the minimum and maximum number of bytes of personalisation string
299 that can be used with the DRBG.
301 =item "reseed_counter" (B<OSSL_DRBG_PARAM_RESEED_CTR>) <unsigned integer>
303 Specifies the number of times the DRBG has been seeded or reseeded.
305 =item "properties" (B<OSSL_RAND_PARAM_PROPERTIES>) <UTF8 string>
307 =item "mac" (B<OSSL_RAND_PARAM_MAC>) <UTF8 string>
309 =item "digest" (B<OSSL_RAND_PARAM_DIGEST>) <UTF8 string>
311 =item "cipher" (B<OSSL_RAND_PARAM_CIPHER>) <UTF8 string>
313 For RAND implementations that use an underlying computation MAC, digest or
314 cipher, these parameters set what the algorithm should be.
316 The value is always the name of the intended algorithm,
317 or the properties in the case of B<OSSL_RAND_PARAM_PROPERTIES>.
323 EVP_RAND_fetch() returns a pointer to a newly fetched B<EVP_RAND>, or
324 NULL if allocation failed.
326 EVP_RAND_provider() returns a pointer to the provider for the RAND, or
329 EVP_RAND_CTX_rand() returns a pointer to the B<EVP_RAND> associated with the
332 EVP_RAND_name() returns the name of the random number generation algorithm.
334 EVP_RAND_number() returns the provider specific identification number
335 for the specified algorithm.
337 EVP_RAND_up_ref() returns 1 on success, 0 on error.
339 EVP_RAND_CTX_new() returns either the newly allocated
340 B<EVP_RAND_CTX> structure or NULL if an error occurred.
342 EVP_RAND_CTX_free() does not return a value.
344 EVP_RAND_nonce() returns the length of the nonce.
346 EVP_RAND_strength() returns the strenght of the random number generator in bits.
348 EVP_RAND_gettable_params(), EVP_RAND_gettable_ctx_params() and
349 EVP_RAND_settable_ctx_params() return an array of OSSL_PARAMs.
351 EVP_RAND_verify_zeroization() returns 1 if the internal DRBG state is
352 currently zeroed, and 0 if not.
354 The remaining functions return 1 for success and 0 or a negative value for
360 L<EVP_RAND-CTR-DRBG(7)>,
361 L<EVP_RAND-HASH-DRBG(7)>,
362 L<EVP_RAND-HMAC-DRBG(7)>,
363 L<EVP_RAND-TEST-RAND(7)>,
368 This functionality was added to OpenSSL 3.0.
372 Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
374 Licensed under the Apache License 2.0 (the "License"). You may not use
375 this file except in compliance with the License. You can obtain a copy
376 in the file LICENSE in the source distribution or at
377 L<https://www.openssl.org/source/license.html>.