EVP_RAND(3SSL)

📦
version 4.0.3 · 13 versions
, in ubuntu stonking

💖 NAME 💖

okay bestie, this is the EVP_RAND page from the 3SSL manual (that's OpenSSL's own docs, no cap) and it's a big one so we're doing it in parts. buckle up 🎀

so what even lives here? literally the entire EVP RAND routines family, and it's a lot of names, so let's do a roll call 👑

  • 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

all of those = the EVP RAND routines. yes, every single one, we're not skipping anybody 🙈

✨ SYNOPSIS ✨

the way you summon all of this into your file is giving:

#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

okay so first thing, notice those two typedefs up top, EVP_RAND and EVP_RAND_CTX — they're the two ✨iconic✨ opaque types you'll be passing around forever. EVP_RAND is the algorithm itself, EVP_RAND_CTX is your actual working instance of it. bestie energy: one is the recipe, the other is the cake 🎂

and then boom, three little #defines at the bottom:

  • EVP_RAND_STATE_UNINITIALISED is 0
  • EVP_RAND_STATE_READY is 1
  • EVP_RAND_STATE_ERROR is 2

those are the vibes your RAND context can be in, and EVP_RAND_get_state is literally how you check which one 😭

🌸 to be continued, bestie — the plot thickens next part 🌸

✨ DESCRIPTION ✨

okay bestie, gather round 💖 the EVP RAND routines are a high-level interface to random number generators — both deterministic and not (yes, both flavors are on the menu).

But real talk first: if all you wanna do is generate some random bytes, you do not need any of this. Just call RAND_bytes() or RAND_priv_bytes() and go live your life 🌸. It's only when you want to do more than that, that you reach for these calls — and when you do, use them instead of the older RAND functions. (The old ones are giving expired milk, no cap.)

So here's the whole vibe 🦋 after you create an EVP_RAND_CTX for whatever algorithm you need using EVP_RAND_CTX_new(), you feed inputs to the algorithm one of two ways:

  • by passing them straight in as part of the EVP_RAND_instantiate() call, or
  • by making calls to EVP_RAND_CTX_set_params() before you call EVP_RAND_instantiate().

And then, finally, you call EVP_RAND_generate() to produce cryptographically secure random bytes. slay. 💅

🎀 Types 🎀

  • EVP_RAND — a type that holds the implementation of a RAND.
  • EVP_RAND_CTX — a context type that holds the algorithm inputs. and bestie, EVP_RAND_CTX structures are reference counted. periodt.

💜 Algorithm implementation fetching 💜

  • EVP_RAND_fetch() — fetches you an implementation of a RAND algorithm, given a library context libctx and a set of properties. Wanna know more? Go read "ALGORITHM FETCHING" in crypto(7). iykyk 📚

What you get back must eventually be freed with EVP_RAND_free(3). Don't leave it hanging, that's not cute.

  • EVP_RAND_up_ref() — bumps up the reference count of a RAND you already fetched. 🔥
  • EVP_RAND_free() — frees a fetched algorithm. And pssst: NULL is a totally valid parameter here, and when you pass it, this function is a no-op. Nothing happens. Chill.

🌈 Context manipulation functions 🌈

  • EVP_RAND_CTX_new() — creates a shiny new context for the RAND implementation rand. If it's not NULL, parent specifies the seed source for this implementation. Heads up: not all random number generators need a seed source specified. And if a parent is required but you pass NULL, it'll utilise the operating system entropy sources instead.
okay listen, small PSA 👑 it is recommended to minimise the number of random number generators that rely on the operating system for their randomness, because that stuff is often scarce. Don't be greedy with the OS entropy, bestie.
  • EVP_RAND_CTX_free() — frees up the context ctx. If ctx is NULL, nothing is done. Simple as that. 🫶
  • EVP_RAND_CTX_get0_rand() — returns the EVP_RAND associated with the context ctx.

