1=pod 2 3=head1 NAME 4 5EVP_RAND - the random bit generator 6 7=head1 SYNOPSIS 8 9 #include <openssl/evp.h> 10 #include <rand.h> 11 12=head1 DESCRIPTION 13 14The default OpenSSL RAND method is based on the EVP_RAND classes to provide 15non-deterministic inputs to other cryptographic algorithms. 16 17While the RAND API is the 'frontend' which is intended to be used by 18application developers for obtaining random bytes, the EVP_RAND API 19serves as the 'backend', connecting the former with the operating 20systems's entropy sources and providing access to deterministic random 21bit generators (DRBG) and their configuration parameters. 22A DRBG is a certain type of cryptographically-secure pseudo-random 23number generator (CSPRNG), which is described in 24[NIST SP 800-90A Rev. 1]. 25 26=head2 Disclaimer 27 28Unless you have very specific requirements for your random generator, 29it is in general not necessary to utilize the EVP_RAND API directly. 30The usual way to obtain random bytes is to use L<RAND_bytes(3)> or 31L<RAND_priv_bytes(3)>, see also L<RAND(7)>. 32 33=head2 Typical Use Cases 34 35Typical examples for such special use cases are the following: 36 37=over 2 38 39=item * 40 41You want to use your own private DRBG instances. 42Multiple DRBG instances which are accessed only by a single thread provide 43additional security (because their internal states are independent) and 44better scalability in multithreaded applications (because they don't need 45to be locked). 46 47=item * 48 49You need to integrate a previously unsupported entropy source. 50Refer to L<provider-rand(7)> for the implementation details to support adding 51randomness sources to EVP_RAND. 52 53=item * 54 55You need to change the default settings of the standard OpenSSL RAND 56implementation to meet specific requirements. 57 58=back 59 60 61=head1 EVP_RAND CHAINING 62 63An EVP_RAND instance can be used as the entropy source of another 64EVP_RAND instance, provided it has itself access to a valid entropy source. 65The EVP_RAND instance which acts as entropy source is called the I<parent>, 66the other instance the I<child>. Typically, the child will be a DRBG because 67it does not make sense for the child to be an entropy source. 68 69This is called chaining. A chained EVP_RAND instance is created by passing 70a pointer to the parent EVP_RAND_CTX as argument to the EVP_RAND_CTX_new() call. 71It is possible to create chains of more than two DRBG in a row. 72It is also possible to use any EVP_RAND_CTX class as the parent, however, only 73a live entropy source may ignore and not use its parent. 74 75=head1 THE THREE SHARED DRBG INSTANCES 76 77Currently, there are three shared DRBG instances, 78the <primary>, <public>, and <private> DRBG. 79While the <primary> DRBG is a single global instance, the <public> and <private> 80DRBG are created per thread and accessed through thread-local storage. 81 82By default, the functions L<RAND_bytes(3)> and L<RAND_priv_bytes(3)> use 83the thread-local <public> and <private> DRBG instance, respectively. 84 85=head2 The <primary> DRBG instance 86 87The <primary> DRBG is not used directly by the application, only for reseeding 88the two other two DRBG instances. It reseeds itself by obtaining randomness 89either from os entropy sources or by consuming randomness which was added 90previously by L<RAND_add(3)>. 91 92=head2 The <public> DRBG instance 93 94This instance is used per default by L<RAND_bytes(3)>. 95 96=head2 The <private> DRBG instance 97 98This instance is used per default by L<RAND_priv_bytes(3)> 99 100 101=head1 LOCKING 102 103The <primary> DRBG is intended to be accessed concurrently for reseeding 104by its child DRBG instances. The necessary locking is done internally. 105It is I<not> thread-safe to access the <primary> DRBG directly via the 106EVP_RAND interface. 107The <public> and <private> DRBG are thread-local, i.e. there is an 108instance of each per thread. So they can safely be accessed without 109locking via the EVP_RAND interface. 110 111Pointers to these DRBG instances can be obtained using 112RAND_get0_primary(), RAND_get0_public() and RAND_get0_private(), respectively. 113Note that it is not allowed to store a pointer to one of the thread-local 114DRBG instances in a variable or other memory location where it will be 115accessed and used by multiple threads. 116 117All other DRBG instances created by an application don't support locking, 118because they are intended to be used by a single thread. 119Instead of accessing a single DRBG instance concurrently from different 120threads, it is recommended to instantiate a separate DRBG instance per 121thread. Using the <primary> DRBG as entropy source for multiple DRBG 122instances on different threads is thread-safe, because the DRBG instance 123will lock the <primary> DRBG automatically for obtaining random input. 124 125=head1 THE OVERALL PICTURE 126 127The following picture gives an overview over how the DRBG instances work 128together and are being used. 129 130 +--------------------+ 131 | os entropy sources | 132 +--------------------+ 133 | 134 v +-----------------------------+ 135 RAND_add() ==> <primary> <-| shared DRBG (with locking) | 136 / \ +-----------------------------+ 137 / \ +---------------------------+ 138 <public> <private> <- | per-thread DRBG instances | 139 | | +---------------------------+ 140 v v 141 RAND_bytes() RAND_priv_bytes() 142 | ^ 143 | | 144 +------------------+ +------------------------------------+ 145 | general purpose | | used for secrets like session keys | 146 | random generator | | and private keys for certificates | 147 +------------------+ +------------------------------------+ 148 149 150The usual way to obtain random bytes is to call RAND_bytes(...) or 151RAND_priv_bytes(...). These calls are roughly equivalent to calling 152EVP_RAND_generate(<public>, ...) and 153EVP_RAND_generate(<private>, ...), 154respectively. 155 156=head1 RESEEDING 157 158A DRBG instance seeds itself automatically, pulling random input from 159its entropy source. The entropy source can be either a trusted operating 160system entropy source, or another DRBG with access to such a source. 161 162Automatic reseeding occurs after a predefined number of generate requests. 163The selection of the trusted entropy sources is configured at build 164time using the --with-rand-seed option. The following sections explain 165the reseeding process in more detail. 166 167=head2 Automatic Reseeding 168 169Before satisfying a generate request (L<EVP_RAND_generate(3)>), the DRBG 170reseeds itself automatically, if one of the following conditions holds: 171 172- the DRBG was not instantiated (=seeded) yet or has been uninstantiated. 173 174- the number of generate requests since the last reseeding exceeds a 175certain threshold, the so called I<reseed_interval>. 176This behaviour can be disabled by setting the I<reseed_interval> to 0. 177 178- the time elapsed since the last reseeding exceeds a certain time 179interval, the so called I<reseed_time_interval>. 180This can be disabled by setting the I<reseed_time_interval> to 0. 181 182- the DRBG is in an error state. 183 184B<Note>: An error state is entered if the entropy source fails while 185the DRBG is seeding or reseeding. 186The last case ensures that the DRBG automatically recovers 187from the error as soon as the entropy source is available again. 188 189=head2 Manual Reseeding 190 191In addition to automatic reseeding, the caller can request an immediate 192reseeding of the DRBG with fresh entropy by setting the 193I<prediction resistance> parameter to 1 when calling 194L<EVP_RAND_generate(3)>. 195 196The document [NIST SP 800-90C] describes prediction resistance requests 197in detail and imposes strict conditions on the entropy sources that are 198approved for providing prediction resistance. 199A request for prediction resistance can only be satisfied by pulling fresh 200entropy from a live entropy source (section 5.5.2 of [NIST SP 800-90C]). 201It is up to the user to ensure that a live entropy source is configured 202and is being used. 203 204For the three shared DRBGs (and only for these) there is another way to 205reseed them manually: 206If L<RAND_add(3)> is called with a positive I<randomness> argument 207(or L<RAND_seed(3)>), then this will immediately reseed the <primary> DRBG. 208The <public> and <private> DRBG will detect this on their next generate 209call and reseed, pulling randomness from <primary>. 210 211The last feature has been added to support the common practice used with 212previous OpenSSL versions to call RAND_add() before calling RAND_bytes(). 213 214 215=head2 Entropy Input and Additional Data 216 217The DRBG distinguishes two different types of random input: I<entropy>, 218which comes from a trusted source, and I<additional input>', 219which can optionally be added by the user and is considered untrusted. 220It is possible to add I<additional input> not only during reseeding, 221but also for every generate request. 222 223 224=head2 Configuring the Random Seed Source 225 226In most cases OpenSSL will automatically choose a suitable seed source 227for automatically seeding and reseeding its <primary> DRBG. The 228default seed source can be configured when OpenSSL is compiled by 229setting B<-DOPENSSL_DEFAULT_SEED_SRC=SEED-SRC>. If not set then 230"SEED-SRC" is used. One can specify a third-party provider seed-source, 231or B<-DOPENSSL_DEFAULT_SEED_SRC=JITTER> if available. 232 233In some cases however, it will be necessary to explicitly specify a 234seed source used by "SEED-SRC" during configuration, using the 235--with-rand-seed option. For more information, see the INSTALL 236instructions. There are also operating systems where no seed source is 237available and automatic reseeding is disabled by default. 238 239The following two sections describe the reseeding process of the primary 240DRBG, depending on whether automatic reseeding is available or not. 241 242 243=head2 Reseeding the primary DRBG with automatic seeding enabled 244 245Calling RAND_poll() or RAND_add() is not necessary, because the DRBG 246pulls the necessary entropy from its source automatically. 247However, both calls are permitted, and do reseed the RNG. 248 249RAND_add() can be used to add both kinds of random input, depending on the 250value of the I<randomness> argument: 251 252=over 4 253 254=item randomness == 0: 255 256The random bytes are mixed as additional input into the current state of 257the DRBG. 258Mixing in additional input is not considered a full reseeding, hence the 259reseed counter is not reset. 260 261 262=item randomness > 0: 263 264The random bytes are used as entropy input for a full reseeding 265(resp. reinstantiation) if the DRBG is instantiated 266(resp. uninstantiated or in an error state). 267The number of random bits required for reseeding is determined by the 268security strength of the DRBG. Currently it defaults to 256 bits (32 bytes). 269It is possible to provide less randomness than required. 270In this case the missing randomness will be obtained by pulling random input 271from the trusted entropy sources. 272 273=back 274 275NOTE: Manual reseeding is *not allowed* in FIPS mode, because 276[NIST SP-800-90Ar1] mandates that entropy *shall not* be provided by 277the consuming application for instantiation (Section 9.1) or 278reseeding (Section 9.2). For that reason, the I<randomness> 279argument is ignored and the random bytes provided by the L<RAND_add(3)> and 280L<RAND_seed(3)> calls are treated as additional data. 281 282=head2 Reseeding the primary DRBG with automatic seeding disabled 283 284Calling RAND_poll() will always fail. 285 286RAND_add() needs to be called for initial seeding and periodic reseeding. 287At least 48 bytes (384 bits) of randomness have to be provided, otherwise 288the (re-)seeding of the DRBG will fail. This corresponds to one and a half 289times the security strength of the DRBG. The extra half is used for the 290nonce during instantiation. 291 292More precisely, the number of bytes needed for seeding depend on the 293I<security strength> of the DRBG, which is set to 256 by default. 294 295=head1 SEE ALSO 296 297L<RAND(7)>, L<EVP_RAND(3)> 298 299=head1 HISTORY 300 301This functionality was added in OpenSSL 3.0. 302 303=head1 COPYRIGHT 304 305Copyright 2017-2024 The OpenSSL Project Authors. All Rights Reserved. 306 307Licensed under the Apache License 2.0 (the "License"). You may not use 308this file except in compliance with the License. You can obtain a copy 309in the file LICENSE in the source distribution or at 310L<https://www.openssl.org/source/license.html>. 311 312=cut 313
