RAND_GET0_PRIMARY(3SSL)

📦
version 4.0.3 · 13 versions
, in ubuntu stonking

💖 RAND_get0_primary — the OpenSSL rand girlies 💖

okay bestie, welcome to RAND_GET0_PRIMARY(3SSL), aka the page where we meet the OpenSSL functions that hand you the global EVP_RAND_CTX instances. yes this is a real manual section, no I'm not kidding, and honestly? it's giving backstage pass to the random number generator. 🔥

✨ NAME ✨

RAND_get0_primary, RAND_get0_public, RAND_get0_private, RAND_set0_public, RAND_set0_private — get access to the global EVP_RAND_CTX instances 🦋

✨ SYNOPSIS ✨

#include <openssl/rand.h>

EVP_RAND_CTX *RAND_get0_primary(OSSL_LIB_CTX *ctx);
EVP_RAND_CTX *RAND_get0_public(OSSL_LIB_CTX *ctx);
EVP_RAND_CTX *RAND_get0_private(OSSL_LIB_CTX *ctx);
int RAND_set0_public(OSSL_LIB_CTX *ctx, EVP_RAND_CTX *rand);
int RAND_set0_private(OSSL_LIB_CTX *ctx, EVP_RAND_CTX *rand);

like, that's the whole invite list. five functions. slay. 💅

✨ DESCRIPTION ✨

okay so. the default RAND API implementation, aka RAND_OpenSSL(), runs on three shared DRBG instances, and you reach them all through the RAND API:

  • the public DRBG and the private DRBG are thread-local instances, used by RAND_bytes() and RAND_priv_bytes() respectively.
  • the primary DRBG is a global instance, and here's the tea: it is not intended to be used directly, it's used internally to reseed the other two. it's the backstage crew, not the main character. 🎭

The three get functions give you access to those shared DRBG instances.

The two set functions let you swap the public and private DRBG instances out for another random number generator. glow-up, but make it cryptographic. 👑

✨ RETURN VALUES ✨

  • RAND_get0_primary() — returns a pointer to the primary DRBG instance for the given OSSL_LIB_CTX ctx.
  • RAND_get0_public() — returns a pointer to the public DRBG instance for the given OSSL_LIB_CTX ctx.
  • RAND_get0_private() — returns a pointer to the private DRBG instance for the given OSSL_LIB_CTX ctx.
  • RAND_set0_public() and RAND_set0_private() — return 1 on success and 0 on error. no in-between, no "it's complicated". 💀

✨ NOTES ✨ ✨

⚠️ it is not thread-safe to access the primary DRBG instance. periodt.

the public and private DRBG instances can be accessed safely, because they're thread-local. but note — and this is important bestie — changes to these two instances apply only to the current thread. your thread, your business. 🧚

for that reason, it is recommended not to change the settings of these three instances directly. instead, an application should change the default settings for new DRBG instances at initialization time, before creating additional threads. do it early or don't do it at all, iykyk. 🎀

during initialization, it is possible to change the reseed interval and reseed time interval. it is also possible to exchange the reseeding callbacks entirely. full customization arc. 🌈

to set the type of DRBG that will be instantiated, use the RAND_set_DRBG_type(3) call before accessing the random number generation infrastructure. before. BEFORE. 😭

the two set functions operate on the current thread. so if you want to use the same random number generator across all threads, each thread must individually call the set functions. no shortcuts, every thread does its own thing. 🙈

✨ SEE ALSO ✨

go read those too, you'll be obsessed. 💜

✨ HISTORY ✨

  • RAND_set0_public() and RAND_set0_private() were added in OpenSSL 3.1.
  • the remaining functions were added in OpenSSL 3.0.

so the get girls are older than the set girls. lore. 📜

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

and that's the whole thing, bestie 💖 this was OpenSSL 4.0.3, dated 2026-09-29, and yes it really is called RAND_GET0_PRIMARY(3SSL). mwah. 🫶✨💅

📦 where this page comes from