🔥 Random Number Generator Functions 🔥

  • EVP_RAND_instantiate() — processes any parameters sitting in params, and then instantiates the RAND ctx with a minimum security strength of strength and a personalisation string pstr of length pstr_len. If prediction_resistance is specified, fresh entropy from a live source will be sought. 👀 This call operates as per NIST SP 800-90A and SP 800-90C.
  • EVP_RAND_uninstantiate() — uninstantiates the RAND ctx, as per NIST SP 800-90A and SP 800-90C. After this call, the RAND cannot be used to generate bytes anymore. It can only be freed or instantiated again. It's giving ✨closed for business✨.
  • EVP_RAND_generate() — produces random bytes from the RAND ctx, with the additional input addin of length addin_len. The bytes it produces will meet the security strength. If prediction_resistance is specified, fresh entropy from a live source will be sought. This call operates as per NIST SP 800-90A and SP 800-90C. 💖
  • EVP_RAND_reseed() — reseeds the RAND with new entropy. You can supply entropy ent of length ent_len bytes, and you can also supply additional input addin of length addin_len bytes. In the FIPS provider, both are treated as additional input as per NIST SP-800-90Ar1, Sections 9.1 and 9.2. Additional seed material is also drawn from the RAND's parent or the operating system. And if prediction_resistance is specified, fresh entropy from a live source will be sought. This call operates as per NIST SP 800-90A and SP 800-90C.
  • EVP_RAND_nonce() — creates a nonce in out of length outlen bytes, from the RAND ctx. iconic.
  • EVP_RAND_enable_locking() — enables locking for the RAND ctx and all of its parents. After this, the ctx will operate in a thread safe manner — albeit more slowly. 🐢
⚠️ real talk: this function is not itself thread safe if you call it with the same ctx from multiple threads. Typically you should enable locking before a ctx is shared across multiple threads. do it early, bestie, don't play yourself.
  • EVP_RAND_get_params() — retrieves details about the implementation rand. The set of parameters you give with params determines exactly which parameters get retrieved. And note: a parameter that is unknown in the underlying context is simply ignored. no drama.
  • EVP_RAND_CTX_get_params() — retrieves chosen parameters, given the context ctx and its underlying context. The set of parameters you give with params determines exactly which parameters get retrieved. Same deal: a parameter unknown in the underlying context is simply ignored. 🙈
  • EVP_RAND_CTX_set_params() — passes chosen parameters to the underlying context, given a context ctx. The set of parameters you give with params determines exactly which parameters get passed down. Note that a parameter unknown in the underlying context is simply ignored. And also — what happens when a needed parameter isn't passed down? That's defined by the implementation. so uh, ask your provider. 😭
  • EVP_RAND_gettable_params() — returns an OSSL_PARAM(3) array that describes the retrievable and settable parameters. Specifically, EVP_RAND_gettable_params() returns parameters that can be used with EVP_RAND_get_params().
  • EVP_RAND_gettable_ctx_params() and EVP_RAND_CTX_gettable_params() — return constant OSSL_PARAM(3) arrays that describe the retrievable parameters that can be used with EVP_RAND_CTX_get_params(). EVP_RAND_gettable_ctx_params() returns the parameters that can be retrieved from the algorithm, whereas EVP_RAND_CTX_gettable_params() returns the parameters that can be retrieved in the context's current state. two different vibes, keep them straight bestie 💅
  • EVP_RAND_settable_ctx_params() and EVP_RAND_CTX_settable_params() — return constant OSSL_PARAM(3) arrays that describe the settable parameters that can be used with EVP_RAND_CTX_set_params(). EVP_RAND_settable_ctx_params() returns the parameters that can be retrieved from the algorithm, whereas EVP_RAND_CTX_settable_params() returns the parameters that can be retrieved in the context's current state.

