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.   The file /dev/random has major device number 1 and minor device
17       number 8.  The file /dev/urandom has major device number  1  and  minor
18       device 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       Linux 3.17 and later provides the simpler and safer getrandom(2) inter‐
26       face  which requires no special files; see the getrandom(2) manual page
27       for details.
28
29       When read, the /dev/urandom device returns random bytes using a pseudo‐
30       random  number generator seeded from the entropy pool.  Reads from this
31       device do not block (i.e., the CPU is not yielded), but  can  incur  an
32       appreciable delay when requesting large amounts of data.
33
34       When read during early boot time, /dev/urandom may return data prior to
35       the entropy pool being initialized.  If this is of concern in your  ap‐
36       plication, use getrandom(2) or /dev/random instead.
37
38       The /dev/random device is a legacy interface which dates back to a time
39       where the  cryptographic  primitives  used  in  the  implementation  of
40       /dev/urandom were not widely trusted.  It will return random bytes only
41       within the estimated number of bits of fresh noise in the entropy pool,
42       blocking  if  necessary.  /dev/random is suitable for applications that
43       need high quality randomness, and can afford indeterminate delays.
44
45       When the entropy pool is empty, reads from /dev/random will block until
46       additional  environmental  noise is gathered.  If open(2) is called for
47       /dev/random with the O_NONBLOCK flag, a  subsequent  read(2)  will  not
48       block  if the requested number of bytes is not available.  Instead, the
49       available bytes are returned.  If no byte is  available,  read(2)  will
50       return -1 and errno will be set to EAGAIN.
51
52       The  O_NONBLOCK  flag  has  no  effect when opening /dev/urandom.  When
53       calling read(2) for the device /dev/urandom, reads of up to  256  bytes
54       will  return as many bytes as are requested and will not be interrupted
55       by a signal handler.  Reads with a buffer over this  limit  may  return
56       less  than  the requested number of bytes or fail with the error EINTR,
57       if interrupted by a signal handler.
58
59       Since Linux 3.16, a read(2)  from  /dev/urandom  will  return  at  most
60       32 MB.   A  read(2) from /dev/random will return at most 512 bytes (340
61       bytes on Linux kernels before version 2.6.12).
62
63       Writing to /dev/random or /dev/urandom will  update  the  entropy  pool
64       with  the  data  written,  but this will not result in a higher entropy
65       count.  This means that it will impact  the  contents  read  from  both
66       files, but it will not make reads from /dev/random faster.
67
68   Usage
69       The  /dev/random  interface  is  considered  a  legacy  interface,  and
70       /dev/urandom is preferred and sufficient in all use cases, with the ex‐
71       ception  of  applications  which  require  randomness during early boot
72       time; for these applications, getrandom(2) must be  used  instead,  be‐
73       cause it will block until the entropy pool is initialized.
74
75       If a seed file is saved across reboots as recommended below, the output
76       is cryptographically secure against attackers without local root access
77       as  soon as it is reloaded in the boot sequence, and perfectly adequate
78       for network encryption session keys.  (All  major  Linux  distributions
79       have  saved  the  seed file across reboots since 2000 at least.)  Since
80       reads from /dev/random may block, users will usually want to open it in
81       nonblocking  mode  (or  perform  a read with timeout), and provide some
82       sort of user notification if the desired  entropy  is  not  immediately
83       available.
84
85   Configuration
86       If  your  system does not have /dev/random and /dev/urandom created al‐
87       ready, they can be created with the following commands:
88
89           mknod -m 666 /dev/random c 1 8
90           mknod -m 666 /dev/urandom c 1 9
91           chown root:root /dev/random /dev/urandom
92
93       When a Linux system starts up without much  operator  interaction,  the
94       entropy  pool  may  be in a fairly predictable state.  This reduces the
95       actual amount of noise in the entropy pool below the estimate.  In  or‐
96       der  to counteract this effect, it helps to carry entropy pool informa‐
97       tion across shut-downs and start-ups.  To do this, add the lines to  an
98       appropriate  script  which  is run during the Linux system start-up se‐
99       quence:
100
101           echo "Initializing random number generator..."
102           random_seed=/var/run/random-seed
103           # Carry a random seed from start-up to start-up
104           # Load and then save the whole entropy pool
105           if [ -f $random_seed ]; then
106               cat $random_seed >/dev/urandom
107           else
108               touch $random_seed
109           fi
110           chmod 600 $random_seed
111           poolfile=/proc/sys/kernel/random/poolsize
112           [ -r $poolfile ] && bits=$(cat $poolfile) || bits=4096
113           bytes=$(expr $bits / 8)
114           dd if=/dev/urandom of=$random_seed count=1 bs=$bytes
115
116       Also, add the following lines in an appropriate  script  which  is  run
117       during the Linux system shutdown:
118
119           # Carry a random seed from shut-down to start-up
120           # Save the whole entropy pool
121           echo "Saving random seed..."
122           random_seed=/var/run/random-seed
123           touch $random_seed
124           chmod 600 $random_seed
125           poolfile=/proc/sys/kernel/random/poolsize
126           [ -r $poolfile ] && bits=$(cat $poolfile) || bits=4096
127           bytes=$(expr $bits / 8)
128           dd if=/dev/urandom of=$random_seed count=1 bs=$bytes
129
130       In   the  above  examples,  we  assume  Linux  2.6.0  or  later,  where
131       /proc/sys/kernel/random/poolsize returns the size of the  entropy  pool
132       in bits (see below).
133
134   /proc interfaces
135       The  files  in  the  directory  /proc/sys/kernel/random  (present since
136       2.3.16) provide additional information about the /dev/random device:
137
138       entropy_avail
139              This read-only file gives the available entropy, in bits.   This
140              will be a number in the range 0 to 4096.
141
142       poolsize
143              This  file gives the size of the entropy pool.  The semantics of
144              this file vary across kernel versions:
145
146              Linux 2.4:
147                     This file gives the size of the entropy  pool  in  bytes.
148                     Normally,  this  file  will have the value 512, but it is
149                     writable, and can be changed to any value  for  which  an
150                     algorithm  is  available.   The  choices are 32, 64, 128,
151                     256, 512, 1024, or 2048.
152
153              Linux 2.6 and later:
154                     This file is read-only, and gives the size of the entropy
155                     pool in bits.  It contains the value 4096.
156
157       read_wakeup_threshold
158              This  file  contains  the number of bits of entropy required for
159              waking  up  processes  that  sleep  waiting  for  entropy   from
160              /dev/random.  The default is 64.
161
162       write_wakeup_threshold
163              This  file contains the number of bits of entropy below which we
164              wake up processes that do a select(2) or poll(2) for  write  ac‐
165              cess  to /dev/random.  These values can be changed by writing to
166              the files.
167
168       uuid and boot_id
169              These   read-only   files   contain    random    strings    like
170              6fd5a44b-35f4-4ad4-a9b9-6b9be13e1fe9.   The  former is generated
171              afresh for each read, the latter was generated once.
172
173   ioctl(2) interface
174       The following ioctl(2) requests are defined on  file  descriptors  con‐
175       nected  to  either /dev/random or /dev/urandom.  All requests performed
176       will interact with the input entropy pool  impacting  both  /dev/random
177       and /dev/urandom.  The CAP_SYS_ADMIN capability is required for all re‐
178       quests except RNDGETENTCNT.
179
180       RNDGETENTCNT
181              Retrieve the entropy count of the input pool, the contents  will
182              be  the  same  as the entropy_avail file under proc.  The result
183              will be stored in the int pointed to by the argument.
184
185       RNDADDTOENTCNT
186              Increment or decrement the entropy count of the  input  pool  by
187              the value pointed to by the argument.
188
189       RNDGETPOOL
190              Removed in Linux 2.6.9.
191
192       RNDADDENTROPY
193              Add  some additional entropy to the input pool, incrementing the
194              entropy count.  This differs  from  writing  to  /dev/random  or
195              /dev/urandom,  which  only adds some data but does not increment
196              the entropy count.  The following structure is used:
197
198                  struct rand_pool_info {
199                      int    entropy_count;
200                      int    buf_size;
201                      __u32  buf[0];
202                  };
203
204              Here entropy_count is the value added to  (or  subtracted  from)
205              the  entropy count, and buf is the buffer of size buf_size which
206              gets added to the entropy pool.
207
208       RNDZAPENTCNT, RNDCLEARPOOL
209              Zero the entropy count of all pools and  add  some  system  data
210              (such as wall clock) to the pools.
211

FILES

213       /dev/random
214       /dev/urandom
215

NOTES

217       For  an  overview  and comparison of the various interfaces that can be
218       used to obtain randomness, see random(7).
219

BUGS

221       During early boot time, reads from /dev/urandom may return  data  prior
222       to the entropy pool being initialized.
223

SEE ALSO

225       mknod(1), getrandom(2), random(7)
226
227       RFC 1750, "Randomness Recommendations for Security"
228

COLOPHON

230       This  page  is  part of release 5.10 of the Linux man-pages project.  A
231       description of the project, information about reporting bugs,  and  the
232       latest     version     of     this    page,    can    be    found    at
233       https://www.kernel.org/doc/man-pages/.
234
235
236
237Linux                             2017-09-15                         RANDOM(4)
Impressum