1RANDOM(4)                  Linux Programmer's Manual                 RANDOM(4)
2
3
4

NAME

6       random, urandom - kernel random number source devices
7

SYNOPSIS

9       #include <linux/random.h>
10
11       int ioctl(fd, RNDrequest, param);
12

DESCRIPTION

14       The character special files /dev/random and /dev/urandom (present since
15       Linux 1.3.30) provide an interface to the kernel's random number gener‐
16       ator.  File /dev/random has major device number 1 and minor device num‐
17       ber 8.  File /dev/urandom has major device number 1  and  minor  device
18       number 9.
19
20       The  random  number  generator  gathers environmental noise from device
21       drivers and other sources into an entropy  pool.   The  generator  also
22       keeps  an  estimate of the number of bits of noise in the entropy pool.
23       From this entropy pool random numbers are created.
24
25       When read, the /dev/random device will only return random bytes  within
26       the estimated number of bits of noise in the entropy pool.  /dev/random
27       should be suitable for uses that need very high quality randomness such
28       as  one-time  pad  or  key generation.  When the entropy pool is empty,
29       reads from /dev/random will block until additional environmental  noise
30       is gathered.
31
32       A  read  from  the  /dev/urandom device will not block waiting for more
33       entropy.  As a result, if  there  is  not  sufficient  entropy  in  the
34       entropy  pool,  the  returned  values are theoretically vulnerable to a
35       cryptographic attack on the algorithms used by the  driver.   Knowledge
36       of  how to do this is not available in the current unclassified litera‐
37       ture, but it is theoretically possible that such an attack  may  exist.
38       If this is a concern in your application, use /dev/random instead.
39
40       Writing  to  /dev/random  or  /dev/urandom will update the entropy pool
41       with the data written, but this will not result  in  a  higher  entropy
42       count.   This  means  that  it  will impact the contents read from both
43       files, but it will not make reads from /dev/random faster.
44
45   Usage
46       If  you  are  unsure  about  whether  you  should  use  /dev/random  or
47       /dev/urandom,  then  probably you want to use the latter.  As a general
48       rule, /dev/urandom should be  used  for  everything  except  long-lived
49       GPG/SSL/SSH keys.
50
51       If  a seed file is saved across reboots as recommended below (all major
52       Linux distributions have done this since 2000 at least), the output  is
53       cryptographically secure against attackers without local root access as
54       soon as it is reloaded in the boot sequence, and perfectly adequate for
55       network  encryption  session  keys.   Since  reads from /dev/random may
56       block, users will usually want to open it in nonblocking mode (or  per‐
57       form  a  read with timeout), and provide some sort of user notification
58       if the desired entropy is not immediately available.
59
60       The kernel random-number generator  is  designed  to  produce  a  small
61       amount  of  high-quality  seed material to seed a cryptographic pseudo-
62       random number generator (CPRNG).  It  is  designed  for  security,  not
63       speed, and is poorly suited to generating large amounts of random data.
64       Users should be very economical in the amount  of  seed  material  that
65       they  read  from  /dev/urandom (and /dev/random); unnecessarily reading
66       large quantities of data from this device will have a  negative  impact
67       on other users of the device.
68
69       The  amount  of  seed material required to generate a cryptographic key
70       equals the effective key size of the key.  For example, a 3072-bit  RSA
71       or Diffie-Hellman private key has an effective key size of 128 bits (it
72       requires about 2^128 operations to break) so a key generator only needs
73       128 bits (16 bytes) of seed material from /dev/random.
74
75       While  some  safety margin above that minimum is reasonable, as a guard
76       against flaws in the CPRNG algorithm, no cryptographic primitive avail‐
77       able  today  can  hope to promise more than 256 bits of security, so if
78       any program reads more than 256 bits (32 bytes) from the kernel  random
79       pool  per  invocation, or per reasonable reseed interval (not less than
80       one minute), that should be taken as a sign that  its  cryptography  is
81       not skillfully implemented.
82
83   Configuration
84       If  your  system  does  not  have  /dev/random and /dev/urandom created
85       already, they can be created with the following commands:
86
87           mknod -m 644 /dev/random c 1 8
88           mknod -m 644 /dev/urandom c 1 9
89           chown root:root /dev/random /dev/urandom
90
91       When a Linux system starts up without much  operator  interaction,  the
92       entropy  pool  may  be in a fairly predictable state.  This reduces the
93       actual amount of noise in the entropy  pool  below  the  estimate.   In
94       order  to counteract this effect, it helps to carry entropy pool infor‐
95       mation across shut-downs and start-ups.  To do this, add the  following
96       lines  to  an  appropriate  script which is run during the Linux system
97       start-up sequence:
98
99           echo "Initializing random number generator..."
100           random_seed=/var/run/random-seed
101           # Carry a random seed from start-up to start-up
102           # Load and then save the whole entropy pool
103           if [ -f $random_seed ]; then
104               cat $random_seed >/dev/urandom
105           else
106               touch $random_seed
107           fi
108           chmod 600 $random_seed
109           poolfile=/proc/sys/kernel/random/poolsize
110           [ -r $poolfile ] && bytes=`cat $poolfile` || bytes=512
111           dd if=/dev/urandom of=$random_seed count=1 bs=$bytes
112
113       Also, add the following lines in an appropriate  script  which  is  run
114       during the Linux system shutdown:
115
116           # Carry a random seed from shut-down to start-up
117           # Save the whole entropy pool
118           echo "Saving random seed..."
119           random_seed=/var/run/random-seed
120           touch $random_seed
121           chmod 600 $random_seed
122           poolfile=/proc/sys/kernel/random/poolsize
123           [ -r $poolfile ] && bytes=`cat $poolfile` || bytes=512
124           dd if=/dev/urandom of=$random_seed count=1 bs=$bytes
125
126   /proc Interface
127       The  files  in  the  directory  /proc/sys/kernel/random  (present since
128       2.3.16) provide an additional interface to the /dev/random device.
129
130       The read-only file entropy_avail gives  the  available  entropy.   Nor‐
131       mally, this will be 4096 (bits), a full entropy pool.
132
133       The file poolsize gives the size of the entropy pool.  The semantics of
134       this file vary across kernel versions:
135
136              Linux 2.4:  This file gives the size  of  the  entropy  pool  in
137                          bytes.  Normally, this file will have the value 512,
138                          but it is writable, and can be changed to any  value
139                          for  which  an  algorithm is available.  The choices
140                          are 32, 64, 128, 256, 512, 1024, or 2048.
141
142              Linux 2.6:  This file is read-only, and gives the  size  of  the
143                          entropy pool in bits.  It contains the value 4096.
144
145       The  file  read_wakeup_threshold contains the number of bits of entropy
146       required for waking up processes that sleep waiting  for  entropy  from
147       /dev/random.   The default is 64.  The file write_wakeup_threshold con‐
148       tains the number of bits of entropy below which we  wake  up  processes
149       that  do a select(2) or poll(2) for write access to /dev/random.  These
150       values can be changed by writing to the files.
151
152       The read-only files  uuid  and  boot_id  contain  random  strings  like
153       6fd5a44b-35f4-4ad4-a9b9-6b9be13e1fe9.   The  former is generated afresh
154       for each read, the latter was generated once.
155
156   ioctl(2) interface
157       The following ioctl(2) requests are defined on  file  descriptors  con‐
158       nected  to  either /dev/random or /dev/urandom.  All requests performed
159       will interact with the input entropy pool  impacting  both  /dev/random
160       and  /dev/urandom.   The  CAP_SYS_ADMIN  capability is required for all
161       requests except RNDGETENTCNT.
162
163       RNDGETENTCNT
164              Retrieve the entropy count of the input pool, the contents  will
165              be  the  same  as the entropy_avail file under proc.  The result
166              will be stored in the int pointed to by the argument.
167
168       RNDADDTOENTCNT
169              Increment or decrement the entropy count of the  input  pool  by
170              the value pointed to by the argument.
171
172       RNDGETPOOL
173              Removed in Linux 2.6.9.
174
175       RNDADDENTROPY
176              Add  some additional entropy to the input pool, incrementing the
177              entropy count.  This differs  from  writing  to  /dev/random  or
178              /dev/urandom,  which  only adds some data but does not increment
179              the entropy count.  The following structure is used:
180
181                  struct rand_pool_info {
182                      int    entropy_count;
183                      int    buf_size;
184                      __u32  buf[0];
185                  };
186
187              Here entropy_count is the value added to  (or  subtracted  from)
188              the  entropy count, and buf is the buffer of size buf_size which
189              gets added to the entropy pool.
190
191       RNDZAPENTCNT, RNDCLEARPOOL
192              Zero the entropy count of all pools and  add  some  system  data
193              (such as wall clock) to the pools.
194

FILES

196       /dev/random
197       /dev/urandom
198

SEE ALSO

200       mknod(1)
201       RFC 1750, "Randomness Recommendations for Security"
202

COLOPHON

204       This  page  is  part of release 3.53 of the Linux man-pages project.  A
205       description of the project, and information about reporting  bugs,  can
206       be found at http://www.kernel.org/doc/man-pages/.
207
208
209
210Linux                             2013-03-15                         RANDOM(4)
Impressum