🦋 Information functions 🦋

  • EVP_RAND_get_strength() — returns the security strength of the RAND ctx. 💪
  • EVP_RAND_get_state() — returns the current state of the RAND ctx. The states defined by the OpenSSL RNGs are:
    • EVP_RAND_STATE_UNINITIALISED — this RNG is currently uninitialised. The instantiate call will change this to the ready state.
    • EVP_RAND_STATE_READY — this RNG is currently ready to generate output. 🌟
    • EVP_RAND_STATE_ERROR — this RNG is in an error state. 💀
  • EVP_RAND_is_a() — returns 1 if rand is an implementation of an algorithm that's identifiable with name, otherwise 0.
  • EVP_RAND_get0_provider() — returns the provider that holds the implementation of the given rand.
  • EVP_RAND_do_all_provided() — traverses all RAND implemented by all activated providers in the given library context libctx, and for each of the implementations, calls the given function fn with the implementation method and the given arg as argument. a little tour of the whole neighborhood 🚶‍♀️
  • EVP_RAND_get0_name() — returns the canonical name of rand.
  • EVP_RAND_names_do_all() — traverses all names for rand, and calls fn with each name and data.
  • EVP_RAND_get0_description() — returns a description of the rand, meant for display and human consumption. The description is at the discretion of the rand implementation — so don't @ it, it writes its own bio.
  • EVP_RAND_verify_zeroization() — confirms whether the internal DRBG state is currently zeroed. This is used by the FIPS provider to support the mandatory self tests. ✅

⭐ 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. so don't come for it if your provider doesn't have it 🙈

For rands that are also deterministic random bit generators (DRBGs), these additional parameters are recognised. And heads up: 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> and "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> and "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> and "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>, "digest" (OSSL_RAND_PARAM_DIGEST) <UTF8 string>, and "cipher" (OSSL_RAND_PARAM_CIPHER) <UTF8 string> — For RAND implementations that use an underlying 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 💭

okay bestie, listen up, this part is the "read before you wreck stuff" part 🫶

  • The prediction_resistance argument to EVP_RAND_instantiate(), EVP_RAND_generate() or EVP_RAND_reseed() — when you set it to a nonzero value — is something you should use sparingly. like, not every day. as a lil treat. ✨ In the default setup, this will cause all public and private DRBGs to be reseeded on next use. And since by default public and private DRBGs are allocated on a per thread basis, that can result in significant overhead for highly multi-threaded applications. 😭 so yeah, it's giving expensive.
  • For normal use-cases, the default reseed_requests and reseed_time_interval thresholds already ensure sufficient prediction resistance over time, so you're fine. And if you think they're too high, you can just reduce those values. lowkey customizable, highkey fine. 💅
  • Explicitly requesting prediction resistance is intended for more special use-cases, like generating long-term secrets. that's the moment. that's when you use it. 👑

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. ngl this doesn't just happen by itself — this must be done by explicitly calling EVP_RAND_enable_locking(). no cap, you have to ask for it. 🔒

The RAND life-cycle is described in life_cycle-rand(7). In the future, the transitions described there will be enforced. 🫣 And when this is done, it will not be considered a breaking change to the API. so don't come for the API later, bestie, it told you in advance.

🎀 RETURN VALUES 🎀

here's the vibe check on what everything hands back to you:

  • 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. it just frees and dips. 🦋
  • EVP_RAND_CTX_up_ref() — returns 1 on success, 0 on error.
  • EVP_RAND_nonce() — returns 1 on success, 0 on error.
  • 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. 🙈

And the remaining functions? They return 1 for success and 0 or a negative value for failure. that's the whole rule, fr fr.

👀 SEE ALSO 👀

go read these next, bestie, they're all part of the lore:

🌈 HISTORY 🌈

  • EVP_RAND_CTX_up_ref() was added in OpenSSL 3.1. ✨
  • The remaining functions were added in OpenSSL 3.0.

so yeah, EVP_RAND_CTX_up_ref() is the baby of the family. 🍼

Copyright 2020-2026 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>.

and that's a wrap on EVP_RAND(3SSL), bestie 🎀 this one came from OpenSSL 4.0.3, dated 2026-09-29 — go forth and generate randomness responsibly, ily, bye! 💖✨🦋

📦 where this page comes from