NAME¶

EVP_RAND, EVP_RAND_fetch, EVP_RAND_free, EVP_RAND_up_ref, EVP_RAND_CTX, EVP_RAND_CTX_new, EVP_RAND_CTX_free, EVP_RAND_CTX_up_ref, EVP_RAND_instantiate, EVP_RAND_uninstantiate, EVP_RAND_generate, EVP_RAND_reseed, EVP_RAND_nonce, EVP_RAND_enable_locking, EVP_RAND_verify_zeroization, EVP_RAND_get_strength, EVP_RAND_get_state, EVP_RAND_get0_provider, EVP_RAND_CTX_get0_rand, EVP_RAND_is_a, EVP_RAND_get0_name, EVP_RAND_names_do_all, EVP_RAND_get0_description, EVP_RAND_CTX_get_params, EVP_RAND_CTX_set_params, EVP_RAND_do_all_provided, EVP_RAND_get_params, EVP_RAND_gettable_ctx_params, EVP_RAND_settable_ctx_params, EVP_RAND_CTX_gettable_params, EVP_RAND_CTX_settable_params, EVP_RAND_gettable_params, EVP_RAND_STATE_UNINITIALISED, EVP_RAND_STATE_READY, EVP_RAND_STATE_ERROR - EVP RAND routines

SYNOPSIS¶

 #include <openssl/evp.h>
 typedef struct evp_rand_st EVP_RAND;
 typedef struct evp_rand_ctx_st EVP_RAND_CTX;
 EVP_RAND *EVP_RAND_fetch(OSSL_LIB_CTX *libctx, const char *algorithm,
                        const char *properties);
 int EVP_RAND_up_ref(EVP_RAND *rand);
 void EVP_RAND_free(EVP_RAND *rand);
 EVP_RAND_CTX *EVP_RAND_CTX_new(EVP_RAND *rand, EVP_RAND_CTX *parent);
 void EVP_RAND_CTX_free(EVP_RAND_CTX *ctx);
 int EVP_RAND_CTX_up_ref(EVP_RAND_CTX *ctx);
 EVP_RAND *EVP_RAND_CTX_get0_rand(EVP_RAND_CTX *ctx);
 int EVP_RAND_get_params(EVP_RAND *rand, OSSL_PARAM params[]);
 int EVP_RAND_CTX_get_params(EVP_RAND_CTX *ctx, OSSL_PARAM params[]);
 int EVP_RAND_CTX_set_params(EVP_RAND_CTX *ctx, const OSSL_PARAM params[]);
 const OSSL_PARAM *EVP_RAND_gettable_params(const EVP_RAND *rand);
 const OSSL_PARAM *EVP_RAND_gettable_ctx_params(const EVP_RAND *rand);
 const OSSL_PARAM *EVP_RAND_settable_ctx_params(const EVP_RAND *rand);
 const OSSL_PARAM *EVP_RAND_CTX_gettable_params(EVP_RAND_CTX *ctx);
 const OSSL_PARAM *EVP_RAND_CTX_settable_params(EVP_RAND_CTX *ctx);
 const char *EVP_RAND_get0_name(const EVP_RAND *rand);
 const char *EVP_RAND_get0_description(const EVP_RAND *rand);
 int EVP_RAND_is_a(const EVP_RAND *rand, const char *name);
 const OSSL_PROVIDER *EVP_RAND_get0_provider(const EVP_RAND *rand);
 void EVP_RAND_do_all_provided(OSSL_LIB_CTX *libctx,
                               void (*fn)(EVP_RAND *rand, void *arg),
                               void *arg);
 int EVP_RAND_names_do_all(const EVP_RAND *rand,
                           void (*fn)(const char *name, void *data),
                           void *data);
 int EVP_RAND_instantiate(EVP_RAND_CTX *ctx, unsigned int strength,
                          int prediction_resistance,
                          const unsigned char *pstr, size_t pstr_len,
                          const OSSL_PARAM params[]);
 int EVP_RAND_uninstantiate(EVP_RAND_CTX *ctx);
 int EVP_RAND_generate(EVP_RAND_CTX *ctx, unsigned char *out, size_t outlen,
                       unsigned int strength, int prediction_resistance,
                       const unsigned char *addin, size_t addin_len);
 int EVP_RAND_reseed(EVP_RAND_CTX *ctx, int prediction_resistance,
                     const unsigned char *ent, size_t ent_len,
                     const unsigned char *addin, size_t addin_len);
 int EVP_RAND_nonce(EVP_RAND_CTX *ctx, unsigned char *out, size_t outlen);
 int EVP_RAND_enable_locking(EVP_RAND_CTX *ctx);
 int EVP_RAND_verify_zeroization(EVP_RAND_CTX *ctx);
 unsigned int EVP_RAND_get_strength(EVP_RAND_CTX *ctx);
 int EVP_RAND_get_state(EVP_RAND_CTX *ctx);
 #define EVP_RAND_STATE_UNINITIALISED    0
 #define EVP_RAND_STATE_READY            1
 #define EVP_RAND_STATE_ERROR            2

DESCRIPTION¶

The EVP RAND routines are a high-level interface to random number generators both deterministic and not. If you just want to generate random bytes then you don't need to use these functions: just call RAND_bytes() or RAND_priv_bytes(). If you want to do more, these calls should be used instead of the older RAND and RAND_DRBG functions.

After creating a EVP_RAND_CTX for the required algorithm using EVP_RAND_CTX_new(), inputs to the algorithm are supplied either by passing them as part of the EVP_RAND_instantiate() call or using calls to EVP_RAND_CTX_set_params() before calling EVP_RAND_instantiate(). Finally, call EVP_RAND_generate() to produce cryptographically secure random bytes.

