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,
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(OSSL_LIB_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(OSSL_LIB_CTX *libctx,
42 void (*fn)(EVP_RAND *rand, void *arg),
44 int 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_verify_zeroization(EVP_RAND_CTX *ctx);
61 unsigned int EVP_RAND_strength(EVP_RAND_CTX *ctx);
62 int EVP_RAND_state(EVP_RAND_CTX *ctx);
64 #define EVP_RAND_STATE_UNINITIALISED 0
65 #define EVP_RAND_STATE_READY 1
66 #define EVP_RAND_STATE_ERROR 2
70 The EVP RAND routines are a high-level interface to random number generators
71 both deterministic and not.
72 If you just want to generate random bytes then you don't need to use
73 these functions: just call RAND_bytes() or RAND_priv_bytes().
74 If you want to do more, these calls should be used instead of the older
75 RAND and RAND_DRBG functions.
77 After creating a B<EVP_RAND_CTX> for the required algorithm using
78 EVP_RAND_CTX_new(), inputs to the algorithm are supplied
79 using calls to EVP_RAND_set_ctx_params() before
80 calling EVP_RAND_instantiate() and then EVP_RAND_generate() to produce
81 cryptographically secure random bytes.
85 B<EVP_RAND> is a type that holds the implementation of a RAND.
87 B<EVP_RAND_CTX> is a context type that holds the algorithm inputs.
88 B<EVP_RAND_CTX> structures are reference counted.
90 =head2 Algorithm implementation fetching
92 EVP_RAND_fetch() fetches an implementation of a RAND I<algorithm>, given
93 a library context I<libctx> and a set of I<properties>.
94 See L<provider(7)/Fetching algorithms> for further information.
96 The returned value must eventually be freed with
99 EVP_RAND_up_ref() increments the reference count of an already fetched
102 EVP_RAND_free() frees a fetched algorithm.
103 NULL is a valid parameter, for which this function is a no-op.
105 =head2 Context manipulation functions
107 EVP_RAND_CTX_new() creates a new context for the RAND implementation I<rand>.
108 If not NULL, I<parent> specifies the seed source for this implementation.
109 Not all random number generators need to have a seed source specified.
110 If a parent is required, a NULL I<parent> will utilise the operating
111 system entropy sources.
112 It is recommended to minimise the number of random number generators that
113 rely on the operating system for their randomness because this is often scarce.
115 EVP_RAND_CTX_free() frees up the context I<ctx>. If I<ctx> is NULL, nothing
118 EVP_RAND_CTX_rand() returns the B<EVP_RAND> associated with the context
121 =head2 Random Number Generator Functions
123 EVP_RAND_instantiate() instantiates the RAND I<ctx> with a minimum security
124 strength of <strength> and personalisation string I<pstr> of length <pstr_len>.
125 If I<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 800-90C.
128 EVP_RAND_uninstantiate() uninstantiates the RAND I<ctx> as per
129 NIST SP 800-90A and SP 800-90C. Subsequent to this call, the RAND cannot
130 be used to generate bytes. It can only be freed or instantiated again.
132 EVP_RAND_generate() produces random bytes from the RAND I<ctx> with the
133 additional input I<addin> of length I<addin_len>. The bytes
134 produced will meet the security I<strength>.
135 If I<prediction_resistance> is specified, fresh entropy from a live source
136 will be sought. This call operates as per NIST SP 800-90A and SP 800-90C.
138 EVP_RAND_reseed() reseeds the RAND with new entropy.
139 Entropy I<ent> of length I<ent_len> bytes can be supplied as can additional
140 input I<addin> of length I<addin_len> bytes. In the FIPS provider, both are
141 treated as additional input as per NIST SP-800-90Ar1, Sections 9.1 and 9.2.
142 Additional seed material is also drawn from the RAND's parent or the
143 operating system. If I<prediction_resistance> is specified, fresh entropy
144 from a live source will be sought. This call operates as per NIST SP 800-90A
147 EVP_RAND_nonce() creates a nonce in I<out> of maximum length I<outlen>
148 bytes from the RAND I<ctx>. The function returns the length of the generated
149 nonce. If I<out> is NULL, the length is still returned but no generation
150 takes place. This allows a caller to dynamically allocate a buffer of the
153 EVP_RAND_enable_locking() enables locking for the RAND I<ctx> and all of
154 its parents. After this I<ctx> will operate in a thread safe manner, albeit
155 more slowly. This function is not itself thread safe if called with the same
156 I<ctx> from multiple threads. Typically locking should be enabled before a
157 I<ctx> is shared across multiple threads.
159 EVP_RAND_get_params() retrieves details about the implementation
161 The set of parameters given with I<params> determine exactly what
162 parameters should be retrieved.
163 Note that a parameter that is unknown in the underlying context is
166 EVP_RAND_get_ctx_params() retrieves chosen parameters, given the
167 context I<ctx> and its underlying context.
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_set_ctx_params() passes chosen parameters to the underlying
174 context, given a context I<ctx>.
175 The set of parameters given with I<params> determine exactly what
176 parameters are passed down.
177 Note that a parameter that is unknown in the underlying context is
179 Also, what happens when a needed parameter isn't passed down is
180 defined by the implementation.
182 EVP_RAND_gettable_params(), EVP_RAND_gettable_ctx_params() and
183 EVP_RAND_settable_ctx_params() get a constant B<OSSL_PARAM> array that
184 describes the retrievable and settable parameters, i.e. parameters that
185 can be used with EVP_RAND_get_params(), EVP_RAND_get_ctx_params()
186 and EVP_RAND_set_ctx_params(), respectively.
187 See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.
189 =head2 Information functions
191 EVP_RAND_strength() returns the security strength of the RAND I<ctx>.
193 EVP_RAND_state() returns the current state of the RAND I<ctx>.
194 States defined by the OpenSSL RNGs are:
200 EVP_RAND_STATE_UNINITIALISED: this RNG is currently uninitialised.
201 The instantiate call will change this to the ready state.
205 EVP_RAND_STATE_READY: this RNG is currently ready to generate output.
209 EVP_RAND_STATE_ERROR: this RNG is in an error state.
213 EVP_RAND_is_a() returns 1 if I<rand> is an implementation of an
214 algorithm that's identifiable with I<name>, otherwise 0.
216 EVP_RAND_provider() returns the provider that holds the implementation
217 of the given I<rand>.
219 EVP_RAND_do_all_provided() traverses all RAND implemented by all activated
220 providers in the given library context I<libctx>, and for each of the
221 implementations, calls the given function I<fn> with the implementation method
222 and the given I<arg> as argument.
224 EVP_RAND_number() returns the internal dynamic number assigned to
227 EVP_RAND_name() returns the canonical name of I<rand>.
229 EVP_RAND_names_do_all() traverses all names for I<rand>, and calls
230 I<fn> with each name and I<data>.
232 EVP_RAND_verify_zeroization() confirms if the internal DRBG state is
233 currently zeroed. This is used by the FIPS provider to support the mandatory
238 The standard parameter names are:
242 =item "state" (B<OSSL_RAND_PARAM_STATE>) <integer>
244 Returns the state of the random number generator.
246 =item "strength" (B<OSSL_RAND_PARAM_STRENGTH>) <unsigned integer>
248 Returns the bit strength of the random number generator.
252 For rands that are also deterministic random bit generators (DRBGs), these
253 additional parameters are recognised. Not all
254 parameters are relevant to, or are understood by all DRBG rands:
258 =item "reseed_requests" (B<OSSL_DRBG_PARAM_RESEED_REQUESTS>) <unsigned integer>
260 Reads or set the number of generate requests before reseeding the
263 =item "reseed_time_interval" (B<OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL>) <integer>
265 Reads or set the number of elapsed seconds before reseeding the
268 =item "max_request" (B<OSSL_DRBG_PARAM_RESEED_REQUESTS>) <unsigned integer>
270 Specifies the maximum number of bytes that can be generated in a single
271 call to OSSL_FUNC_rand_generate.
273 =item "min_entropylen" (B<OSSL_DRBG_PARAM_MIN_ENTROPYLEN>) <unsigned integer>
275 =item "max_entropylen" (B<OSSL_DRBG_PARAM_MAX_ENTROPYLEN>) <unsigned integer>
277 Specify the minimum and maximum number of bytes of random material that
278 can be used to seed the DRBG.
280 =item "min_noncelen" (B<OSSL_DRBG_PARAM_MIN_NONCELEN>) <unsigned integer>
282 =item "max_noncelen" (B<OSSL_DRBG_PARAM_MAX_NONCELEN>) <unsigned integer>
284 Specify the minimum and maximum number of bytes of nonce that can be used to
287 =item "max_perslen" (B<OSSL_DRBG_PARAM_MAX_PERSLEN>) <unsigned integer>
289 =item "max_adinlen" (B<OSSL_DRBG_PARAM_MAX_ADINLEN>) <unsigned integer>
291 Specify the minimum and maximum number of bytes of personalisation string
292 that can be used with the DRBG.
294 =item "reseed_counter" (B<OSSL_DRBG_PARAM_RESEED_COUNTER>) <unsigned integer>
296 Specifies the number of times the DRBG has been seeded or reseeded.
298 =item "properties" (B<OSSL_RAND_PARAM_PROPERTIES>) <UTF8 string>
300 =item "mac" (B<OSSL_RAND_PARAM_MAC>) <UTF8 string>
302 =item "digest" (B<OSSL_RAND_PARAM_DIGEST>) <UTF8 string>
304 =item "cipher" (B<OSSL_RAND_PARAM_CIPHER>) <UTF8 string>
306 For RAND implementations that use an underlying computation MAC, digest or
307 cipher, these parameters set what the algorithm should be.
309 The value is always the name of the intended algorithm,
310 or the properties in the case of B<OSSL_RAND_PARAM_PROPERTIES>.
316 An B<EVP_RAND_CTX> needs to have locking enabled if it acts as the parent of
317 more than one child and the children can be accessed concurrently. This must
318 be done by explicitly calling EVP_RAND_enable_locking().
322 EVP_RAND_fetch() returns a pointer to a newly fetched B<EVP_RAND>, or
323 NULL if allocation failed.
325 EVP_RAND_provider() returns a pointer to the provider for the RAND, or
328 EVP_RAND_CTX_rand() returns a pointer to the B<EVP_RAND> associated with the
331 EVP_RAND_name() returns the name of the random number generation algorithm.
333 EVP_RAND_number() returns the provider specific identification number
334 for the specified algorithm.
336 EVP_RAND_up_ref() returns 1 on success, 0 on error.
338 EVP_RAND_names_do_all() returns 1 if the callback was called for all names. A
339 return value of 0 means that the callback was not called for any names.
341 EVP_RAND_CTX_new() returns either the newly allocated
342 B<EVP_RAND_CTX> structure or NULL if an error occurred.
344 EVP_RAND_CTX_free() does not return a value.
346 EVP_RAND_nonce() returns the length of the nonce.
348 EVP_RAND_strength() returns the strength of the random number generator in bits.
350 EVP_RAND_gettable_params(), EVP_RAND_gettable_ctx_params() and
351 EVP_RAND_settable_ctx_params() return an array of OSSL_PARAMs.
353 EVP_RAND_verify_zeroization() returns 1 if the internal DRBG state is
354 currently zeroed, and 0 if not.
356 The remaining functions return 1 for success and 0 or a negative value for
362 L<EVP_RAND-CTR-DRBG(7)>,
363 L<EVP_RAND-HASH-DRBG(7)>,
364 L<EVP_RAND-HMAC-DRBG(7)>,
365 L<EVP_RAND-TEST-RAND(7)>,
370 This functionality was added to OpenSSL 3.0.
374 Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
376 Licensed under the Apache License 2.0 (the "License"). You may not use
377 this file except in compliance with the License. You can obtain a copy
378 in the file LICENSE in the source distribution or at
379 L<https://www.openssl.org/source/license.html>.