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