original/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 .\"     Add a Usage subsection that recommends most users to use
  17 .\"     /dev/urandom, and emphasizes parsimonious usage of /dev/random.
  18 .\"
  19 .TH RANDOM 4 2013-03-15 "Linux" "Linux Programmer's Manual"
  20 .SH NAME
  21 random, urandom \- kernel random number source devices
  22 .SH SYNOPSIS
  23 #include <linux/random.h>
  24 .sp
  25 .BI "int ioctl(" fd ", RND" request ", " param ");"
  26 .SH DESCRIPTION
  27 The character special files \fI/dev/random\fP and
  28 \fI/dev/urandom\fP (present since Linux 1.3.30)
  29 provide an interface to the kernel's random number generator.
  30 File \fI/dev/random\fP has major device number 1
  31 and minor device number 8.
  32 File \fI/dev/urandom\fP has major device number 1 and minor device number 9.
  33 .LP
  34 The random number generator gathers environmental noise
  35 from device drivers and other sources into an entropy pool.
  36 The generator also keeps an estimate of the
  37 number of bits of noise in the entropy pool.
  38 From this entropy pool random numbers are created.
  39 .LP
  40 When read, the \fI/dev/random\fP device will only return random bytes
  41 within the estimated number of bits of noise in the entropy
  42 pool.
  43 \fI/dev/random\fP should be suitable for uses that need very
  44 high quality randomness such as one-time pad or key generation.
  45 When the entropy pool is empty, reads from \fI/dev/random\fP will block
  46 until additional environmental noise is gathered.
  47 .LP
  48 A read from the \fI/dev/urandom\fP device will not block
  49 waiting for more entropy.
  50 As a result, if there is not sufficient entropy in the
  51 entropy pool, the returned values are theoretically vulnerable to a
  52 cryptographic attack on the algorithms used by the driver.
  53 Knowledge of how to do this is not available in the current unclassified
  54 literature, but it is theoretically possible that such an attack may
  55 exist.
  56 If this is a concern in your application, use \fI/dev/random\fP
  57 instead.
  58 .LP
  59 Writing to \fI/dev/random\fP or \fI/dev/urandom\fP will update the
  60 entropy pool with the data written, but this will not result in a
  61 higher entropy count.
  62 This means that it will impact the contents
  63 read from both files, but it will not make reads from
  64 \fI/dev/random\fP faster.
  65 .SS Usage
  66 If you are unsure about whether you should use
  67 .IR /dev/random
  68 or
  69 .IR /dev/urandom ,
  70 then probably you want to use the latter.
  71 As a general rule,
  72 .IR /dev/urandom
  73 should be used for everything except long-lived GPG/SSL/SSH keys.
  74
  75 If a seed file is saved across reboots as recommended below (all major
  76 Linux distributions have done this since 2000 at least), the output is
  77 cryptographically secure against attackers without local root access as
  78 soon as it is reloaded in the boot sequence, and perfectly adequate for
  79 network encryption session keys.
  80 Since reads from
  81 .I /dev/random
  82 may block, users will usually want to open it in nonblocking mode
  83 (or perform a read with timeout),
  84 and provide some sort of user notification if the desired
  85 entropy is not immediately available.
  86
  87 The kernel random-number generator is designed to produce a small
  88 amount of high-quality seed material to seed a
  89 cryptographic pseudo-random number generator (CPRNG).
  90 It is designed for security, not speed, and is poorly
  91 suited to generating large amounts of random data.
  92 Users should be very economical in the amount of seed
  93 material that they read from
  94 .IR /dev/urandom
  95 (and
  96 .IR /dev/random );
  97 unnecessarily reading large quantities of data from this device will have
  98 a negative impact on other users of the device.
  99
 100 The amount of seed material required to generate a cryptographic key
 101 equals the effective key size of the key.
 102 For example, a 3072-bit RSA
 103 or Diffie-Hellman private key has an effective key size of 128 bits
 104 (it requires about 2^128 operations to break) so a key generator only
 105 needs 128 bits (16 bytes) of seed material from
 106 .IR /dev/random .
 107
 108 While some safety margin above that minimum is reasonable, as a guard
 109 against flaws in the CPRNG algorithm, no cryptographic primitive
 110 available today can hope to promise more than 256 bits of security,
 111 so if any program reads more than 256 bits (32 bytes) from the kernel
 112 random pool per invocation, or per reasonable reseed interval (not less
 113 than one minute), that should be taken as a sign that its cryptography is
 114 .I not
 115 skillfully implemented.
 116 .SS Configuration
 117 If your system does not have
 118 \fI/dev/random\fP and \fI/dev/urandom\fP created already, they
 119 can be created with the following commands:
 120
 121 .nf
 122     mknod \-m 644 /dev/random c 1 8
 123     mknod \-m 644 /dev/urandom c 1 9
 124     chown root:root /dev/random /dev/urandom
 125 .fi
 126
 127 When a Linux system starts up without much operator interaction,
 128 the entropy pool may be in a fairly predictable state.
 129 This reduces the actual amount of noise in the entropy pool
 130 below the estimate.
 131 In order to counteract this effect, it helps to carry
 132 entropy pool information across shut-downs and start-ups.
 133 To do this, add the following lines to an appropriate script
 134 which is run during the Linux system start-up sequence:
 135
 136 .nf
 137     echo "Initializing random number generator..."
 138     random_seed=/var/run/random-seed
 139     # Carry a random seed from start-up to start-up
 140     # Load and then save the whole entropy pool
 141     if [ \-f $random_seed ]; then
 142         cat $random_seed >/dev/urandom
 143     else
 144         touch $random_seed
 145     fi
 146     chmod 600 $random_seed
 147     poolfile=/proc/sys/kernel/random/poolsize
 148     [ \-r $poolfile ] && bytes=\`cat $poolfile\` || bytes=512
 149     dd if=/dev/urandom of=$random_seed count=1 bs=$bytes
 150 .fi
 151
 152 Also, add the following lines in an appropriate script which is
 153 run during the Linux system shutdown:
 154
 155 .nf
 156     # Carry a random seed from shut-down to start-up
 157     # Save the whole entropy pool
 158     echo "Saving random seed..."
 159     random_seed=/var/run/random-seed
 160     touch $random_seed
 161     chmod 600 $random_seed
 162     poolfile=/proc/sys/kernel/random/poolsize
 163     [ \-r $poolfile ] && bytes=\`cat $poolfile\` || bytes=512
 164     dd if=/dev/urandom of=$random_seed count=1 bs=$bytes
 165 .fi
 166 .SS /proc Interface
 167 The files in the directory
 168 .I /proc/sys/kernel/random
 169 (present since 2.3.16) provide an additional interface to the
 170 .I /dev/random
 171 device.
 172 .LP
 173 The read-only file
 174 .I entropy_avail
 175 gives the available entropy.
 176 Normally, this will be 4096 (bits),
 177 a full entropy pool.
 178 .LP
 179 The file
 180 .I poolsize
 181 gives the size of the entropy pool.
 182 The semantics of this file vary across kernel versions:
 183 .RS
 184 .TP 12
 185 Linux 2.4:
 186 This file gives the size of the entropy pool in
 187 .IR bytes .
 188 Normally, this file will have the value 512, but it is writable,
 189 and can be changed to any value for which an algorithm is available.
 190 The choices are 32, 64, 128, 256, 512, 1024, or 2048.
 191 .TP
 192 Linux 2.6:
 193 This file is read-only, and gives the size of the entropy pool in
 194 .IR bits .
 195 It contains the value 4096.
 196 .RE
 197 .LP
 198 The file
 199 .I read_wakeup_threshold
 200 contains the number of bits of entropy required for waking up processes
 201 that sleep waiting for entropy from
 202 .IR /dev/random .
 203 The default is 64.
 204 The file
 205 .I write_wakeup_threshold
 206 contains the number of bits of entropy below which we wake up
 207 processes that do a
 208 .BR select (2)
 209 or
 210 .BR poll (2)
 211 for write access to
 212 .IR /dev/random .
 213 These values can be changed by writing to the files.
 214 .LP
 215 The read-only files
 216 .I uuid
 217 and
 218 .I boot_id
 219 contain random strings like 6fd5a44b-35f4-4ad4-a9b9-6b9be13e1fe9.
 220 The former is generated afresh for each read, the latter was
 221 generated once.
 222 .SS ioctl(2) interface
 223 The following
 224 .BR ioctl (2)
 225 requests are defined on file descriptors connected to either \fI/dev/random\fP
 226 or \fI/dev/urandom\fP.
 227 All requests performed will interact with the input
 228 entropy pool impacting both \fI/dev/random\fP and \fI/dev/urandom\fP.
 229 The
 230 .B CAP_SYS_ADMIN
 231 capability is required for all requests except
 232 .BR RNDGETENTCNT .
 233 .TP
 234 .BR RNDGETENTCNT
 235 Retrieve the entropy count of the input pool, the contents will be the same
 236 as the
 237 .I entropy_avail
 238 file under proc.
 239 The result will be stored in the int pointed to by the argument.
 240 .TP
 241 .BR RNDADDTOENTCNT
 242 Increment or decrement the entropy count of the input pool
 243 by the value pointed to by the argument.
 244 .TP
 245 .BR RNDGETPOOL
 246 Removed in Linux 2.6.9.
 247 .TP
 248 .BR RNDADDENTROPY
 249 Add some additional entropy to the input pool,
 250 incrementing the entropy count.
 251 This differs from writing to \fI/dev/random\fP or \fI/dev/urandom\fP,
 252 which only adds some
 253 data but does not increment the entropy count.
 254 The following structure is used:
 255 .IP
 256 .nf
 257     struct rand_pool_info {
 258         int    entropy_count;
 259         int    buf_size;
 260         __u32  buf[0];
 261     };
 262 .fi
 263 .IP
 264 Here
 265 .I entropy_count
 266 is the value added to (or subtracted from) the entropy count, and
 267 .I buf
 268 is the buffer of size
 269 .I buf_size
 270 which gets added to the entropy pool.
 271 .TP
 272 .BR RNDZAPENTCNT ", " RNDCLEARPOOL
 273 Zero the entropy count of all pools and add some system data (such as
 274 wall clock) to the pools.
 275 .SH FILES
 276 /dev/random
 277 .br
 278 /dev/urandom
 279 .\" .SH AUTHOR
 280 .\" The kernel's random number generator was written by
 281 .\" Theodore Ts'o (tytso@athena.mit.edu).
 282 .SH SEE ALSO
 283 .BR mknod (1)
 284 .br
 285 RFC\ 1750, "Randomness Recommendations for Security"
 286 .SH COLOPHON
 287 This page is part of release 3.67 of the Linux
 288 .I man-pages
 289 project.
 290 A description of the project,
 291 information about reporting bugs,
 292 and the latest version of this page,
 293 can be found at
 294 \%http://www.kernel.org/doc/man\-pages/.