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