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 2017-03-13 "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 .PP
  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 (The
  72 .BR getentropy (3)
  73 function provides a slightly more portable interface on top of
  74 .BR getrandom (2).)
  75 .\"
  76 .SS Initialization of the entropy pool
  77 The kernel collects bits of entropy from the environment.
  78 When a sufficient number of random bits has been collected, the
  79 entropy pool is considered to be initialized.
  80 .SS Choice of random source
  81 Unless you are doing long-term key generation (and most likely not even
  82 then), you probably shouldn't be reading from the
  83 .IR /dev/random
  84 device or employing
  85 .BR getrandom (2)
  86 with the
  87 .BR GRND_RANDOM
  88 flag.
  89 Instead, either read from the
  90 .IR /dev/urandom
  91 device or employ
  92 .BR getrandom (2)
  93 without the
  94 .B GRND_RANDOM
  95 flag.
  96 The cryptographic algorithms used for the
  97 .IR urandom
  98 source are quite conservative, and so should be sufficient for all purposes.
  99 .PP
 100 The disadvantage of
 101 .B GRND_RANDOM
 102 and reads from
 103 .I /dev/random
 104 is that the operation can block for an indefinite period of time.
 105 Furthermore, dealing with the partially fulfilled
 106 requests that can occur when using
 107 .B GRND_RANDOM
 108 or when reading from
 109 .I /dev/random
 110 increases code complexity.
 111 .\"
 112 .SS Monte Carlo and other probabilistic sampling applications
 113 Using these interfaces to provide large quantities of data for
 114 Monte Carlo simulations or other programs/algorithms which are
 115 doing probabilistic sampling will be slow.
 116 Furthermore, it is unnecessary, because such applications do not
 117 need cryptographically secure random numbers.
 118 Instead, use the interfaces described in this page to obtain
 119 a small amount of data to seed a user-space pseudorandom
 120 number generator for use by such applications.
 121 .\"
 122 .SS Comparison between getrandom, /dev/urandom, and /dev/random
 123 The following table summarizes the behavior of the various
 124 interfaces that can be used to obtain randomness.
 125 .B GRND_NONBLOCK
 126 is a flag that can be used to control the blocking behavior of
 127 .BR getrandom (2).
 128 The final column of the table considers the case that can occur
 129 in early boot time when the entropy pool is not yet initialized.
 130 .ad l
 131 .TS
 132 allbox;
 133 lbw13 lbw12 lbw14 lbw18
 134 l l l l.
 135 Interface       Pool    T{
 136 Blocking
 137 \%behavior
 138 T}      T{
 139 Behavior when pool is not yet ready
 140 T}
 141 T{
 142 .I /dev/random
 143 T}      T{
 144 Blocking pool
 145 T}      T{
 146 If entropy too low, blocks until there is enough entropy again
 147 T}      T{
 148 Blocks until enough entropy gathered
 149 T}
 150 T{
 151 .I /dev/urandom
 152 T}      T{
 153 CSPRNG output
 154 T}      T{
 155 Never blocks
 156 T}      T{
 157 Returns output from uninitialized CSPRNG (may be low entropy and unsuitable for cryptography)
 158 T}
 159 T{
 160 .BR getrandom ()
 161 T}      T{
 162 Same as
 163 .I /dev/urandom
 164 T}      T{
 165 Does not block once is pool ready
 166 T}      T{
 167 Blocks until pool ready
 168 T}
 169 T{
 170 .BR getrandom ()
 171 .B GRND_RANDOM
 172 T}      T{
 173 Same as
 174 .I /dev/random
 175 T}      T{
 176 If entropy too low, blocks until there is enough entropy again
 177 T}      T{
 178 Blocks until pool ready
 179 T}
 180 T{
 181 .BR getrandom ()
 182 .B GRND_NONBLOCK
 183 T}      T{
 184 Same as
 185 .I /dev/urandom
 186 T}      T{
 187 Does not block once is pool ready
 188 T}      T{
 189 .B EAGAIN
 190 T}
 191 T{
 192 .BR getrandom ()
 193 .B GRND_RANDOM
 194 +
 195 .B GRND_NONBLOCK
 196 T}      T{
 197 Same as
 198 .I /dev/random
 199 T}      T{
 200 .B EAGAIN
 201 if not enough entropy available
 202 T}      T{
 203 .B EAGAIN
 204 T}
 205 .TE
 206 .ad
 207 .\"
 208 .SS Generating cryptographic keys
 209 The amount of seed material required to generate a cryptographic key
 210 equals the effective key size of the key.
 211 For example, a 3072-bit RSA
 212 or Diffie-Hellman private key has an effective key size of 128 bits
 213 (it requires about 2^128 operations to break) so a key generator
 214 needs only 128 bits (16 bytes) of seed material from
 215 .IR /dev/random .
 216 .PP
 217 While some safety margin above that minimum is reasonable, as a guard
 218 against flaws in the CSPRNG algorithm, no cryptographic primitive
 219 available today can hope to promise more than 256 bits of security,
 220 so if any program reads more than 256 bits (32 bytes) from the kernel
 221 random pool per invocation, or per reasonable reseed interval (not less
 222 than one minute), that should be taken as a sign that its cryptography is
 223 .I not
 224 skillfully implemented.
 225 .\"
 226 .SH SEE ALSO
 227 .BR getrandom (2),
 228 .BR getauxval (3),
 229 .BR getentropy (3),
 230 .BR random (4),
 231 .BR urandom (4),
 232 .BR signal (7)