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

FILES

215       /dev/random
216       /dev/urandom
217

NOTES

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

BUGS

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

SEE ALSO

227       mknod(1), getrandom(2), random(7)
228
229       RFC 1750, "Randomness Recommendations for Security"
230
231
232
233Linux man-pages 6.04              2022-12-04                         random(4)
Impressum