man4/random.4

   1 .\" Copyright (c) 1997 John S. Kallal (kallal@voicenet.com)
   2 .\"
   3 .\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA)
   4 .\" This is free documentation; you can redistribute it and/or
   5 .\" modify it under the terms of the GNU General Public License as
   6 .\" published by the Free Software Foundation; either version 2 of
   7 .\" the License, or (at your option) any later version.
   8 .\" %%%LICENSE_END
   9 .\"
  10 .\" Some changes by tytso and aeb.
  11 .\"
  12 .\" 2004-12-16, John V. Belmonte/mtk, Updated init and quit scripts
  13 .\" 2004-04-08, AEB, Improved description of read from /dev/urandom
  14 .\" 2008-06-20, George Spelvin <linux@horizon.com>,
  15 .\"             Matt Mackall <mpm@selenic.com>
  16 .\"
  17 .TH RANDOM 4 2017-09-15 "Linux" "Linux Programmer's Manual"
  18 .SH NAME
  19 random, urandom \- kernel random number source devices
  20 .SH SYNOPSIS
  21 #include <linux/random.h>
  22 .PP
  23 .BI "int ioctl(" fd ", RND" request ", " param ");"
  24 .SH DESCRIPTION
  25 The character special files \fI/dev/random\fP and
  26 \fI/dev/urandom\fP (present since Linux 1.3.30)
  27 provide an interface to the kernel's random number generator.
  28 The file
  29 .I /dev/random
  30 has major device number 1 and minor device number 8.
  31 The file
  32 .I /dev/urandom
  33 has major device number 1 and minor device number 9.
  34 .PP
  35 The random number generator gathers environmental noise
  36 from device drivers and other sources into an entropy pool.
  37 The generator also keeps an estimate of the
  38 number of bits of noise in the entropy pool.
  39 From this entropy pool, random numbers are created.
  40 .PP
  41 Linux 3.17 and later provides the simpler and safer
  42 .BR getrandom (2)
  43 interface which requires no special files;
  44 see the
  45 .BR getrandom (2)
  46 manual page for details.
  47 .PP
  48 When read, the
  49 .I /dev/urandom
  50 device returns random bytes using a pseudorandom
  51 number generator seeded from the entropy pool.
  52 Reads from this device do not block (i.e., the CPU is not yielded),
  53 but can incur an appreciable delay when requesting large amounts of data.
  54 .PP
  55 When read during early boot time,
  56 .IR /dev/urandom
  57 may return data prior to the entropy pool being initialized.
  58 .\" This is a real problem; see
  59 .\" commit 9b4d008787f864f17d008c9c15bbe8a0f7e2fc24
  60 If this is of concern in your application, use
  61 .BR getrandom (2)
  62 or \fI/dev/random\fP instead.
  63 .PP
  64 The \fI/dev/random\fP device is a legacy interface which dates back to
  65 a time where the cryptographic primitives used in the implementation
  66 of \fI/dev/urandom\fP were not widely trusted.
  67 It will return random bytes only within the estimated number of
  68 bits of fresh noise in the entropy pool, blocking if necessary.
  69 \fI/dev/random\fP is suitable for applications that need
  70 high quality randomness, and can afford indeterminate delays.
  71 .PP
  72 When the entropy pool is empty, reads from \fI/dev/random\fP will block
  73 until additional environmental noise is gathered.
  74 If
  75 .BR open (2)
  76 is called for
  77 .I /dev/random
  78 with the
  79 .BR O_NONBLOCK
  80 flag, a subsequent
  81 .BR read (2)
  82 will not block if the requested number of bytes is not available.
  83 Instead, the available bytes are returned.
  84 If no byte is available,
  85 .BR read (2)
  86 will return -1 and
  87 .I errno
  88 will be set to
  89 .BR EAGAIN .
  90 .PP
  91 The
  92 .B O_NONBLOCK
  93 flag has no effect when opening
  94 .IR /dev/urandom .
  95 When calling
  96 .BR read (2)
  97 for the device
  98 .IR /dev/urandom ,
  99 reads of up to 256 bytes will return as many bytes as are requested
 100 and will not be interrupted by a signal handler.
 101 Reads with a buffer over this limit may return less than the
 102 requested number of bytes or fail with the error
 103 .BR EINTR ,
 104 if interrupted by a signal handler.
 105 .PP
 106 Since Linux 3.16,
 107 .\" commit 79a8468747c5f95ed3d5ce8376a3e82e0c5857fc
 108 a
 109 .BR read (2)
 110 from
 111 .IR /dev/urandom
 112 will return at most 32\ MB.
 113 A
 114 .BR read (2)
 115 from
 116 .IR /dev/random
 117 will return at most 512 bytes
 118 .\" SEC_XFER_SIZE in drivers/char/random.c
 119 (340 bytes on Linux kernels before version 2.6.12).
 120 .PP
 121 Writing to \fI/dev/random\fP or \fI/dev/urandom\fP will update the
 122 entropy pool with the data written, but this will not result in a
 123 higher entropy count.
 124 This means that it will impact the contents
 125 read from both files, but it will not make reads from
 126 \fI/dev/random\fP faster.
 127 .SS Usage
 128 The
 129 .IR /dev/random
 130 interface is considered a legacy interface, and
 131 .IR /dev/urandom
 132 is preferred and sufficient in all use cases, with the exception of
 133 applications which require randomness during early boot time; for
 134 these applications,
 135 .BR getrandom (2)
 136 must be used instead,
 137 because it will block until the entropy pool is initialized.
 138 .PP
 139 If a seed file is saved across reboots as recommended below (all major
 140 Linux distributions have done this since 2000 at least), the output is
 141 cryptographically secure against attackers without local root access as
 142 soon as it is reloaded in the boot sequence, and perfectly adequate for
 143 network encryption session keys.
 144 Since reads from
 145 .I /dev/random
 146 may block, users will usually want to open it in nonblocking mode
 147 (or perform a read with timeout),
 148 and provide some sort of user notification if the desired
 149 entropy is not immediately available.
 150 .\"
 151 .SS Configuration
 152 If your system does not have
 153 \fI/dev/random\fP and \fI/dev/urandom\fP created already, they
 154 can be created with the following commands:
 155 .PP
 156 .in +4n
 157 .EX
 158 mknod \-m 666 /dev/random c 1 8
 159 mknod \-m 666 /dev/urandom c 1 9
 160 chown root:root /dev/random /dev/urandom
 161 .EE
 162 .in
 163 .PP
 164 When a Linux system starts up without much operator interaction,
 165 the entropy pool may be in a fairly predictable state.
 166 This reduces the actual amount of noise in the entropy pool
 167 below the estimate.
 168 In order to counteract this effect, it helps to carry
 169 entropy pool information across shut-downs and start-ups.
 170 To do this, add the lines to an appropriate script
 171 which is run during the Linux system start-up sequence:
 172 .PP
 173 .in +4n
 174 .EX
 175 echo "Initializing random number generator..."
 176 random_seed=/var/run/random-seed
 177 # Carry a random seed from start-up to start-up
 178 # Load and then save the whole entropy pool
 179 if [ \-f $random_seed ]; then
 180     cat $random_seed >/dev/urandom
 181 else
 182     touch $random_seed
 183 fi
 184 chmod 600 $random_seed
 185 poolfile=/proc/sys/kernel/random/poolsize
 186 [ \-r $poolfile ] && bits=$(cat $poolfile) || bits=4096
 187 bytes=$(expr $bits / 8)
 188 dd if=/dev/urandom of=$random_seed count=1 bs=$bytes
 189 .EE
 190 .in
 191 .PP
 192 Also, add the following lines in an appropriate script which is
 193 run during the Linux system shutdown:
 194 .PP
 195 .in +4n
 196 .EX
 197 # Carry a random seed from shut-down to start-up
 198 # Save the whole entropy pool
 199 echo "Saving random seed..."
 200 random_seed=/var/run/random-seed
 201 touch $random_seed
 202 chmod 600 $random_seed
 203 poolfile=/proc/sys/kernel/random/poolsize
 204 [ \-r $poolfile ] && bits=$(cat $poolfile) || bits=4096
 205 bytes=$(expr $bits / 8)
 206 dd if=/dev/urandom of=$random_seed count=1 bs=$bytes
 207 .EE
 208 .in
 209 .PP
 210 In the above examples, we assume Linux 2.6.0 or later, where
 211 .IR /proc/sys/kernel/random/poolsize
 212 returns the size of the entropy pool in bits (see below).
 213 .\"
 214 .SS /proc interfaces
 215 The files in the directory
 216 .I /proc/sys/kernel/random
 217 (present since 2.3.16) provide additional information about the
 218 .I /dev/random
 219 device:
 220 .TP
 221 .I entropy_avail
 222 This read-only file gives the available entropy, in bits.
 223 This will be a number in the range 0 to 4096.
 224 .TP
 225 .I poolsize
 226 This file
 227 gives the size of the entropy pool.
 228 The semantics of this file vary across kernel versions:
 229 .RS
 230 .TP
 231 Linux 2.4:
 232 This file gives the size of the entropy pool in
 233 .IR bytes .
 234 Normally, this file will have the value 512, but it is writable,
 235 and can be changed to any value for which an algorithm is available.
 236 The choices are 32, 64, 128, 256, 512, 1024, or 2048.
 237 .TP
 238 Linux 2.6 and later:
 239 This file is read-only, and gives the size of the entropy pool in
 240 .IR bits .
 241 It contains the value 4096.
 242 .RE
 243 .TP
 244 .I read_wakeup_threshold
 245 This file
 246 contains the number of bits of entropy required for waking up processes
 247 that sleep waiting for entropy from
 248 .IR /dev/random .
 249 The default is 64.
 250 .TP
 251 .I write_wakeup_threshold
 252 This file
 253 contains the number of bits of entropy below which we wake up
 254 processes that do a
 255 .BR select (2)
 256 or
 257 .BR poll (2)
 258 for write access to
 259 .IR /dev/random .
 260 These values can be changed by writing to the files.
 261 .TP
 262 .IR uuid " and " boot_id
 263 These read-only files
 264 contain random strings like 6fd5a44b-35f4-4ad4-a9b9-6b9be13e1fe9.
 265 The former is generated afresh for each read, the latter was
 266 generated once.
 267 .\"
 268 .SS ioctl(2) interface
 269 The following
 270 .BR ioctl (2)
 271 requests are defined on file descriptors connected to either \fI/dev/random\fP
 272 or \fI/dev/urandom\fP.
 273 All requests performed will interact with the input
 274 entropy pool impacting both \fI/dev/random\fP and \fI/dev/urandom\fP.
 275 The
 276 .B CAP_SYS_ADMIN
 277 capability is required for all requests except
 278 .BR RNDGETENTCNT .
 279 .TP
 280 .BR RNDGETENTCNT
 281 Retrieve the entropy count of the input pool, the contents will be the same
 282 as the
 283 .I entropy_avail
 284 file under proc.
 285 The result will be stored in the int pointed to by the argument.
 286 .TP
 287 .BR RNDADDTOENTCNT
 288 Increment or decrement the entropy count of the input pool
 289 by the value pointed to by the argument.
 290 .TP
 291 .BR RNDGETPOOL
 292 Removed in Linux 2.6.9.
 293 .TP
 294 .BR RNDADDENTROPY
 295 Add some additional entropy to the input pool,
 296 incrementing the entropy count.
 297 This differs from writing to \fI/dev/random\fP or \fI/dev/urandom\fP,
 298 which only adds some
 299 data but does not increment the entropy count.
 300 The following structure is used:
 301 .IP
 302 .in +4n
 303 .EX
 304 struct rand_pool_info {
 305     int    entropy_count;
 306     int    buf_size;
 307     __u32  buf[0];
 308 };
 309 .EE
 310 .in
 311 .IP
 312 Here
 313 .I entropy_count
 314 is the value added to (or subtracted from) the entropy count, and
 315 .I buf
 316 is the buffer of size
 317 .I buf_size
 318 which gets added to the entropy pool.
 319 .TP
 320 .BR RNDZAPENTCNT ", " RNDCLEARPOOL
 321 Zero the entropy count of all pools and add some system data (such as
 322 wall clock) to the pools.
 323 .SH FILES
 324 .I /dev/random
 325 .br
 326 .I /dev/urandom
 327 .SH NOTES
 328 For an overview and comparison of the various interfaces that
 329 can be used to obtain randomness, see
 330 .BR random (7).
 331 .SH BUGS
 332 During early boot time, reads from
 333 .I /dev/urandom
 334 may return data prior to the entropy pool being initialized.
 335 .\" .SH AUTHOR
 336 .\" The kernel's random number generator was written by
 337 .\" Theodore Ts'o (tytso@athena.mit.edu).
 338 .SH SEE ALSO
 339 .BR mknod (1),
 340 .BR getrandom (2),
 341 .BR random (7)
 342 .PP
 343 RFC\ 1750, "Randomness Recommendations for Security"