man7/random.7

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