doc/man7/RAND_DRBG.pod

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