secure/lib/libcrypto/man/man7/RAND_DRBG.7

   1 .\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.40)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{\
  60 .    if \nF \{\
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{\
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "RAND_DRBG 7"
 136 .TH RAND_DRBG 7 "2020-03-17" "1.1.1e" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 RAND_DRBG \- the deterministic random bit generator
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/rand_drbg.h>
 147 .Ve
 148 .SH "DESCRIPTION"
 149 .IX Header "DESCRIPTION"
 150 The default OpenSSL \s-1RAND\s0 method is based on the \s-1RAND_DRBG\s0 class,
 151 which implements a deterministic random bit generator (\s-1DRBG\s0).
 152 A \s-1DRBG\s0 is a certain type of cryptographically-secure pseudo-random
 153 number generator (\s-1CSPRNG\s0), which is described in
 154 [\s-1NIST SP 800\-90A\s0 Rev. 1].
 155 .PP
 156 While the \s-1RAND API\s0 is the 'frontend' which is intended to be used by
 157 application developers for obtaining random bytes, the \s-1RAND_DRBG API\s0
 158 serves as the 'backend', connecting the former with the operating
 159 systems's entropy sources and providing access to the \s-1DRBG\s0's
 160 configuration parameters.
 161 .SS "Disclaimer"
 162 .IX Subsection "Disclaimer"
 163 Unless you have very specific requirements for your random generator,
 164 it is in general not necessary to utilize the \s-1RAND_DRBG API\s0 directly.
 165 The usual way to obtain random bytes is to use \fBRAND_bytes\fR\|(3) or
 166 \&\fBRAND_priv_bytes\fR\|(3), see also \s-1\fBRAND\s0\fR\|(7).
 167 .SS "Typical Use Cases"
 168 .IX Subsection "Typical Use Cases"
 169 Typical examples for such special use cases are the following:
 170 .IP "\(bu" 2
 171 You want to use your own private \s-1DRBG\s0 instances.
 172 Multiple \s-1DRBG\s0 instances which are accessed only by a single thread provide
 173 additional security (because their internal states are independent) and
 174 better scalability in multithreaded applications (because they don't need
 175 to be locked).
 176 .IP "\(bu" 2
 177 You need to integrate a previously unsupported entropy source.
 178 .IP "\(bu" 2
 179 You need to change the default settings of the standard OpenSSL \s-1RAND\s0
 180 implementation to meet specific requirements.
 181 .SH "CHAINING"
 182 .IX Header "CHAINING"
 183 A \s-1DRBG\s0 instance can be used as the entropy source of another \s-1DRBG\s0 instance,
 184 provided it has itself access to a valid entropy source.
 185 The \s-1DRBG\s0 instance which acts as entropy source is called the \fIparent\fR \s-1DRBG,\s0
 186 the other instance the \fIchild\fR \s-1DRBG.\s0
 187 .PP
 188 This is called chaining. A chained \s-1DRBG\s0 instance is created by passing
 189 a pointer to the parent \s-1DRBG\s0 as argument to the \fBRAND_DRBG_new()\fR call.
 190 It is possible to create chains of more than two \s-1DRBG\s0 in a row.
 191 .SH "THE THREE SHARED DRBG INSTANCES"
 192 .IX Header "THE THREE SHARED DRBG INSTANCES"
 193 Currently, there are three shared \s-1DRBG\s0 instances,
 194 the <master>, <public>, and <private> \s-1DRBG.\s0
 195 While the <master> \s-1DRBG\s0 is a single global instance, the <public> and <private>
 196 \&\s-1DRBG\s0 are created per thread and accessed through thread-local storage.
 197 .PP
 198 By default, the functions \fBRAND_bytes\fR\|(3) and \fBRAND_priv_bytes\fR\|(3) use
 199 the thread-local <public> and <private> \s-1DRBG\s0 instance, respectively.
 200 .SS "The <master> \s-1DRBG\s0 instance"
 201 .IX Subsection "The <master> DRBG instance"
 202 The <master> \s-1DRBG\s0 is not used directly by the application, only for reseeding
 203 the two other two \s-1DRBG\s0 instances. It reseeds itself by obtaining randomness
 204 either from os entropy sources or by consuming randomness which was added
 205 previously by \fBRAND_add\fR\|(3).
 206 .SS "The <public> \s-1DRBG\s0 instance"
 207 .IX Subsection "The <public> DRBG instance"
 208 This instance is used per default by \fBRAND_bytes\fR\|(3).
 209 .SS "The <private> \s-1DRBG\s0 instance"
 210 .IX Subsection "The <private> DRBG instance"
 211 This instance is used per default by \fBRAND_priv_bytes\fR\|(3)
 212 .SH "LOCKING"
 213 .IX Header "LOCKING"
 214 The <master> \s-1DRBG\s0 is intended to be accessed concurrently for reseeding
 215 by its child \s-1DRBG\s0 instances. The necessary locking is done internally.
 216 It is \fInot\fR thread-safe to access the <master> \s-1DRBG\s0 directly via the
 217 \&\s-1RAND_DRBG\s0 interface.
 218 The <public> and <private> \s-1DRBG\s0 are thread-local, i.e. there is an
 219 instance of each per thread. So they can safely be accessed without
 220 locking via the \s-1RAND_DRBG\s0 interface.
 221 .PP
 222 Pointers to these \s-1DRBG\s0 instances can be obtained using
 223 \&\fBRAND_DRBG_get0_master()\fR,
 224 \&\fBRAND_DRBG_get0_public()\fR, and
 225 \&\fBRAND_DRBG_get0_private()\fR, respectively.
 226 Note that it is not allowed to store a pointer to one of the thread-local
 227 \&\s-1DRBG\s0 instances in a variable or other memory location where it will be
 228 accessed and used by multiple threads.
 229 .PP
 230 All other \s-1DRBG\s0 instances created by an application don't support locking,
 231 because they are intended to be used by a single thread.
 232 Instead of accessing a single \s-1DRBG\s0 instance concurrently from different
 233 threads, it is recommended to instantiate a separate \s-1DRBG\s0 instance per
 234 thread. Using the <master> \s-1DRBG\s0 as entropy source for multiple \s-1DRBG\s0
 235 instances on different threads is thread-safe, because the \s-1DRBG\s0 instance
 236 will lock the <master> \s-1DRBG\s0 automatically for obtaining random input.
 237 .SH "THE OVERALL PICTURE"
 238 .IX Header "THE OVERALL PICTURE"
 239 The following picture gives an overview over how the \s-1DRBG\s0 instances work
 240 together and are being used.
 241 .PP
 242 .Vb 10
 243 \&               +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
 244 \&               | os entropy sources |
 245 \&               +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
 246 \&                        |
 247 \&                        v           +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
 248 \&      RAND_add() ==> <master>     <\-| shared DRBG (with locking)  |
 249 \&                      /   \e         +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
 250 \&                     /     \e              +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
 251 \&              <public>     <private>   <\- | per\-thread DRBG instances |
 252 \&                 |             |          +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
 253 \&                 v             v
 254 \&               RAND_bytes()   RAND_priv_bytes()
 255 \&                    |               ^
 256 \&                    |               |
 257 \&    +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+      +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
 258 \&    | general purpose  |      | used for secrets like session keys |
 259 \&    | random generator |      | and private keys for certificates  |
 260 \&    +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+      +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
 261 .Ve
 262 .PP
 263 The usual way to obtain random bytes is to call RAND_bytes(...) or
 264 RAND_priv_bytes(...). These calls are roughly equivalent to calling
 265 RAND_DRBG_bytes(<public>, ...) and RAND_DRBG_bytes(<private>, ...),
 266 respectively. The method \fBRAND_DRBG_bytes\fR\|(3) is a convenience method
 267 wrapping the \fBRAND_DRBG_generate\fR\|(3) function, which serves the actual
 268 request for random data.
 269 .SH "RESEEDING"
 270 .IX Header "RESEEDING"
 271 A \s-1DRBG\s0 instance seeds itself automatically, pulling random input from
 272 its entropy source. The entropy source can be either a trusted operating
 273 system entropy source, or another \s-1DRBG\s0 with access to such a source.
 274 .PP
 275 Automatic reseeding occurs after a predefined number of generate requests.
 276 The selection of the trusted entropy sources is configured at build
 277 time using the \-\-with\-rand\-seed option. The following sections explain
 278 the reseeding process in more detail.
 279 .SS "Automatic Reseeding"
 280 .IX Subsection "Automatic Reseeding"
 281 Before satisfying a generate request (\fBRAND_DRBG_generate\fR\|(3)), the \s-1DRBG\s0
 282 reseeds itself automatically, if one of the following conditions holds:
 283 .PP
 284 \&\- the \s-1DRBG\s0 was not instantiated (=seeded) yet or has been uninstantiated.
 285 .PP
 286 \&\- the number of generate requests since the last reseeding exceeds a
 287 certain threshold, the so called \fIreseed_interval\fR.
 288 This behaviour can be disabled by setting the \fIreseed_interval\fR to 0.
 289 .PP
 290 \&\- the time elapsed since the last reseeding exceeds a certain time
 291 interval, the so called \fIreseed_time_interval\fR.
 292 This can be disabled by setting the \fIreseed_time_interval\fR to 0.
 293 .PP
 294 \&\- the \s-1DRBG\s0 is in an error state.
 295 .PP
 296 \&\fBNote\fR: An error state is entered if the entropy source fails while
 297 the \s-1DRBG\s0 is seeding or reseeding.
 298 The last case ensures that the \s-1DRBG\s0 automatically recovers
 299 from the error as soon as the entropy source is available again.
 300 .SS "Manual Reseeding"
 301 .IX Subsection "Manual Reseeding"
 302 In addition to automatic reseeding, the caller can request an immediate
 303 reseeding of the \s-1DRBG\s0 with fresh entropy by setting the
 304 \&\fIprediction resistance\fR parameter to 1 when calling \fBRAND_DRBG_generate\fR\|(3).
 305 .PP
 306 The document [\s-1NIST SP 800\-90C\s0] describes prediction resistance requests
 307 in detail and imposes strict conditions on the entropy sources that are
 308 approved for providing prediction resistance.
 309 Since the default \s-1DRBG\s0 implementation does not have access to such an approved
 310 entropy source, a request for prediction resistance will currently always fail.
 311 In other words, prediction resistance is currently not supported yet by the \s-1DRBG.\s0
 312 .PP
 313 For the three shared DRBGs (and only for these) there is another way to
 314 reseed them manually:
 315 If \fBRAND_add\fR\|(3) is called with a positive \fIrandomness\fR argument
 316 (or \fBRAND_seed\fR\|(3)), then this will immediately reseed the <master> \s-1DRBG.\s0
 317 The <public> and <private> \s-1DRBG\s0 will detect this on their next generate
 318 call and reseed, pulling randomness from <master>.
 319 .PP
 320 The last feature has been added to support the common practice used with
 321 previous OpenSSL versions to call \fBRAND_add()\fR before calling \fBRAND_bytes()\fR.
 322 .SS "Entropy Input vs. Additional Data"
 323 .IX Subsection "Entropy Input vs. Additional Data"
 324 The \s-1DRBG\s0 distinguishes two different types of random input: \fIentropy\fR,
 325 which comes from a trusted source, and \fIadditional input\fR',
 326 which can optionally be added by the user and is considered untrusted.
 327 It is possible to add \fIadditional input\fR not only during reseeding,
 328 but also for every generate request.
 329 This is in fact done automatically by \fBRAND_DRBG_bytes\fR\|(3).
 330 .SS "Configuring the Random Seed Source"
 331 .IX Subsection "Configuring the Random Seed Source"
 332 In most cases OpenSSL will automatically choose a suitable seed source
 333 for automatically seeding and reseeding its <master> \s-1DRBG.\s0 In some cases
 334 however, it will be necessary to explicitly specify a seed source during
 335 configuration, using the \-\-with\-rand\-seed option. For more information,
 336 see the \s-1INSTALL\s0 instructions. There are also operating systems where no
 337 seed source is available and automatic reseeding is disabled by default.
 338 .PP
 339 The following two sections describe the reseeding process of the master
 340 \&\s-1DRBG,\s0 depending on whether automatic reseeding is available or not.
 341 .SS "Reseeding the master \s-1DRBG\s0 with automatic seeding enabled"
 342 .IX Subsection "Reseeding the master DRBG with automatic seeding enabled"
 343 Calling \fBRAND_poll()\fR or \fBRAND_add()\fR is not necessary, because the \s-1DRBG\s0
 344 pulls the necessary entropy from its source automatically.
 345 However, both calls are permitted, and do reseed the \s-1RNG.\s0
 346 .PP
 347 \&\fBRAND_add()\fR can be used to add both kinds of random input, depending on the
 348 value of the \fBrandomness\fR argument:
 349 .IP "randomness == 0:" 4
 350 .IX Item "randomness == 0:"
 351 The random bytes are mixed as additional input into the current state of
 352 the \s-1DRBG.\s0
 353 Mixing in additional input is not considered a full reseeding, hence the
 354 reseed counter is not reset.
 355 .IP "randomness > 0:" 4
 356 .IX Item "randomness > 0:"
 357 The random bytes are used as entropy input for a full reseeding
 358 (resp. reinstantiation) if the \s-1DRBG\s0 is instantiated
 359 (resp. uninstantiated or in an error state).
 360 The number of random bits required for reseeding is determined by the
 361 security strength of the \s-1DRBG.\s0 Currently it defaults to 256 bits (32 bytes).
 362 It is possible to provide less randomness than required.
 363 In this case the missing randomness will be obtained by pulling random input
 364 from the trusted entropy sources.
 365 .SS "Reseeding the master \s-1DRBG\s0 with automatic seeding disabled"
 366 .IX Subsection "Reseeding the master DRBG with automatic seeding disabled"
 367 Calling \fBRAND_poll()\fR will always fail.
 368 .PP
 369 \&\fBRAND_add()\fR needs to be called for initial seeding and periodic reseeding.
 370 At least 48 bytes (384 bits) of randomness have to be provided, otherwise
 371 the (re\-)seeding of the \s-1DRBG\s0 will fail. This corresponds to one and a half
 372 times the security strength of the \s-1DRBG.\s0 The extra half is used for the
 373 nonce during instantiation.
 374 .PP
 375 More precisely, the number of bytes needed for seeding depend on the
 376 \&\fIsecurity strength\fR of the \s-1DRBG,\s0 which is set to 256 by default.
 377 .SH "SEE ALSO"
 378 .IX Header "SEE ALSO"
 379 \&\fBRAND_DRBG_bytes\fR\|(3),
 380 \&\fBRAND_DRBG_generate\fR\|(3),
 381 \&\fBRAND_DRBG_reseed\fR\|(3),
 382 \&\fBRAND_DRBG_get0_master\fR\|(3),
 383 \&\fBRAND_DRBG_get0_public\fR\|(3),
 384 \&\fBRAND_DRBG_get0_private\fR\|(3),
 385 \&\fBRAND_DRBG_set_reseed_interval\fR\|(3),
 386 \&\fBRAND_DRBG_set_reseed_time_interval\fR\|(3),
 387 \&\fBRAND_DRBG_set_reseed_defaults\fR\|(3),
 388 \&\s-1\fBRAND\s0\fR\|(7),
 389 .SH "COPYRIGHT"
 390 .IX Header "COPYRIGHT"
 391 Copyright 2017\-2018 The OpenSSL Project Authors. All Rights Reserved.
 392 .PP
 393 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 394 this file except in compliance with the License.  You can obtain a copy
 395 in the file \s-1LICENSE\s0 in the source distribution or at
 396 <https://www.openssl.org/source/license.html>.