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