secure/lib/libcrypto/man/man7/RAND.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 7"
 136 .TH RAND 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 \&\- the OpenSSL random generator
 143 .SH "DESCRIPTION"
 144 .IX Header "DESCRIPTION"
 145 Random numbers are a vital part of cryptography, they are needed to provide
 146 unpredictability for tasks like key generation, creating salts, and many more.
 147 Software-based generators must be seeded with external randomness before they
 148 can be used as a cryptographically-secure pseudo-random number generator
 149 (\s-1CSPRNG\s0).
 150 The availability of common hardware with special instructions and
 151 modern operating systems, which may use items such as interrupt jitter
 152 and network packet timings, can be reasonable sources of seeding material.
 153 .PP
 154 OpenSSL comes with a default implementation of the \s-1RAND API\s0 which is based on
 155 the deterministic random bit generator (\s-1DRBG\s0) model as described in
 156 [\s-1NIST SP 800\-90A\s0 Rev. 1]. The default random generator will initialize
 157 automatically on first use and will be fully functional without having
 158 to be initialized ('seeded') explicitly.
 159 It seeds and reseeds itself automatically using trusted random sources
 160 provided by the operating system.
 161 .PP
 162 As a normal application developer, you do not have to worry about any details,
 163 just use \fBRAND_bytes\fR\|(3) to obtain random data.
 164 Having said that, there is one important rule to obey: Always check the error
 165 return value of \fBRAND_bytes\fR\|(3) and do not take randomness for granted.
 166 Although (re\-)seeding is automatic, it can fail because no trusted random source
 167 is available or the trusted source(s) temporarily fail to provide sufficient
 168 random seed material.
 169 In this case the \s-1CSPRNG\s0 enters an error state and ceases to provide output,
 170 until it is able to recover from the error by reseeding itself.
 171 For more details on reseeding and error recovery, see \s-1\fBRAND_DRBG\s0\fR\|(7).
 172 .PP
 173 For values that should remain secret, you can use \fBRAND_priv_bytes\fR\|(3)
 174 instead.
 175 This method does not provide 'better' randomness, it uses the same type of \s-1CSPRNG.\s0
 176 The intention behind using a dedicated \s-1CSPRNG\s0 exclusively for private
 177 values is that none of its output should be visible to an attacker (e.g.,
 178 used as salt value), in order to reveal as little information as
 179 possible about its internal state, and that a compromise of the \*(L"public\*(R"
 180 \&\s-1CSPRNG\s0 instance will not affect the secrecy of these private values.
 181 .PP
 182 In the rare case where the default implementation does not satisfy your special
 183 requirements, there are two options:
 184 .IP "\(bu" 2
 185 Replace the default \s-1RAND\s0 method by your own \s-1RAND\s0 method using
 186 \&\fBRAND_set_rand_method\fR\|(3).
 187 .IP "\(bu" 2
 188 Modify the default settings of the OpenSSL \s-1RAND\s0 method by modifying the security
 189 parameters of the underlying \s-1DRBG,\s0 which is described in detail in \s-1\fBRAND_DRBG\s0\fR\|(7).
 190 .PP
 191 Changing the default random generator or its default parameters should be necessary
 192 only in exceptional cases and is not recommended, unless you have a profound knowledge
 193 of cryptographic principles and understand the implications of your changes.
 194 .SH "SEE ALSO"
 195 .IX Header "SEE ALSO"
 196 \&\fBRAND_add\fR\|(3),
 197 \&\fBRAND_bytes\fR\|(3),
 198 \&\fBRAND_priv_bytes\fR\|(3),
 199 \&\fBRAND_get_rand_method\fR\|(3),
 200 \&\fBRAND_set_rand_method\fR\|(3),
 201 \&\fBRAND_OpenSSL\fR\|(3),
 202 \&\s-1\fBRAND_DRBG\s0\fR\|(7)
 203 .SH "COPYRIGHT"
 204 .IX Header "COPYRIGHT"
 205 Copyright 2018\-2019 The OpenSSL Project Authors. All Rights Reserved.
 206 .PP
 207 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 208 this file except in compliance with the License.  You can obtain a copy
 209 in the file \s-1LICENSE\s0 in the source distribution or at
 210 <https://www.openssl.org/source/license.html>.