{ "mode": "man", "parameter": "EVP_RAND", "section": "7ssl", "url": "https://www.chedong.com/phpMan.php/man/EVP_RAND/7ssl/json", "generated": "2026-06-15T13:13:00Z", "synopsis": "#include \n#include ", "sections": { "NAME": { "content": "EVPRAND - the random bit generator\n", "subsections": [] }, "SYNOPSIS": { "content": "#include \n#include \n", "subsections": [] }, "DESCRIPTION": { "content": "The default OpenSSL RAND method is based on the EVPRAND classes to provide non-deterministic\ninputs to other cryptographic algorithms.\n\nWhile the RAND API is the 'frontend' which is intended to be used by application developers\nfor obtaining random bytes, the EVPRAND API serves as the 'backend', connecting the former\nwith the operating systems's entropy sources and providing access to deterministic random bit\ngenerators (DRBG) and their configuration parameters. A DRBG is a certain type of\ncryptographically-secure pseudo-random number generator (CSPRNG), which is described in [NIST\nSP 800-90A Rev. 1].\n", "subsections": [ { "name": "Disclaimer", "content": "Unless you have very specific requirements for your random generator, it is in general not\nnecessary to utilize the EVPRAND API directly. The usual way to obtain random bytes is to\nuse RANDbytes(3) or RANDprivbytes(3), see also RAND(7).\n" }, { "name": "Typical Use Cases", "content": "Typical examples for such special use cases are the following:\n\n• You want to use your own private DRBG instances. Multiple DRBG instances which are\naccessed only by a single thread provide additional security (because their internal states\nare independent) and better scalability in multithreaded applications (because they don't\nneed to be locked).\n\n• You need to integrate a previously unsupported entropy source. Refer to provider-rand(7)\nfor the implementation details to support adding randomness sources to EVPRAND.\n\n• You need to change the default settings of the standard OpenSSL RAND implementation to meet\nspecific requirements.\n" } ] }, "EVPRAND CHAINING": { "content": "An EVPRAND instance can be used as the entropy source of another EVPRAND instance, provided\nit has itself access to a valid entropy source. The EVPRAND instance which acts as entropy\nsource is called the parent, the other instance the child. Typically, the child will be a\nDRBG because it does not make sense for the child to be an entropy source.\n\nThis is called chaining. A chained EVPRAND instance is created by passing a pointer to the\nparent EVPRANDCTX as argument to the EVPRANDCTXnew() call. It is possible to create\nchains of more than two DRBG in a row. It is also possible to use any EVPRANDCTX class as\nthe parent, however, only a live entropy source may ignore and not use its parent.\n", "subsections": [] }, "THE THREE SHARED DRBG INSTANCES": { "content": "Currently, there are three shared DRBG instances, the , , and \nDRBG. While the DRBG is a single global instance, the and DRBG\nare created per thread and accessed through thread-local storage.\n\nBy default, the functions RANDbytes(3) and RANDprivbytes(3) use the thread-local \nand DRBG instance, respectively.\n", "subsections": [ { "name": "The DRBG instance", "content": "The DRBG is not used directly by the application, only for reseeding the two other\ntwo DRBG instances. It reseeds itself by obtaining randomness either from os entropy sources\nor by consuming randomness which was added previously by RANDadd(3).\n" }, { "name": "The DRBG instance", "content": "This instance is used per default by RANDbytes(3).\n" }, { "name": "The DRBG instance", "content": "This instance is used per default by RANDprivbytes(3)\n" } ] }, "LOCKING": { "content": "The DRBG is intended to be accessed concurrently for reseeding by its child DRBG\ninstances. The necessary locking is done internally. It is not thread-safe to access the\n DRBG directly via the EVPRAND interface. The and DRBG are\nthread-local, i.e. there is an instance of each per thread. So they can safely be accessed\nwithout locking via the EVPRAND interface.\n\nPointers to these DRBG instances can be obtained using RANDget0primary(),\nRANDget0public() and RANDget0private(), respectively. Note that it is not allowed to\nstore a pointer to one of the thread-local DRBG instances in a variable or other memory\nlocation where it will be accessed and used by multiple threads.\n\nAll other DRBG instances created by an application don't support locking, because they are\nintended to be used by a single thread. Instead of accessing a single DRBG instance\nconcurrently from different threads, it is recommended to instantiate a separate DRBG\ninstance per thread. Using the DRBG as entropy source for multiple DRBG instances\non different threads is thread-safe, because the DRBG instance will lock the DRBG\nautomatically for obtaining random input.\n", "subsections": [] }, "THE OVERALL PICTURE": { "content": "The following picture gives an overview over how the DRBG instances work together and are\nbeing used.\n\n+--------------------+\n| os entropy sources |\n+--------------------+\n|\nv +-----------------------------+\nRANDadd() ==> <-| shared DRBG (with locking) |\n/ \\ +-----------------------------+\n/ \\ +---------------------------+\n <- | per-thread DRBG instances |\n| | +---------------------------+\nv v\nRANDbytes() RANDprivbytes()\n| ^\n| |\n+------------------+ +------------------------------------+\n| general purpose | | used for secrets like session keys |\n| random generator | | and private keys for certificates |\n+------------------+ +------------------------------------+\n\nThe usual way to obtain random bytes is to call RANDbytes(...) or RANDprivbytes(...).\nThese calls are roughly equivalent to calling EVPRANDgenerate(, ...) and\nEVPRANDgenerate(, ...), respectively.\n", "subsections": [] }, "RESEEDING": { "content": "A DRBG instance seeds itself automatically, pulling random input from its entropy source. The\nentropy source can be either a trusted operating system entropy source, or another DRBG with\naccess to such a source.\n\nAutomatic reseeding occurs after a predefined number of generate requests. The selection of\nthe trusted entropy sources is configured at build time using the --with-rand-seed option.\nThe following sections explain the reseeding process in more detail.\n", "subsections": [ { "name": "Automatic Reseeding", "content": "Before satisfying a generate request (EVPRANDgenerate(3)), the DRBG reseeds itself\nautomatically, if one of the following conditions holds:\n\n- the DRBG was not instantiated (=seeded) yet or has been uninstantiated.\n\n- the number of generate requests since the last reseeding exceeds a certain threshold, the\nso called reseedinterval. This behaviour can be disabled by setting the reseedinterval to\n0.\n\n- the time elapsed since the last reseeding exceeds a certain time interval, the so called\nreseedtimeinterval. This can be disabled by setting the reseedtimeinterval to 0.\n\n- the DRBG is in an error state.\n\nNote: An error state is entered if the entropy source fails while the DRBG is seeding or\nreseeding. The last case ensures that the DRBG automatically recovers from the error as soon\nas the entropy source is available again.\n" }, { "name": "Manual Reseeding", "content": "In addition to automatic reseeding, the caller can request an immediate reseeding of the DRBG\nwith fresh entropy by setting the prediction resistance parameter to 1 when calling\nEVPRANDgenerate(3).\n\nThe document [NIST SP 800-90C] describes prediction resistance requests in detail and imposes\nstrict conditions on the entropy sources that are approved for providing prediction\nresistance. A request for prediction resistance can only be satisfied by pulling fresh\nentropy from a live entropy source (section 5.5.2 of [NIST SP 800-90C]). It is up to the\nuser to ensure that a live entropy source is configured and is being used.\n\nFor the three shared DRBGs (and only for these) there is another way to reseed them manually:\nIf RANDadd(3) is called with a positive randomness argument (or RANDseed(3)), then this\nwill immediately reseed the DRBG. The and DRBG will detect this\non their next generate call and reseed, pulling randomness from .\n\nThe last feature has been added to support the common practice used with previous OpenSSL\nversions to call RANDadd() before calling RANDbytes().\n" }, { "name": "Entropy Input and Additional Data", "content": "The DRBG distinguishes two different types of random input: entropy, which comes from a\ntrusted source, and additional input', which can optionally be added by the user and is\nconsidered untrusted. It is possible to add additional input not only during reseeding, but\nalso for every generate request.\n" }, { "name": "Configuring the Random Seed Source", "content": "In most cases OpenSSL will automatically choose a suitable seed source for automatically\nseeding and reseeding its DRBG. In some cases however, it will be necessary to\nexplicitly specify a seed source during configuration, using the --with-rand-seed option. For\nmore information, see the INSTALL instructions. There are also operating systems where no\nseed source is available and automatic reseeding is disabled by default.\n\nThe following two sections describe the reseeding process of the primary DRBG, depending on\nwhether automatic reseeding is available or not.\n" }, { "name": "Reseeding the primary DRBG with automatic seeding enabled", "content": "Calling RANDpoll() or RANDadd() is not necessary, because the DRBG pulls the necessary\nentropy from its source automatically. However, both calls are permitted, and do reseed the\nRNG.\n\nRANDadd() can be used to add both kinds of random input, depending on the value of the\nrandomness argument:\n\nrandomness == 0:\nThe random bytes are mixed as additional input into the current state of the DRBG.\nMixing in additional input is not considered a full reseeding, hence the reseed counter\nis not reset.\n\nrandomness > 0:\nThe random bytes are used as entropy input for a full reseeding (resp. reinstantiation)\nif the DRBG is instantiated (resp. uninstantiated or in an error state). The number of\nrandom bits required for reseeding is determined by the security strength of the DRBG.\nCurrently it defaults to 256 bits (32 bytes). It is possible to provide less randomness\nthan required. In this case the missing randomness will be obtained by pulling random\ninput from the trusted entropy sources.\n\nNOTE: Manual reseeding is *not allowed* in FIPS mode, because [NIST SP-800-90Ar1] mandates\nthat entropy *shall not* be provided by the consuming application for instantiation (Section\n9.1) or reseeding (Section 9.2). For that reason, the randomness argument is ignored and the\nrandom bytes provided by the RANDadd(3) and RANDseed(3) calls are treated as additional\ndata.\n" }, { "name": "Reseeding the primary DRBG with automatic seeding disabled", "content": "Calling RANDpoll() will always fail.\n\nRANDadd() needs to be called for initial seeding and periodic reseeding. At least 48 bytes\n(384 bits) of randomness have to be provided, otherwise the (re-)seeding of the DRBG will\nfail. This corresponds to one and a half times the security strength of the DRBG. The extra\nhalf is used for the nonce during instantiation.\n\nMore precisely, the number of bytes needed for seeding depend on the security strength of the\nDRBG, which is set to 256 by default.\n" } ] }, "SEE ALSO": { "content": "RAND(7), EVPRAND(3)\n", "subsections": [] }, "HISTORY": { "content": "This functionality was added in OpenSSL 3.0.\n", "subsections": [] }, "COPYRIGHT": { "content": "Copyright 2017-2020 The OpenSSL Project Authors. All Rights Reserved.\n\nLicensed under the Apache License 2.0 (the \"License\"). You may not use this file except in\ncompliance with the License. You can obtain a copy in the file LICENSE in the source\ndistribution or at .\n\n\n\n3.0.2 2026-06-02 EVPRAND(7SSL)", "subsections": [] } }, "summary": "EVPRAND - the random bit generator", "flags": [], "examples": [], "see_also": [ { "name": "RAND", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/RAND/7/json" }, { "name": "EVPRAND", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/EVPRAND/3/json" } ] }