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