1.\" Copyright (c) 2001 Mark R V Murray. All rights reserved.
2.\"
3.\" Redistribution and use in source and binary forms, with or without
4.\" modification, are permitted provided that the following conditions
5.\" are met:
6.\" 1. Redistributions of source code must retain the above copyright
7.\" notice, this list of conditions and the following disclaimer.
8.\" 2. Redistributions in binary form must reproduce the above copyright
9.\" notice, this list of conditions and the following disclaimer in the
10.\" documentation and/or other materials provided with the distribution.
11.\"
12.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
13.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
14.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
15.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
16.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
17.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
18.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
19.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
20.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
21.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
22.\" SUCH DAMAGE.
23.\"
| 1.\" Copyright (c) 2001 Mark R V Murray. All rights reserved.
2.\"
3.\" Redistribution and use in source and binary forms, with or without
4.\" modification, are permitted provided that the following conditions
5.\" are met:
6.\" 1. Redistributions of source code must retain the above copyright
7.\" notice, this list of conditions and the following disclaimer.
8.\" 2. Redistributions in binary form must reproduce the above copyright
9.\" notice, this list of conditions and the following disclaimer in the
10.\" documentation and/or other materials provided with the distribution.
11.\"
12.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
13.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
14.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
15.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
16.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
17.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
18.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
19.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
20.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
21.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
22.\" SUCH DAMAGE.
23.\"
|
24.\" $FreeBSD: head/share/man/man4/random.4 130582 2004-06-16 08:33:57Z ru $
| 24.\" $FreeBSD: head/share/man/man4/random.4 131530 2004-07-03 18:29:24Z ru $
|
25.\"
26.Dd February 10, 2001
27.Dt RANDOM 4
28.Os
29.Sh NAME
30.Nm random
31.Nd the entropy device
32.Sh DESCRIPTION
33The
34.Nm
35device
36returns an endless supply of random bytes when read.
37It also accepts and reads data
38as any ordinary (and willing) file,
39but discards data written to it.
40The device will probe for
41certain hardware entropy sources,
42and use these in preference to the fallback,
43which is a generator implemented in software.
44.Pp
45If the device has is using
46the software generator,
47writing data to
48.Nm
49would perturb the internal state.
50This perturbation of the internal state
51is the only userland method of introducing
52extra entropy into the device.
53If the writer has superuser privilege,
54then closing the device after writing
55will make the software generator reseed itself.
56This can be used for extra security,
57as it immediately introduces any/all new entropy
58into the PRNG.
59The hardware generators will generate
60sufficient quantities of entropy,
61and will therefore ignore user-supplied input.
62The software
63.Nm
64device may be controlled with
65.Xr sysctl 8 .
66.Pp
67To see the devices' current settings, use the command line:
68.Pp
69.Dl sysctl kern.random
70.Pp
71which results in something like:
72.Pp
73.Bd -literal -offset indent
74kern.random.sys.seeded: 1
75kern.random.sys.burst: 20
76kern.random.sys.harvest.ethernet: 0
77kern.random.sys.harvest.point_to_point: 0
78kern.random.sys.harvest.interrupt: 0
79kern.random.yarrow.gengateinterval: 10
80kern.random.yarrow.bins: 10
81kern.random.yarrow.fastthresh: 100
82kern.random.yarrow.slowthresh: 160
83kern.random.yarrow.slowoverthresh: 2
84.Ed
85.Pp
86(These would not be seen if a
87hardware generator is present.)
88.Pp
89All settings are read/write.
90.Pp
91The
92.Va kern.random.sys.seeded
93variable indicates whether or not the
94.Nm
95device is in an acceptably secure state
96as a result of reseeding.
97If set to 0, the device will block (on read) until the next reseed
98(which can be from an explicit write,
99or as a result of entropy harvesting).
100A reseed will set the value to 1 (non-blocking).
101.Pp
102The
103.Va kern.random.sys.burst
104variable instructs the kernel thread
105that processes the harvest queue
106to
107.Xr tsleep 9
108briefly after that many events
109have been processed.
110This helps prevent the random device
111from being so compute-bound
112that it takes over all processing ability.
113A value of 0 (zero) is treated as
114.Em infinity ,
115and will only allow the kernel to pause
116if the queue is empty.
117Only values in the range
118.Bq 0..20
119are accepted.
120.Pp
121The
122.Va kern.random.sys.harvest.ethernet
123variable is used to select LAN traffic as an entropy source.
124A 0 (zero) value means that LAN traffic
125is not considered as an entropy source.
126Set the variable to 1 (one)
127if you wish to use LAN traffic for entropy harvesting.
128.Pp
129The
130.Va kern.random.sys.harvest.point_to_point
131variable is used to select serial line traffic as an entropy source.
132(Serial line traffic includes PPP, SLIP and all tun0 traffic.)
133A 0 (zero) value means such traffic
134is not considered as an entropy source.
135Set the variable to 1 (one)
136if you wish to use it for entropy harvesting.
137.Pp
138The
139.Va kern.random.sys.harvest.interrupt
140variable is used to select hardware interrupts
141as an entropy source.
142A 0 (zero) value means interrupts
143are not considered as an entropy source.
144Set the variable to 1 (one)
145if you wish to use them for entropy harvesting.
146All interrupt harvesting is setup by the
147individual device drivers.
148.Pp
149The other variables are explained in the paper describing the
150.Em Yarrow
151algorithm at
152.Pa http://www.counterpane.com/yarrow.html .
153.Pp
154These variables are all limited
155in terms of the values they may contain:
156.Bl -tag -width "kern.random.yarrow.gengateinterval" -compact -offset indent
157.It Va kern.random.yarrow.gengateinterval
158.Bq 4..64
159.It Va kern.random.yarrow.bins
160.Bq 2..16
161.It Va kern.random.yarrow.fastthresh
162.Bq 64..256
163.It Va kern.random.yarrow.slowthresh
164.Bq 64..256
165.It Va kern.random.yarrow.slowoverthresh
166.Bq 1..5
167.El
168.Pp
169Internal
170.Xr sysctl 3
171handlers force the above variables
172into the stated ranges.
173.Sh RANDOMNESS
174The use of randomness in the field of computing
175is a rather subtle issue because randomness means
176different things to different people.
177Consider generating a password randomly,
178simulating a coin tossing experiment or
179choosing a random back-off period when a server does not respond.
180Each of these tasks requires random numbers,
181but the random numbers in each case have different requirements.
182.Pp
183Generation of passwords, session keys and the like
184requires cryptographic randomness.
185A cryptographic random number generator should be designed
186so that its output is difficult to guess,
187even if a lot of auxiliary information is known
188(such as when it was seeded, subsequent or previous output, and so on).
189On
190.Fx ,
191seeding for cryptographic random number generators is provided by the
192.Nm
193device,
194which provides real randomness.
195The
196.Xr arc4random 3
197library call provides a pseudo-random sequence
198which is generally reckoned to be suitable for
199simple cryptographic use.
200The OpenSSL library also provides functions for managing randomness
201via functions such as
202.Xr RAND_bytes 3
203and
204.Xr RAND_add 3 .
205Note that OpenSSL uses the
206.Nm
207device for seeding automatically.
208.Pp
209Randomness for simulation is required in engineering or
210scientific software and games.
211The first requirement of these applications is
212that the random numbers produced conform to some well-known,
213usually uniform, distribution.
214The sequence of numbers should also appear numerically uncorrelated,
215as simulation often assumes independence of its random inputs.
216Often it is desirable to reproduce
217the results of a simulation exactly,
218so that if the generator is seeded in the same way,
219it should produce the same results.
220A peripheral concern for simulation is
221the speed of a random number generator.
222.Pp
223Another issue in simulation is
224the size of the state associated with the random number generator, and
225how frequently it repeats itself.
226For example,
| 25.\"
26.Dd February 10, 2001
27.Dt RANDOM 4
28.Os
29.Sh NAME
30.Nm random
31.Nd the entropy device
32.Sh DESCRIPTION
33The
34.Nm
35device
36returns an endless supply of random bytes when read.
37It also accepts and reads data
38as any ordinary (and willing) file,
39but discards data written to it.
40The device will probe for
41certain hardware entropy sources,
42and use these in preference to the fallback,
43which is a generator implemented in software.
44.Pp
45If the device has is using
46the software generator,
47writing data to
48.Nm
49would perturb the internal state.
50This perturbation of the internal state
51is the only userland method of introducing
52extra entropy into the device.
53If the writer has superuser privilege,
54then closing the device after writing
55will make the software generator reseed itself.
56This can be used for extra security,
57as it immediately introduces any/all new entropy
58into the PRNG.
59The hardware generators will generate
60sufficient quantities of entropy,
61and will therefore ignore user-supplied input.
62The software
63.Nm
64device may be controlled with
65.Xr sysctl 8 .
66.Pp
67To see the devices' current settings, use the command line:
68.Pp
69.Dl sysctl kern.random
70.Pp
71which results in something like:
72.Pp
73.Bd -literal -offset indent
74kern.random.sys.seeded: 1
75kern.random.sys.burst: 20
76kern.random.sys.harvest.ethernet: 0
77kern.random.sys.harvest.point_to_point: 0
78kern.random.sys.harvest.interrupt: 0
79kern.random.yarrow.gengateinterval: 10
80kern.random.yarrow.bins: 10
81kern.random.yarrow.fastthresh: 100
82kern.random.yarrow.slowthresh: 160
83kern.random.yarrow.slowoverthresh: 2
84.Ed
85.Pp
86(These would not be seen if a
87hardware generator is present.)
88.Pp
89All settings are read/write.
90.Pp
91The
92.Va kern.random.sys.seeded
93variable indicates whether or not the
94.Nm
95device is in an acceptably secure state
96as a result of reseeding.
97If set to 0, the device will block (on read) until the next reseed
98(which can be from an explicit write,
99or as a result of entropy harvesting).
100A reseed will set the value to 1 (non-blocking).
101.Pp
102The
103.Va kern.random.sys.burst
104variable instructs the kernel thread
105that processes the harvest queue
106to
107.Xr tsleep 9
108briefly after that many events
109have been processed.
110This helps prevent the random device
111from being so compute-bound
112that it takes over all processing ability.
113A value of 0 (zero) is treated as
114.Em infinity ,
115and will only allow the kernel to pause
116if the queue is empty.
117Only values in the range
118.Bq 0..20
119are accepted.
120.Pp
121The
122.Va kern.random.sys.harvest.ethernet
123variable is used to select LAN traffic as an entropy source.
124A 0 (zero) value means that LAN traffic
125is not considered as an entropy source.
126Set the variable to 1 (one)
127if you wish to use LAN traffic for entropy harvesting.
128.Pp
129The
130.Va kern.random.sys.harvest.point_to_point
131variable is used to select serial line traffic as an entropy source.
132(Serial line traffic includes PPP, SLIP and all tun0 traffic.)
133A 0 (zero) value means such traffic
134is not considered as an entropy source.
135Set the variable to 1 (one)
136if you wish to use it for entropy harvesting.
137.Pp
138The
139.Va kern.random.sys.harvest.interrupt
140variable is used to select hardware interrupts
141as an entropy source.
142A 0 (zero) value means interrupts
143are not considered as an entropy source.
144Set the variable to 1 (one)
145if you wish to use them for entropy harvesting.
146All interrupt harvesting is setup by the
147individual device drivers.
148.Pp
149The other variables are explained in the paper describing the
150.Em Yarrow
151algorithm at
152.Pa http://www.counterpane.com/yarrow.html .
153.Pp
154These variables are all limited
155in terms of the values they may contain:
156.Bl -tag -width "kern.random.yarrow.gengateinterval" -compact -offset indent
157.It Va kern.random.yarrow.gengateinterval
158.Bq 4..64
159.It Va kern.random.yarrow.bins
160.Bq 2..16
161.It Va kern.random.yarrow.fastthresh
162.Bq 64..256
163.It Va kern.random.yarrow.slowthresh
164.Bq 64..256
165.It Va kern.random.yarrow.slowoverthresh
166.Bq 1..5
167.El
168.Pp
169Internal
170.Xr sysctl 3
171handlers force the above variables
172into the stated ranges.
173.Sh RANDOMNESS
174The use of randomness in the field of computing
175is a rather subtle issue because randomness means
176different things to different people.
177Consider generating a password randomly,
178simulating a coin tossing experiment or
179choosing a random back-off period when a server does not respond.
180Each of these tasks requires random numbers,
181but the random numbers in each case have different requirements.
182.Pp
183Generation of passwords, session keys and the like
184requires cryptographic randomness.
185A cryptographic random number generator should be designed
186so that its output is difficult to guess,
187even if a lot of auxiliary information is known
188(such as when it was seeded, subsequent or previous output, and so on).
189On
190.Fx ,
191seeding for cryptographic random number generators is provided by the
192.Nm
193device,
194which provides real randomness.
195The
196.Xr arc4random 3
197library call provides a pseudo-random sequence
198which is generally reckoned to be suitable for
199simple cryptographic use.
200The OpenSSL library also provides functions for managing randomness
201via functions such as
202.Xr RAND_bytes 3
203and
204.Xr RAND_add 3 .
205Note that OpenSSL uses the
206.Nm
207device for seeding automatically.
208.Pp
209Randomness for simulation is required in engineering or
210scientific software and games.
211The first requirement of these applications is
212that the random numbers produced conform to some well-known,
213usually uniform, distribution.
214The sequence of numbers should also appear numerically uncorrelated,
215as simulation often assumes independence of its random inputs.
216Often it is desirable to reproduce
217the results of a simulation exactly,
218so that if the generator is seeded in the same way,
219it should produce the same results.
220A peripheral concern for simulation is
221the speed of a random number generator.
222.Pp
223Another issue in simulation is
224the size of the state associated with the random number generator, and
225how frequently it repeats itself.
226For example,
|
227a program which shuffles a pack of cards should have 52! possible outputs,
228which requires the random number generator to have 52! starting states.
| 227a program which shuffles a pack of cards should have 52!\& possible outputs,
228which requires the random number generator to have 52!\& starting states.
|
229This means the seed should have at least log_2(52!) ~ 226 bits of state
230if the program is to stand a chance of outputting all possible sequences,
231and the program needs some unbiased way of generating these bits.
232Again,
233the
234.Nm
235device could be used for seeding here,
236but in practice, smaller seeds are usually considered acceptable.
237.Pp
238.Fx
239provides two families of functions which are considered
240suitable for simulation.
241The
242.Xr random 3
243family of functions provides a random integer
244between 0 to
245.if t 2\u\s731\s10\d\(mi1.
246.if n (2**31)\(mi1.
247The functions
248.Xr srandom 3 ,
249.Xr initstate 3
250and
251.Xr setstate 3
252are provided for deterministically setting
253the state of the generator and
254the function
255.Xr srandomdev 3
256is provided for setting the state via the
257.Nm
258device.
259The
260.Xr drand48 3
261family of functions are also provided,
262which provide random floating point numbers in various ranges.
263.Pp
264Randomness that is used for collision avoidance
265(for example, in certain network protocols)
266has slightly different semantics again.
267It is usually expected that the numbers will be uniform,
268as this produces the lowest chances of collision.
269Here again,
270the seeding of the generator is very important,
271as it is required that different instances of
272the generator produce independent sequences.
273However, the guessability or reproducibility of the sequence is unimportant,
274unlike the previous cases.
275.Pp
276One final consideration for the seeding of random number generators
277is a bootstrapping problem.
278In some cases, it may be difficult to find enough randomness to
279seed a random number generator until a system is fully operational,
280but the system requires random numbers to become fully operational.
281There is no substitute for careful thought here,
282but the
283.Fx
284.Nm
285device,
286which is based on the Yarrow system,
287should be of some help in this area.
288.Pp
289.Fx
290does also provide the traditional
291.Xr rand 3
292library call,
293for compatibility purposes.
294However,
295it is known to be poor for simulation and
296absolutely unsuitable for cryptographic purposes,
297so its use is discouraged.
298.Sh FILES
299.Bl -tag -width ".Pa /dev/random"
300.It Pa /dev/random
301.El
302.Sh SEE ALSO
303.Xr arc4random 3 ,
304.Xr drand48 3 ,
305.Xr rand 3 ,
306.Xr random 3 ,
307.Xr RAND_add 3 ,
308.Xr RAND_bytes 3 ,
309.Xr sysctl 8
310.Sh HISTORY
311A
312.Nm
313device appeared in
314.Fx 2.2 .
315The early version was taken from Theodore Ts'o's entropy driver for Linux.
316The current software implementation,
317introduced in
318.Fx 5.0 ,
319is a complete rewrite by
320.An Mark R V Murray ,
321and is an implementation of the
322.Em Yarrow
323algorithm by Bruce Schneier,
324.Em et al .
325The only hardware implementation
326currently is for the
327.Tn VIA C3 Nehemiah
328(stepping 3 or greater)
329CPU.
330More will be added in the future.
331.Pp
332The author gratefully acknowledges
333significant assistance from VIA Technologies, Inc.
| 229This means the seed should have at least log_2(52!) ~ 226 bits of state
230if the program is to stand a chance of outputting all possible sequences,
231and the program needs some unbiased way of generating these bits.
232Again,
233the
234.Nm
235device could be used for seeding here,
236but in practice, smaller seeds are usually considered acceptable.
237.Pp
238.Fx
239provides two families of functions which are considered
240suitable for simulation.
241The
242.Xr random 3
243family of functions provides a random integer
244between 0 to
245.if t 2\u\s731\s10\d\(mi1.
246.if n (2**31)\(mi1.
247The functions
248.Xr srandom 3 ,
249.Xr initstate 3
250and
251.Xr setstate 3
252are provided for deterministically setting
253the state of the generator and
254the function
255.Xr srandomdev 3
256is provided for setting the state via the
257.Nm
258device.
259The
260.Xr drand48 3
261family of functions are also provided,
262which provide random floating point numbers in various ranges.
263.Pp
264Randomness that is used for collision avoidance
265(for example, in certain network protocols)
266has slightly different semantics again.
267It is usually expected that the numbers will be uniform,
268as this produces the lowest chances of collision.
269Here again,
270the seeding of the generator is very important,
271as it is required that different instances of
272the generator produce independent sequences.
273However, the guessability or reproducibility of the sequence is unimportant,
274unlike the previous cases.
275.Pp
276One final consideration for the seeding of random number generators
277is a bootstrapping problem.
278In some cases, it may be difficult to find enough randomness to
279seed a random number generator until a system is fully operational,
280but the system requires random numbers to become fully operational.
281There is no substitute for careful thought here,
282but the
283.Fx
284.Nm
285device,
286which is based on the Yarrow system,
287should be of some help in this area.
288.Pp
289.Fx
290does also provide the traditional
291.Xr rand 3
292library call,
293for compatibility purposes.
294However,
295it is known to be poor for simulation and
296absolutely unsuitable for cryptographic purposes,
297so its use is discouraged.
298.Sh FILES
299.Bl -tag -width ".Pa /dev/random"
300.It Pa /dev/random
301.El
302.Sh SEE ALSO
303.Xr arc4random 3 ,
304.Xr drand48 3 ,
305.Xr rand 3 ,
306.Xr random 3 ,
307.Xr RAND_add 3 ,
308.Xr RAND_bytes 3 ,
309.Xr sysctl 8
310.Sh HISTORY
311A
312.Nm
313device appeared in
314.Fx 2.2 .
315The early version was taken from Theodore Ts'o's entropy driver for Linux.
316The current software implementation,
317introduced in
318.Fx 5.0 ,
319is a complete rewrite by
320.An Mark R V Murray ,
321and is an implementation of the
322.Em Yarrow
323algorithm by Bruce Schneier,
324.Em et al .
325The only hardware implementation
326currently is for the
327.Tn VIA C3 Nehemiah
328(stepping 3 or greater)
329CPU.
330More will be added in the future.
331.Pp
332The author gratefully acknowledges
333significant assistance from VIA Technologies, Inc.
|