PARAMETERS¶

The standard parameter names are:

"state" (OSSL_RAND_PARAM_STATE) <integer>

Returns the state of the random number generator.

"strength" (OSSL_RAND_PARAM_STRENGTH) <unsigned integer>

Returns the bit strength of the random number generator.

"fips-indicator" (OSSL_RAND_PARAM_FIPS_APPROVED_INDICATOR) <integer>

A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. This option is used by the OpenSSL FIPS provider and is not supported by all EVP_RAND sources.

For rands that are also deterministic random bit generators (DRBGs), these additional parameters are recognised. Not all parameters are relevant to, or are understood by all DRBG rands:

"reseed_requests" (OSSL_DRBG_PARAM_RESEED_REQUESTS) <unsigned integer>

Reads or set the number of generate requests before reseeding the associated RAND ctx.

"reseed_time_interval" (OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL) <integer>

Reads or set the number of elapsed seconds before reseeding the associated RAND ctx.

"max_request" (OSSL_RAND_PARAM_MAX_REQUEST) <unsigned integer>

Specifies the maximum number of bytes that can be generated in a single call to OSSL_FUNC_rand_generate.

"min_entropylen" (OSSL_DRBG_PARAM_MIN_ENTROPYLEN) <unsigned integer>

"max_entropylen" (OSSL_DRBG_PARAM_MAX_ENTROPYLEN) <unsigned integer>

Specify the minimum and maximum number of bytes of random material that can be used to seed the DRBG.

"min_noncelen" (OSSL_DRBG_PARAM_MIN_NONCELEN) <unsigned integer>

"max_noncelen" (OSSL_DRBG_PARAM_MAX_NONCELEN) <unsigned integer>

Specify the minimum and maximum number of bytes of nonce that can be used to seed the DRBG.

"max_perslen" (OSSL_DRBG_PARAM_MAX_PERSLEN) <unsigned integer>

"max_adinlen" (OSSL_DRBG_PARAM_MAX_ADINLEN) <unsigned integer>

Specify the minimum and maximum number of bytes of personalisation string that can be used with the DRBG.

"reseed_counter" (OSSL_DRBG_PARAM_RESEED_COUNTER) <unsigned integer>

Specifies the number of times the DRBG has been seeded or reseeded.

"properties" (OSSL_RAND_PARAM_PROPERTIES) <UTF8 string>

"mac" (OSSL_RAND_PARAM_MAC) <UTF8 string>

"digest" (OSSL_RAND_PARAM_DIGEST) <UTF8 string>

"cipher" (OSSL_RAND_PARAM_CIPHER) <UTF8 string>

For RAND implementations that use an underlying computation MAC, digest or cipher, these parameters set what the algorithm should be.

The value is always the name of the intended algorithm, or the properties in the case of OSSL_RAND_PARAM_PROPERTIES.

NOTES¶

The use of a nonzero value for the prediction_resistance argument to EVP_RAND_instantiate(), EVP_RAND_generate() or EVP_RAND_reseed() should be used sparingly. In the default setup, this will cause all public and private DRBGs to be reseeded on next use. Since, by default, public and private DRBGs are allocated on a per thread basis, this can result in significant overhead for highly multi-threaded applications. For normal use-cases, the default "reseed_requests" and "reseed_time_interval" thresholds ensure sufficient prediction resistance over time and you can reduce those values if you think they are too high. Explicitly requesting prediction resistance is intended for more special use-cases like generating long-term secrets.

An EVP_RAND_CTX needs to have locking enabled if it acts as the parent of more than one child and the children can be accessed concurrently. This must be done by explicitly calling EVP_RAND_enable_locking().

The RAND life-cycle is described in life_cycle-rand(7). In the future, the transitions described there will be enforced. When this is done, it will not be considered a breaking change to the API.

RETURN VALUES¶

EVP_RAND_fetch() returns a pointer to a newly fetched EVP_RAND, or NULL if allocation failed.

EVP_RAND_get0_provider() returns a pointer to the provider for the RAND, or NULL on error.

EVP_RAND_CTX_get0_rand() returns a pointer to the EVP_RAND associated with the context.

EVP_RAND_get0_name() returns the name of the random number generation algorithm.

EVP_RAND_up_ref() returns 1 on success, 0 on error.

EVP_RAND_names_do_all() returns 1 if the callback was called for all names. A return value of 0 means that the callback was not called for any names.

EVP_RAND_CTX_new() returns either the newly allocated EVP_RAND_CTX structure or NULL if an error occurred.

EVP_RAND_CTX_free() does not return a value.

EVP_RAND_CTX_up_ref() returns 1 on success, 0 on error.

EVP_RAND_nonce() returns the length of the nonce.

EVP_RAND_get_strength() returns the strength of the random number generator in bits.

EVP_RAND_gettable_params(), EVP_RAND_gettable_ctx_params() and EVP_RAND_settable_ctx_params() return an array of OSSL_PARAMs.

EVP_RAND_verify_zeroization() returns 1 if the internal DRBG state is currently zeroed, and 0 if not.

The remaining functions return 1 for success and 0 or a negative value for failure.

SEE ALSO¶

RAND_bytes(3), EVP_RAND-CTR-DRBG(7), EVP_RAND-HASH-DRBG(7), EVP_RAND-HMAC-DRBG(7), EVP_RAND-TEST-RAND(7), provider-rand(7), life_cycle-rand(7)

HISTORY¶

EVP_RAND_CTX_up_ref() was added in OpenSSL 3.1.

The remaining functions were added in OpenSSL 3.0.

COPYRIGHT¶

Copyright 2020-2024 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.