EVP_RAND(7ossl)

📦 version 3.5.0, in opensuse-leap 16.0

💜 EVP_RAND — the random bit generator (OpenSSL, section 7ossl)

okay so bestie, buckle up, because this is the page about how OpenSSL actually makes randomness happen under the hood. it's EVP_RAND, it's from the OpenSSL manual (7ossl), and it's genuinely iconic once you get past the acronym soup. 🎀

✨ SYNOPSIS ✨

#include <openssl/evp.h>
#include <rand.h>

that's it. that's the whole vibe check. two includes and you're in. 💅

🌸 DESCRIPTION 🌸

so the default OpenSSL RAND method is built on top of the EVP_RAND classes, and its whole job is to feed non-deterministic inputs into all the other cryptographic algorithms. like, it's the plug. everything else is running on its supply. 🔥

here's the tea though — there are two layers and you gotta know which one's which:

  • The RAND API is the 'frontend' — that's the one intended to be used by application developers for obtaining random bytes. that's your lane, bestie.
  • The EVP_RAND API is the 'backend' — it connects the frontend with the operating system's entropy sources, and it gives you access to deterministic random bit generators (DRBG) and all their configuration parameters.

and a DRBG? that's a certain type of cryptographically-secure pseudo-random number generator (CSPRNG), and it's described in [NIST SP 800-90A Rev. 1]. so yeah. very official. very serious. very much not vibes-based. 👑

🙈 Disclaimer 🙈

okay real talk: unless you have very specific requirements for your random generator, it is in general not necessary to utilize the EVP_RAND API directly. like, at all. put it down. 🫶

the usual way to obtain random bytes is to use RAND_bytes(3) or RAND_priv_bytes(3) — and see also RAND(7). that's the path of least resistance and honestly? it slays.

🦋 Typical Use Cases 🦋

