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