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 .\" %%%LICENSE_START(VERBATIM)
   7 .\" Permission is granted to make and distribute verbatim copies of this
   8 .\" manual provided the copyright notice and this permission notice are
   9 .\" preserved on all copies.
  10 .\"
  11 .\" Permission is granted to copy and distribute modified versions of
  12 .\" this manual under the conditions for verbatim copying, provided that
  13 .\" the entire resulting derived work is distributed under the terms of
  14 .\" a permission notice identical to this one.
  15 .\"
  16 .\" Since the Linux kernel and libraries are constantly changing, this
  17 .\" manual page may be incorrect or out-of-date.  The author(s) assume.
  18 .\" no responsibility for errors or omissions, or for damages resulting.
  19 .\" from the use of the information contained herein.  The author(s) may.
  20 .\" not have taken the same level of care in the production of this.
  21 .\" manual, which is licensed free of charge, as they might when working.
  22 .\" professionally.
  23 .\"
  24 .\" Formatted or processed versions of this manual, if unaccompanied by
  25 .\" the source, must acknowledge the copyright and authors of this work.
  26 .\" %%%LICENSE_END
  27 .\"
  28 .TH RANDOM 7 2016-11-11 "Linux" "Linux Programmer's Manual"
  29 .SH NAME
  30 random \- overview of interfaces for obtaining randomness
  31 .SH DESCRIPTION
  32 The kernel provides the following interfaces to the kernel's
  33 cryptographically secure pseudorandom number generator (CSPRNG):
  34 .IP * 3
  35 The
  36 .I /dev/urandom
  37 and
  38 .I /dev/random
  39 devices, both described in
  40 .BR random (4).
  41 These devices have been present on Linux since early times.
  42 .IP *
  43 The
  44 .BR getrandom (2)
  45 system call, available since Linux 3.17.
  46 This system call provides access either to the same source as
  47 .I /dev/urandom
  48 (called the
  49 .I urandom
  50 source in this page)
  51 or to the same source as
  52 .I /dev/random
  53 (called the
  54 .I random
  55 source in this page).
  56 The default is the
  57 .I urandom
  58 source; the
  59 .I random
  60 source is selected by specifying the
  61 .BR GRND_RANDOM
  62 flag to the system call.
  63 .\"
  64 .SS Initialization of the entropy pool
  65 The kernel collects bits of entropy from the environment.
  66 When a sufficient number of random bits has been collected, the
  67 .I urandom
  68 entropy pool is considered to be initialized.
  69 .SS Choice of random device
  70 Unless you are doing long-term key generation (and most likely not even
  71 then), you probably shouldn't be using
  72 .BR getrandom (2)
  73 with the
  74 .BR GRND_RANDOM
  75 flag or the
  76 .IR /dev/random
  77 device.
  78
  79 Instead, use either
  80 .BR getrandom (2)
  81 without the
  82 .B GRND_RANDOM
  83 flag or the
  84 .IR /dev/urandom
  85 device.
  86 The cryptographic algorithms used for the
  87 .IR urandom
  88 source are quite conservative, and so should be sufficient for all purposes.
  89
  90 The disadvantage of
  91 .B GRND_RANDOM
  92 and reads from
  93 .I /dev/random
  94 is that the operation can block.
  95 Furthermore, dealing with the partially fulfilled
  96 requests that can occur when using
  97 .B GRND_RANDOM
  98 or when reading from
  99 .I /dev/random
 100 increases code complexity.
 101 .\"
 102 .SS Usage recommendations
 103 The kernel random-number generator
 104 relies on entropy gathered from device drivers and other sources of
 105 environmental noise.
 106 It is designed to produce a small
 107 amount of high-quality seed material to seed a
 108 cryptographically secure pseudorandom number generator (CSPRNG).
 109 It is designed for security, not speed, and is poorly
 110 suited to generating large amounts of cryptographic random data.
 111 Users should be economical in the amount of seed
 112 material that they consume via
 113 .BR getrandom (2),
 114 .IR /dev/urandom ,
 115 and
 116 .IR /dev/random .
 117 .\" FIXME Is it really necessary to avoid consuming large amounts
 118 .\" from /dev/urandom? Various sources linked to by
 119 .\" https://bugzilla.kernel.org/show_bug.cgi?id=71211 suggest it is not.
 120 Consuming unnecessarily large quantities of data via these interfaces
 121 will have a negative impact on other consumers of randomness.
 122
 123 These interfaces should not be used to provide large quantities
 124 of data for Monte Carlo simulations or other
 125 programs/algorithms which are doing probabilistic sampling.
 126 Indeed, such usage is unnecessary (and will be slow).
 127 Instead, use these interfaces to provide a small amount of
 128 data used to seed a user-space pseudorandom number generator
 129 for use by such applications.
 130 .\"
 131 .SS Comparison between getrandom, /dev/urandom, and /dev/random
 132 The following table summarizes the behavior of the various
 133 interfaces that can be used to obtain randomness.
 134 .B GRND_NONBLOCK
 135 is a flag that can be used to control the blocking behavior of
 136 .BR getrandom (2).
 137 .ad l
 138 .TS
 139 allbox;
 140 lbw13 lbw12 lbw16 lbw18
 141 l l l l.
 142 Interface       Pool    T{
 143 Blocking
 144 \%behavior
 145 T}      T{
 146 Behavior in early boot time
 147 T}
 148 T{
 149 .I /dev/random
 150 T}      T{
 151 Blocking pool
 152 T}      T{
 153 If entropy too low, block until there is enough entropy again
 154 T}      T{
 155 Blocks until enough entropy gathered
 156 T}
 157 T{
 158 .I /dev/urandom
 159 T}      T{
 160 CSPRNG output
 161 T}      T{
 162 Never blocks
 163 T}      T{
 164 Returns output from uninitialized CSPRNG (may be low entropy and unsuitable for cryptography)
 165 T}
 166 T{
 167 .BR getrandom ()
 168 T}      T{
 169 Same as
 170 .I /dev/urandom
 171 T}      T{
 172 Does not block once pool ready
 173 T}      T{
 174 Blocks until pool ready
 175 T}
 176 T{
 177 .BR getrandom ()
 178 .B GRND_RANDOM
 179 T}      T{
 180 Same as
 181 .I /dev/random
 182 T}      T{
 183 If entropy too low, block until there is enough entropy again
 184 T}      T{
 185 Blocks until pool ready
 186 T}
 187 T{
 188 .BR getrandom ()
 189 .B GRND_NONBLOCK
 190 T}      T{
 191 Same as
 192 .I /dev/urandom
 193 T}      T{
 194 Does not block
 195 T}      T{
 196 .B EAGAIN
 197 if pool not ready
 198 T}
 199 T{
 200 .BR getrandom ()
 201 .B GRND_RANDOM
 202 +
 203 .B GRND_NONBLOCK
 204 T}      T{
 205 Same as
 206 .I /dev/random
 207 T}      T{
 208 .B EAGAIN
 209 if not enough entropy available
 210 T}      T{
 211 .B EAGAIN
 212 if pool not ready
 213 T}
 214 .TE
 215 .ad
 216 .\"
 217 .SS Generating cryptographic keys
 218 The amount of seed material required to generate a cryptographic key
 219 equals the effective key size of the key.
 220 For example, a 3072-bit RSA
 221 or Diffie-Hellman private key has an effective key size of 128 bits
 222 (it requires about 2^128 operations to break) so a key generator
 223 needs only 128 bits (16 bytes) of seed material from
 224 .IR /dev/random .
 225
 226 While some safety margin above that minimum is reasonable, as a guard
 227 against flaws in the CSPRNG algorithm, no cryptographic primitive
 228 available today can hope to promise more than 256 bits of security,
 229 so if any program reads more than 256 bits (32 bytes) from the kernel
 230 random pool per invocation, or per reasonable reseed interval (not less
 231 than one minute), that should be taken as a sign that its cryptography is
 232 .I not
 233 skillfully implemented.
 234 .\"
 235 .SH SEE ALSO
 236 .BR getrandom (2),
 237 .BR random (4),
 238 .BR urandom (4),
 239 .BR signal (7)