so when would you actually touch this? the typical examples for these special use cases are:

  • You want to use your own private DRBG instances. multiple DRBG instances that are accessed only by a single thread give you additional security (because their internal states are independent, no cap) and better scalability in multithreaded applications (because they don't need to be locked). independent states = main character energy for each thread. ✨
  • You need to integrate a previously unsupported entropy source. refer to provider-rand(7) for the implementation details on supporting adding randomness sources to EVP_RAND. 🧚
  • You need to change the default settings of the standard OpenSSL RAND implementation to meet specific requirements. customisation era. 💅

🔗 EVP_RAND CHAINING 🔗

bestie. you can chain these things. an EVP_RAND instance can be used as the entropy source of another EVP_RAND instance — provided it has itself access to a valid entropy source. so it's giving family tree. 🌈

the terminology, because of course there's terminology:

  • the EVP_RAND instance which acts as the entropy source is called the parent
  • the other instance is the child

and typically, the child will be a DRBG — because it does not make sense for the child to be an entropy source. the child has a job and that job is generating. 😌

this whole arrangement is called chaining. a chained EVP_RAND instance is created by passing a pointer to the parent EVP_RAND_CTX as an argument to the EVP_RAND_CTX_new() call. and yes, you can create chains of more than two DRBG in a row. it's a whole lineup. 🔥

it's also possible to use any EVP_RAND_CTX class as the parent — however, only a live entropy source may ignore and not use its parent. everyone else has to respect the chain. periodt.

👑 THE THREE SHARED DRBG INSTANCES 👑

so currently there are three shared DRBG instances, and they have names that are literally in angle brackets:

  • <primary>
  • <public>
  • <private>

the <primary> DRBG is a single global instance. meanwhile <public> and <private> are created per thread and accessed through thread-local storage. so they're like, one per thread, living their best local life. 🎀

by default, the functions RAND_bytes(3) and RAND_priv_bytes(3) use the thread-local <public> and <private> DRBG instance, respectively. each to their own. 💖

⭐ The <primary> DRBG instance

the <primary> DRBG is not used directly by the application — it exists only for reseeding the other two DRBG instances. it reseeds itself by obtaining randomness either from os entropy sources or by consuming randomness which was added previously by RAND_add(3). so it's the parent who feeds everyone and also feeds itself. iconic behaviour tbh. 🫶

⭐ The <public> DRBG instance

this instance is used per default by RAND_bytes(3). that's it. that's its whole arc. ✨

⭐ The <private> DRBG instance

this instance is used per default by RAND_priv_bytes(3). private by name, private by nature. 🦋

🔒 LOCKING 🔒

okay this part matters, so pay attention bestie:

the <primary> DRBG is intended to be accessed concurrently for reseeding by its child DRBG instances, and the necessary locking is done internally. so it handles its own business. 💅

but — and this is the important but — it is not thread-safe to access the <primary> DRBG directly via the EVP_RAND interface. do not do that. 💀

the <public> and <private> DRBG are thread-local, i.e. there is an instance of each per thread. so they can safely be accessed without locking via the EVP_RAND interface. slay. ✅

pointers to these DRBG instances can be obtained using:

  • RAND_get0_primary()
  • RAND_get0_public()
  • RAND_get0_private()

respectively. 🎀

🚨 note that it is not allowed to store a pointer to one of the thread-local DRBG instances in a variable or other memory location where it will be accessed and used by multiple threads. like, don't do that. that's a whole bug waiting to happen and not the cute kind. 😭

all other DRBG instances created by an application don't support locking, because they are intended to be used by a single thread. so instead of accessing a single DRBG instance concurrently from different threads, the recommendation is to instantiate a separate DRBG instance per thread. one per thread, everyone gets their own, no fighting. 🧚

using the <primary> DRBG as entropy source for multiple DRBG instances on different threads is thread-safe, because the DRBG instance will lock the <primary> DRBG automatically for obtaining random input. it handles the queue for you. genuinely so polite. ✨

🖼️ THE OVERALL PICTURE 🖼️

the following picture gives an overview over how the DRBG instances work together and are being used. it's a diagram, it's ASCII, it's art:

                  +--------------------+
                  | os entropy sources |
                  +--------------------+
                           |
                           v           +-----------------------------+
        RAND_add() ==> <primary>     <-| shared DRBG (with locking)  |
                         /   \         +-----------------------------+
                        /     \              +---------------------------+
                 <public>     <private>   <- | per-thread DRBG instances |
                    |             |          +---------------------------+
                    v             v
                  RAND_bytes()   RAND_priv_bytes()
                       |               ^
                       |               |
       +------------------+      +------------------------------------+
       | general purpose  |      | used for secrets like session keys |
       | random generator |      | and private keys for certificates  |
       +------------------+      +------------------------------------+

so the usual way to obtain random bytes is to call RAND_bytes(...) or RAND_priv_bytes(...). and those calls are roughly equivalent to calling EVP_RAND_generate(<public>, ...) and EVP_RAND_generate(<private>, ...), respectively. same energy, different spelling. 💖

🌸 (more coming in part 2, bestie — go drink some water) 🌸

🌱 RESEEDING 🌱

okay so a DRBG instance seeds itself automatically, pulling random input from its entropy source. That entropy source can be either a trusted operating system entropy source, or another DRBG with access to such a source. iconic little self-feeding situation 💖

Automatic reseeding happens after a predefined number of generate requests. The selection of the trusted entropy sources is configured at build time using the --with-rand-seed option. The following sections explain the reseeding process in more detail.

🔁 Automatic Reseeding

Before satisfying a generate request (EVP_RAND_generate(3)), the DRBG reseeds itself automatically if one of the following conditions holds:

  • the DRBG was not instantiated (=seeded) yet or has been uninstantiated.
  • the number of generate requests since the last reseeding exceeds a certain threshold, the so called reseed_interval. This behaviour can be disabled by setting the reseed_interval to 0.
  • the time elapsed since the last reseeding exceeds a certain time interval, the so called reseed_time_interval. This can be disabled by setting the reseed_time_interval to 0.
  • the DRBG is in an error state.
Note: An error state is entered if the entropy source fails while the DRBG is seeding or reseeding. The last case ensures that the DRBG automatically recovers from the error as soon as the entropy source is available again. resilient queen behavior ✨

✋ Manual Reseeding

In addition to automatic reseeding, the caller can request an immediate reseeding of the DRBG with fresh entropy by setting the prediction resistance parameter to 1 when calling EVP_RAND_generate(3).

The document [NIST SP 800-90C] describes prediction resistance requests in detail and imposes strict conditions on the entropy sources that are approved for providing prediction resistance. A request for prediction resistance can only be satisfied by pulling fresh entropy from a live entropy source (section 5.5.2 of [NIST SP 800-90C]). It is up to the user to ensure that a live entropy source is configured and is being used.

For the three shared DRBGs (and only for these) there is another way to reseed them manually: if RAND_add(3) is called with a positive randomness argument (or RAND_seed(3)), then this will immediately reseed the <primary> DRBG. The <public> and <private> DRBG will detect this on their next generate call and reseed, pulling randomness from <primary>.

The last feature has been added to support the common practice used with previous OpenSSL versions to call RAND_add() before calling RAND_bytes().

🎲 Entropy Input and Additional Data

The DRBG distinguishes two different types of random input: entropy, which comes from a trusted source, and additional input, which can optionally be added by the user and is considered untrusted. It is possible to add additional input not only during reseeding, but also for every generate request. two flavors of randomness, one trusted one not, iykyk 🦋

⚙️ Configuring the Random Seed Source

In most cases OpenSSL will automatically choose a suitable seed source for automatically seeding and reseeding its <primary> DRBG. The default seed source can be configured when OpenSSL is compiled by setting -DOPENSSL_DEFAULT_SEED_SRC=SEED-SRC. If not set then "SEED-SRC" is used. One can specify a third-party provider seed-source, or -DOPENSSL_DEFAULT_SEED_SRC=JITTER if available.

In some cases however, it will be necessary to explicitly specify a seed source used by "SEED-SRC" during configuration, using the --with-rand-seed option. For more information, see the INSTALL instructions. There are also operating systems where no seed source is available and automatic reseeding is disabled by default.

The following two sections describe the reseeding process of the primary DRBG, depending on whether automatic reseeding is available or not.

🌈 Reseeding the primary DRBG with automatic seeding enabled

Calling RAND_poll() or RAND_add() is not necessary, because the DRBG pulls the necessary entropy from its source automatically. However, both calls are permitted, and do reseed the RNG.

RAND_add() can be used to add both kinds of random input, depending on the value of the randomness argument:

randomness == 0

The random bytes are mixed as additional input into the current state of the DRBG. Mixing in additional input is not considered a full reseeding, hence the reseed counter is not reset.

randomness > 0

The random bytes are used as entropy input for a full reseeding (resp. reinstantiation) if the DRBG is instantiated (resp. uninstantiated or in an error state). The number of random bits required for reseeding is determined by the security strength of the DRBG. Currently it defaults to 256 bits (32 bytes). It is possible to provide less randomness than required. In this case the missing randomness will be obtained by pulling random input from the trusted entropy sources.

NOTE: Manual reseeding is not allowed in FIPS mode, because [NIST SP-800-90Ar1] mandates that entropy shall not be provided by the consuming application for instantiation (Section 9.1) or reseeding (Section 9.2). For that reason, the randomness argument is ignored and the random bytes provided by the RAND_add(3) and RAND_seed(3) calls are treated as additional data. FIPS said no manual seeding, periodt 💅

🚨 Reseeding the primary DRBG with automatic seeding disabled

Calling RAND_poll() will always fail.

RAND_add() needs to be called for initial seeding and periodic reseeding. At least 48 bytes (384 bits) of randomness have to be provided, otherwise the (re-)seeding of the DRBG will fail. This corresponds to one and a half times the security strength of the DRBG. The extra half is used for the nonce during instantiation.

More precisely, the number of bytes needed for seeding depend on the security strength of the DRBG, which is set to 256 by default. bestie you gotta feed it enough bytes, no cap 🍓

👀 SEE ALSO

🕰️ HISTORY

This functionality was added in OpenSSL 3.0.

Copyright 2017-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>.

okay bestie that’s the whole page 💖 source is EVP_RAND(7ossl), version 3.5.0, dated 2026-09-25. go forth and reseed responsibly 🫶✨💅

📦 where this page comes from