1=pod 2 3=head1 NAME 4 5EVP_RAND, EVP_RAND_fetch, EVP_RAND_free, EVP_RAND_up_ref, EVP_RAND_CTX, 6EVP_RAND_CTX_new, EVP_RAND_CTX_free, EVP_RAND_CTX_up_ref, EVP_RAND_instantiate, 7EVP_RAND_uninstantiate, EVP_RAND_generate, EVP_RAND_reseed, EVP_RAND_nonce, 8EVP_RAND_enable_locking, EVP_RAND_verify_zeroization, EVP_RAND_get_strength, 9EVP_RAND_get_state, 10EVP_RAND_get0_provider, EVP_RAND_CTX_get0_rand, EVP_RAND_is_a, 11EVP_RAND_get0_name, EVP_RAND_names_do_all, 12EVP_RAND_get0_description, 13EVP_RAND_CTX_get_params, 14EVP_RAND_CTX_set_params, EVP_RAND_do_all_provided, EVP_RAND_get_params, 15EVP_RAND_gettable_ctx_params, EVP_RAND_settable_ctx_params, 16EVP_RAND_CTX_gettable_params, EVP_RAND_CTX_settable_params, 17EVP_RAND_gettable_params, EVP_RAND_STATE_UNINITIALISED, EVP_RAND_STATE_READY, 18EVP_RAND_STATE_ERROR - EVP RAND routines 19 20=head1 SYNOPSIS 21 22 #include <openssl/evp.h> 23 24 typedef struct evp_rand_st EVP_RAND; 25 typedef struct evp_rand_ctx_st EVP_RAND_CTX; 26 27 EVP_RAND *EVP_RAND_fetch(OSSL_LIB_CTX *libctx, const char *algorithm, 28 const char *properties); 29 int EVP_RAND_up_ref(EVP_RAND *rand); 30 void EVP_RAND_free(EVP_RAND *rand); 31 EVP_RAND_CTX *EVP_RAND_CTX_new(EVP_RAND *rand, EVP_RAND_CTX *parent); 32 void EVP_RAND_CTX_free(EVP_RAND_CTX *ctx); 33 int EVP_RAND_CTX_up_ref(EVP_RAND_CTX *ctx); 34 EVP_RAND *EVP_RAND_CTX_get0_rand(EVP_RAND_CTX *ctx); 35 int EVP_RAND_get_params(EVP_RAND *rand, OSSL_PARAM params[]); 36 int EVP_RAND_CTX_get_params(EVP_RAND_CTX *ctx, OSSL_PARAM params[]); 37 int EVP_RAND_CTX_set_params(EVP_RAND_CTX *ctx, const OSSL_PARAM params[]); 38 const OSSL_PARAM *EVP_RAND_gettable_params(const EVP_RAND *rand); 39 const OSSL_PARAM *EVP_RAND_gettable_ctx_params(const EVP_RAND *rand); 40 const OSSL_PARAM *EVP_RAND_settable_ctx_params(const EVP_RAND *rand); 41 const OSSL_PARAM *EVP_RAND_CTX_gettable_params(EVP_RAND_CTX *ctx); 42 const OSSL_PARAM *EVP_RAND_CTX_settable_params(EVP_RAND_CTX *ctx); 43 const char *EVP_RAND_get0_name(const EVP_RAND *rand); 44 const char *EVP_RAND_get0_description(const EVP_RAND *rand); 45 int EVP_RAND_is_a(const EVP_RAND *rand, const char *name); 46 const OSSL_PROVIDER *EVP_RAND_get0_provider(const EVP_RAND *rand); 47 void EVP_RAND_do_all_provided(OSSL_LIB_CTX *libctx, 48 void (*fn)(EVP_RAND *rand, void *arg), 49 void *arg); 50 int EVP_RAND_names_do_all(const EVP_RAND *rand, 51 void (*fn)(const char *name, void *data), 52 void *data); 53 54 int EVP_RAND_instantiate(EVP_RAND_CTX *ctx, unsigned int strength, 55 int prediction_resistance, 56 const unsigned char *pstr, size_t pstr_len, 57 const OSSL_PARAM params[]); 58 int EVP_RAND_uninstantiate(EVP_RAND_CTX *ctx); 59 int EVP_RAND_generate(EVP_RAND_CTX *ctx, unsigned char *out, size_t outlen, 60 unsigned int strength, int prediction_resistance, 61 const unsigned char *addin, size_t addin_len); 62 int EVP_RAND_reseed(EVP_RAND_CTX *ctx, int prediction_resistance, 63 const unsigned char *ent, size_t ent_len, 64 const unsigned char *addin, size_t addin_len); 65 int EVP_RAND_nonce(EVP_RAND_CTX *ctx, unsigned char *out, size_t outlen); 66 int EVP_RAND_enable_locking(EVP_RAND_CTX *ctx); 67 int EVP_RAND_verify_zeroization(EVP_RAND_CTX *ctx); 68 unsigned int EVP_RAND_get_strength(EVP_RAND_CTX *ctx); 69 int EVP_RAND_get_state(EVP_RAND_CTX *ctx); 70 71 #define EVP_RAND_STATE_UNINITIALISED 0 72 #define EVP_RAND_STATE_READY 1 73 #define EVP_RAND_STATE_ERROR 2 74 75=head1 DESCRIPTION 76 77The EVP RAND routines are a high-level interface to random number generators 78both deterministic and not. 79If you just want to generate random bytes then you don't need to use 80these functions: just call RAND_bytes() or RAND_priv_bytes(). 81If you want to do more, these calls should be used instead of the older 82RAND and RAND_DRBG functions. 83 84After creating a B<EVP_RAND_CTX> for the required algorithm using 85EVP_RAND_CTX_new(), inputs to the algorithm are supplied either by 86passing them as part of the EVP_RAND_instantiate() call or using calls to 87EVP_RAND_CTX_set_params() before calling EVP_RAND_instantiate(). Finally, 88call EVP_RAND_generate() to produce cryptographically secure random bytes. 89 90=head2 Types 91 92B<EVP_RAND> is a type that holds the implementation of a RAND. 93 94B<EVP_RAND_CTX> is a context type that holds the algorithm inputs. 95B<EVP_RAND_CTX> structures are reference counted. 96 97=head2 Algorithm implementation fetching 98 99EVP_RAND_fetch() fetches an implementation of a RAND I<algorithm>, given 100a library context I<libctx> and a set of I<properties>. 101See L<crypto(7)/ALGORITHM FETCHING> for further information. 102 103The returned value must eventually be freed with 104L<EVP_RAND_free(3)>. 105 106EVP_RAND_up_ref() increments the reference count of an already fetched 107RAND. 108 109EVP_RAND_free() frees a fetched algorithm. 110NULL is a valid parameter, for which this function is a no-op. 111 112=head2 Context manipulation functions 113 114EVP_RAND_CTX_new() creates a new context for the RAND implementation I<rand>. 115If not NULL, I<parent> specifies the seed source for this implementation. 116Not all random number generators need to have a seed source specified. 117If a parent is required, a NULL I<parent> will utilise the operating 118system entropy sources. 119It is recommended to minimise the number of random number generators that 120rely on the operating system for their randomness because this is often scarce. 121 122EVP_RAND_CTX_free() frees up the context I<ctx>. If I<ctx> is NULL, nothing 123is done. 124 125EVP_RAND_CTX_get0_rand() returns the B<EVP_RAND> associated with the context 126I<ctx>. 127 128=head2 Random Number Generator Functions 129 130EVP_RAND_instantiate() processes any parameters in I<params> and 131then instantiates the RAND I<ctx> with a minimum security strength 132of <strength> and personalisation string I<pstr> of length <pstr_len>. 133If I<prediction_resistance> is specified, fresh entropy from a live source 134will be sought. This call operates as per NIST SP 800-90A and SP 800-90C. 135 136EVP_RAND_uninstantiate() uninstantiates the RAND I<ctx> as per 137NIST SP 800-90A and SP 800-90C. Subsequent to this call, the RAND cannot 138be used to generate bytes. It can only be freed or instantiated again. 139 140EVP_RAND_generate() produces random bytes from the RAND I<ctx> with the 141additional input I<addin> of length I<addin_len>. The bytes 142produced will meet the security I<strength>. 143If I<prediction_resistance> is specified, fresh entropy from a live source 144will be sought. This call operates as per NIST SP 800-90A and SP 800-90C. 145 146EVP_RAND_reseed() reseeds the RAND with new entropy. 147Entropy I<ent> of length I<ent_len> bytes can be supplied as can additional 148input I<addin> of length I<addin_len> bytes. In the FIPS provider, both are 149treated as additional input as per NIST SP-800-90Ar1, Sections 9.1 and 9.2. 150Additional seed material is also drawn from the RAND's parent or the 151operating system. If I<prediction_resistance> is specified, fresh entropy 152from a live source will be sought. This call operates as per NIST SP 800-90A 153and SP 800-90C. 154 155EVP_RAND_nonce() creates a nonce in I<out> of length I<outlen> 156bytes from the RAND I<ctx>. 157 158EVP_RAND_enable_locking() enables locking for the RAND I<ctx> and all of 159its parents. After this I<ctx> will operate in a thread safe manner, albeit 160more slowly. This function is not itself thread safe if called with the same 161I<ctx> from multiple threads. Typically locking should be enabled before a 162I<ctx> is shared across multiple threads. 163 164EVP_RAND_get_params() retrieves details about the implementation 165I<rand>. 166The set of parameters given with I<params> determine exactly what 167parameters should be retrieved. 168Note that a parameter that is unknown in the underlying context is 169simply ignored. 170 171EVP_RAND_CTX_get_params() retrieves chosen parameters, given the 172context I<ctx> and its underlying context. 173The set of parameters given with I<params> determine exactly what 174parameters should be retrieved. 175Note that a parameter that is unknown in the underlying context is 176simply ignored. 177 178EVP_RAND_CTX_set_params() passes chosen parameters to the underlying 179context, given a context I<ctx>. 180The set of parameters given with I<params> determine exactly what 181parameters are passed down. 182Note that a parameter that is unknown in the underlying context is 183simply ignored. 184Also, what happens when a needed parameter isn't passed down is 185defined by the implementation. 186 187EVP_RAND_gettable_params() returns an L<OSSL_PARAM(3)> array that describes 188the retrievable and settable parameters. EVP_RAND_gettable_params() returns 189parameters that can be used with EVP_RAND_get_params(). 190 191EVP_RAND_gettable_ctx_params() and EVP_RAND_CTX_gettable_params() return 192constant L<OSSL_PARAM(3)> arrays that describe the retrievable parameters that 193can be used with EVP_RAND_CTX_get_params(). EVP_RAND_gettable_ctx_params() 194returns the parameters that can be retrieved from the algorithm, whereas 195EVP_RAND_CTX_gettable_params() returns the parameters that can be retrieved 196in the context's current state. 197 198EVP_RAND_settable_ctx_params() and EVP_RAND_CTX_settable_params() return 199constant L<OSSL_PARAM(3)> arrays that describe the settable parameters that 200can be used with EVP_RAND_CTX_set_params(). EVP_RAND_settable_ctx_params() 201returns the parameters that can be retrieved from the algorithm, whereas 202EVP_RAND_CTX_settable_params() returns the parameters that can be retrieved 203in the context's current state. 204 205=head2 Information functions 206 207EVP_RAND_get_strength() returns the security strength of the RAND I<ctx>. 208 209EVP_RAND_get_state() returns the current state of the RAND I<ctx>. 210States defined by the OpenSSL RNGs are: 211 212=over 4 213 214=item * 215 216EVP_RAND_STATE_UNINITIALISED: this RNG is currently uninitialised. 217The instantiate call will change this to the ready state. 218 219=item * 220 221EVP_RAND_STATE_READY: this RNG is currently ready to generate output. 222 223=item * 224 225EVP_RAND_STATE_ERROR: this RNG is in an error state. 226 227=back 228 229EVP_RAND_is_a() returns 1 if I<rand> is an implementation of an 230algorithm that's identifiable with I<name>, otherwise 0. 231 232EVP_RAND_get0_provider() returns the provider that holds the implementation 233of the given I<rand>. 234 235EVP_RAND_do_all_provided() traverses all RAND implemented by all activated 236providers in the given library context I<libctx>, and for each of the 237implementations, calls the given function I<fn> with the implementation method 238and the given I<arg> as argument. 239 240EVP_RAND_get0_name() returns the canonical name of I<rand>. 241 242EVP_RAND_names_do_all() traverses all names for I<rand>, and calls 243I<fn> with each name and I<data>. 244 245EVP_RAND_get0_description() returns a description of the rand, meant for 246display and human consumption. The description is at the discretion of 247the rand implementation. 248 249EVP_RAND_verify_zeroization() confirms if the internal DRBG state is 250currently zeroed. This is used by the FIPS provider to support the mandatory 251self tests. 252 253=head1 PARAMETERS 254 255The standard parameter names are: 256 257=over 4 258 259=item "state" (B<OSSL_RAND_PARAM_STATE>) <integer> 260 261Returns the state of the random number generator. 262 263=item "strength" (B<OSSL_RAND_PARAM_STRENGTH>) <unsigned integer> 264 265Returns the bit strength of the random number generator. 266 267=item "fips-indicator" (B<OSSL_RAND_PARAM_FIPS_APPROVED_INDICATOR>) <integer> 268 269A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. 270This option is used by the OpenSSL FIPS provider and is not supported 271by all EVP_RAND sources. 272 273=back 274 275For rands that are also deterministic random bit generators (DRBGs), these 276additional parameters are recognised. Not all 277parameters are relevant to, or are understood by all DRBG rands: 278 279=over 4 280 281=item "reseed_requests" (B<OSSL_DRBG_PARAM_RESEED_REQUESTS>) <unsigned integer> 282 283Reads or set the number of generate requests before reseeding the 284associated RAND ctx. 285 286=item "reseed_time_interval" (B<OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL>) <integer> 287 288Reads or set the number of elapsed seconds before reseeding the 289associated RAND ctx. 290 291=item "max_request" (B<OSSL_RAND_PARAM_MAX_REQUEST>) <unsigned integer> 292 293Specifies the maximum number of bytes that can be generated in a single 294call to OSSL_FUNC_rand_generate. 295 296=item "min_entropylen" (B<OSSL_DRBG_PARAM_MIN_ENTROPYLEN>) <unsigned integer> 297 298=item "max_entropylen" (B<OSSL_DRBG_PARAM_MAX_ENTROPYLEN>) <unsigned integer> 299 300Specify the minimum and maximum number of bytes of random material that 301can be used to seed the DRBG. 302 303=item "min_noncelen" (B<OSSL_DRBG_PARAM_MIN_NONCELEN>) <unsigned integer> 304 305=item "max_noncelen" (B<OSSL_DRBG_PARAM_MAX_NONCELEN>) <unsigned integer> 306 307Specify the minimum and maximum number of bytes of nonce that can be used to 308seed the DRBG. 309 310=item "max_perslen" (B<OSSL_DRBG_PARAM_MAX_PERSLEN>) <unsigned integer> 311 312=item "max_adinlen" (B<OSSL_DRBG_PARAM_MAX_ADINLEN>) <unsigned integer> 313 314Specify the minimum and maximum number of bytes of personalisation string 315that can be used with the DRBG. 316 317=item "reseed_counter" (B<OSSL_DRBG_PARAM_RESEED_COUNTER>) <unsigned integer> 318 319Specifies the number of times the DRBG has been seeded or reseeded. 320 321=item "properties" (B<OSSL_RAND_PARAM_PROPERTIES>) <UTF8 string> 322 323=item "mac" (B<OSSL_RAND_PARAM_MAC>) <UTF8 string> 324 325=item "digest" (B<OSSL_RAND_PARAM_DIGEST>) <UTF8 string> 326 327=item "cipher" (B<OSSL_RAND_PARAM_CIPHER>) <UTF8 string> 328 329For RAND implementations that use an underlying computation MAC, digest or 330cipher, these parameters set what the algorithm should be. 331 332The value is always the name of the intended algorithm, 333or the properties in the case of B<OSSL_RAND_PARAM_PROPERTIES>. 334 335=back 336 337=head1 NOTES 338 339The use of a nonzero value for the I<prediction_resistance> argument to 340EVP_RAND_instantiate(), EVP_RAND_generate() or EVP_RAND_reseed() should 341be used sparingly. In the default setup, this will cause all public and 342private DRBGs to be reseeded on next use. Since, by default, public and 343private DRBGs are allocated on a per thread basis, this can result in 344significant overhead for highly multi-threaded applications. For normal 345use-cases, the default "reseed_requests" and "reseed_time_interval" 346thresholds ensure sufficient prediction resistance over time and you 347can reduce those values if you think they are too high. Explicitly 348requesting prediction resistance is intended for more special use-cases 349like generating long-term secrets. 350 351An B<EVP_RAND_CTX> needs to have locking enabled if it acts as the parent of 352more than one child and the children can be accessed concurrently. This must 353be done by explicitly calling EVP_RAND_enable_locking(). 354 355The RAND life-cycle is described in L<life_cycle-rand(7)>. In the future, 356the transitions described there will be enforced. When this is done, it will 357not be considered a breaking change to the API. 358 359=head1 RETURN VALUES 360 361EVP_RAND_fetch() returns a pointer to a newly fetched B<EVP_RAND>, or 362NULL if allocation failed. 363 364EVP_RAND_get0_provider() returns a pointer to the provider for the RAND, or 365NULL on error. 366 367EVP_RAND_CTX_get0_rand() returns a pointer to the B<EVP_RAND> associated 368with the context. 369 370EVP_RAND_get0_name() returns the name of the random number generation 371algorithm. 372 373EVP_RAND_up_ref() returns 1 on success, 0 on error. 374 375EVP_RAND_names_do_all() returns 1 if the callback was called for all names. A 376return value of 0 means that the callback was not called for any names. 377 378EVP_RAND_CTX_new() returns either the newly allocated 379B<EVP_RAND_CTX> structure or NULL if an error occurred. 380 381EVP_RAND_CTX_free() does not return a value. 382 383EVP_RAND_CTX_up_ref() returns 1 on success, 0 on error. 384 385EVP_RAND_nonce() returns 1 on success, 0 on error. 386 387EVP_RAND_get_strength() returns the strength of the random number generator 388in bits. 389 390EVP_RAND_gettable_params(), EVP_RAND_gettable_ctx_params() and 391EVP_RAND_settable_ctx_params() return an array of OSSL_PARAMs. 392 393EVP_RAND_verify_zeroization() returns 1 if the internal DRBG state is 394currently zeroed, and 0 if not. 395 396The remaining functions return 1 for success and 0 or a negative value for 397failure. 398 399=head1 SEE ALSO 400 401L<RAND_bytes(3)>, 402L<EVP_RAND-CTR-DRBG(7)>, 403L<EVP_RAND-HASH-DRBG(7)>, 404L<EVP_RAND-HMAC-DRBG(7)>, 405L<EVP_RAND-TEST-RAND(7)>, 406L<provider-rand(7)>, 407L<life_cycle-rand(7)> 408 409=head1 HISTORY 410 411EVP_RAND_CTX_up_ref() was added in OpenSSL 3.1. 412 413The remaining functions were added in OpenSSL 3.0. 414 415=head1 COPYRIGHT 416 417Copyright 2020-2025 The OpenSSL Project Authors. All Rights Reserved. 418 419Licensed under the Apache License 2.0 (the "License"). You may not use 420this file except in compliance with the License. You can obtain a copy 421in the file LICENSE in the source distribution or at 422L<https://www.openssl.org/source/license.html>. 423 424=cut 425