doc/man7/EVP_RAND.pod

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