man7/random.7

   1 '\" t
   2 .\" Copyright (C) 2008, George Spelvin <linux@horizon.com>,
   3 .\" and Copyright (C) 2008, Matt Mackall <mpm@selenic.com>
   4 .\" and Copyright (C) 2016, Laurent Georget <laurent.georget@supelec.fr>
   5 .\" and Copyright (C) 2016, Nikos Mavrogiannopoulos <nmav@redhat.com>
   6 .\"
   7 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   8 .\"
   9 .\" The following web page is quite informative:
  10 .\" http://www.2uo.de/myths-about-urandom/
  11 .\"
  12 .TH random 7 (date) "Linux man-pages (unreleased)"
  13 .SH NAME
  14 random \- overview of interfaces for obtaining randomness
  15 .SH DESCRIPTION
  16 The kernel random-number generator relies on entropy gathered from
  17 device drivers and other sources of environmental noise to seed
  18 a cryptographically secure pseudorandom number generator (CSPRNG).
  19 It is designed for security, rather than speed.
  20 .PP
  21 The following interfaces provide access to output from the kernel CSPRNG:
  22 .IP \[bu] 3
  23 The
  24 .I /dev/urandom
  25 and
  26 .I /dev/random
  27 devices, both described in
  28 .BR random (4).
  29 These devices have been present on Linux since early times,
  30 and are also available on many other systems.
  31 .IP \[bu]
  32 The Linux-specific
  33 .BR getrandom (2)
  34 system call, available since Linux 3.17.
  35 This system call provides access either to the same source as
  36 .I /dev/urandom
  37 (called the
  38 .I urandom
  39 source in this page)
  40 or to the same source as
  41 .I /dev/random
  42 (called the
  43 .I random
  44 source in this page).
  45 The default is the
  46 .I urandom
  47 source; the
  48 .I random
  49 source is selected by specifying the
  50 .B GRND_RANDOM
  51 flag to the system call.
  52 (The
  53 .BR getentropy (3)
  54 function provides a slightly more portable interface on top of
  55 .BR getrandom (2).)
  56 .\"
  57 .SS Initialization of the entropy pool
  58 The kernel collects bits of entropy from the environment.
  59 When a sufficient number of random bits has been collected, the
  60 entropy pool is considered to be initialized.
  61 .SS Choice of random source
  62 Unless you are doing long-term key generation (and most likely not even
  63 then), you probably shouldn't be reading from the
  64 .I /dev/random
  65 device or employing
  66 .BR getrandom (2)
  67 with the
  68 .B GRND_RANDOM
  69 flag.
  70 Instead, either read from the
  71 .I /dev/urandom
  72 device or employ
  73 .BR getrandom (2)
  74 without the
  75 .B GRND_RANDOM
  76 flag.
  77 The cryptographic algorithms used for the
  78 .I urandom
  79 source are quite conservative, and so should be sufficient for all purposes.
  80 .PP
  81 The disadvantage of
  82 .B GRND_RANDOM
  83 and reads from
  84 .I /dev/random
  85 is that the operation can block for an indefinite period of time.
  86 Furthermore, dealing with the partially fulfilled
  87 requests that can occur when using
  88 .B GRND_RANDOM
  89 or when reading from
  90 .I /dev/random
  91 increases code complexity.
  92 .\"
  93 .SS Monte Carlo and other probabilistic sampling applications
  94 Using these interfaces to provide large quantities of data for
  95 Monte Carlo simulations or other programs/algorithms which are
  96 doing probabilistic sampling will be slow.
  97 Furthermore, it is unnecessary, because such applications do not
  98 need cryptographically secure random numbers.
  99 Instead, use the interfaces described in this page to obtain
 100 a small amount of data to seed a user-space pseudorandom
 101 number generator for use by such applications.
 102 .\"
 103 .SS Comparison between getrandom, /dev/urandom, and /dev/random
 104 The following table summarizes the behavior of the various
 105 interfaces that can be used to obtain randomness.
 106 .B GRND_NONBLOCK
 107 is a flag that can be used to control the blocking behavior of
 108 .BR getrandom (2).
 109 The final column of the table considers the case that can occur
 110 in early boot time when the entropy pool is not yet initialized.
 111 .ad l
 112 .TS
 113 allbox;
 114 lbw13 lbw12 lbw14 lbw18
 115 l l l l.
 116 Interface       Pool    T{
 117 Blocking
 118 \%behavior
 119 T}      T{
 120 Behavior when pool is not yet ready
 121 T}
 122 T{
 123 .I /dev/random
 124 T}      T{
 125 Blocking pool
 126 T}      T{
 127 If entropy too low, blocks until there is enough entropy again
 128 T}      T{
 129 Blocks until enough entropy gathered
 130 T}
 131 T{
 132 .I /dev/urandom
 133 T}      T{
 134 CSPRNG output
 135 T}      T{
 136 Never blocks
 137 T}      T{
 138 Returns output from uninitialized CSPRNG (may be low entropy and unsuitable for cryptography)
 139 T}
 140 T{
 141 .BR getrandom ()
 142 T}      T{
 143 Same as
 144 .I /dev/urandom
 145 T}      T{
 146 Does not block once is pool ready
 147 T}      T{
 148 Blocks until pool ready
 149 T}
 150 T{
 151 .BR getrandom ()
 152 .B GRND_RANDOM
 153 T}      T{
 154 Same as
 155 .I /dev/random
 156 T}      T{
 157 If entropy too low, blocks until there is enough entropy again
 158 T}      T{
 159 Blocks until pool ready
 160 T}
 161 T{
 162 .BR getrandom ()
 163 .B GRND_NONBLOCK
 164 T}      T{
 165 Same as
 166 .I /dev/urandom
 167 T}      T{
 168 Does not block once is pool ready
 169 T}      T{
 170 .B EAGAIN
 171 T}
 172 T{
 173 .BR getrandom ()
 174 .B GRND_RANDOM
 175 +
 176 .B GRND_NONBLOCK
 177 T}      T{
 178 Same as
 179 .I /dev/random
 180 T}      T{
 181 .B EAGAIN
 182 if not enough entropy available
 183 T}      T{
 184 .B EAGAIN
 185 T}
 186 .TE
 187 .ad
 188 .\"
 189 .SS Generating cryptographic keys
 190 The amount of seed material required to generate a cryptographic key
 191 equals the effective key size of the key.
 192 For example, a 3072-bit RSA
 193 or Diffie-Hellman private key has an effective key size of 128 bits
 194 (it requires about 2\[ha]128 operations to break) so a key generator
 195 needs only 128 bits (16 bytes) of seed material from
 196 .IR /dev/random .
 197 .PP
 198 While some safety margin above that minimum is reasonable, as a guard
 199 against flaws in the CSPRNG algorithm, no cryptographic primitive
 200 available today can hope to promise more than 256 bits of security,
 201 so if any program reads more than 256 bits (32 bytes) from the kernel
 202 random pool per invocation, or per reasonable reseed interval (not less
 203 than one minute), that should be taken as a sign that its cryptography is
 204 .I not
 205 skillfully implemented.
 206 .\"
 207 .SH SEE ALSO
 208 .BR getrandom (2),
 209 .BR getauxval (3),
 210 .BR getentropy (3),
 211 .BR random (4),
 212 .BR urandom (4),
 213 .BR signal (7)