xref: /freebsd/share/man/man4/random.4 (revision 119b75925c562202145d7bac7b676b98029c6cb9)
1.\" Copyright (c) 2001-2015	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$
25.\"
26.Dd June 30, 2015
27.Dt RANDOM 4
28.Os
29.Sh NAME
30.Nm random
31.Nd the entropy device
32.Sh SYNOPSIS
33.Cd "device random"
34.Sh DESCRIPTION
35The
36.Nm
37device
38returns an endless supply of random bytes when read.
39It also accepts and reads data
40as any ordinary file.
41.Pp
42The generator will start in an
43.Em unseeded
44state, and will block reads until
45it is seeded for the first time.
46This may cause trouble at system boot
47when keys and the like
48are generated from
49.Xr random 4
50so steps should be taken to ensure a
51seeding as soon as possible.
52.Pp
53It is also possible
54to read random bytes
55by using the KERN_ARND sysctl.
56On the command line
57this could be done by
58.Pp
59.Dl "sysctl -x -B 16 kern.arandom"
60.Pp
61This sysctl will not return
62random bytes unless
63the
64.Xr random 4
65device is seeded.
66.Pp
67This initial seeding
68of random number generators
69is a bootstrapping problem
70that needs very careful attention.
71In some cases,
72it may be difficult
73to find enough randomness
74to seed a random number generator
75until a system is fully operational,
76but the system requires random numbers
77to become fully operational.
78It is (or more accurately should be)
79critically important that the
80.Nm
81device is seeded
82before the first time it is used.
83In the case where a dummy or "blocking-only"
84device is used,
85it is the responsibility
86of the system architect
87to ensure that no blocking reads
88hold up critical processes.
89.Pp
90To see the current settings of the software
91.Nm
92device, use the command line:
93.Pp
94.Dl "sysctl kern.random"
95.Pp
96which results in something like:
97.Bd -literal -offset indent
98kern.random.fortuna.minpoolsize: 64
99kern.random.harvest.mask_symbolic: [HIGH_PERFORMANCE], ... ,CACHED
100kern.random.harvest.mask_bin: 00111111111
101kern.random.harvest.mask: 511
102kern.random.random_sources: 'Intel Secure Key RNG'
103.Ed
104.Pp
105Other than
106.Dl kern.random.fortuna.minpoolsize
107and
108.Dl kern.random.harvest.mask
109all settings are read-only.
110.Pp
111The
112.Pa kern.random.fortuna.minpoolsize
113sysctl is used
114to set the seed threshhold.
115A smaller number gives a faster seed,
116but a less secure one.
117In practice,
118values between 64 and 256
119are acceptable.
120.Pp
121The
122.Va kern.random.harvest.mask
123bitmask is used to select
124the possible entropy sources.
125A 0 (zero) value means
126the corresponding source
127is not considered
128as an entropy source.
129Set the bit to 1 (one)
130if you wish to use
131that source.
132The
133.Va kern.random.harvest.mask_bin
134and
135.Va kern.random.harvest.mask_symbolic
136sysctl
137can be used confirm
138that your choices are correct.
139Note that disabled items
140in the latter item
141are listed in square brackets.
142See
143.Xr random_harvest 9
144for more on the harvesting of entropy.
145.Sh RANDOMNESS
146The use of randomness in the field of computing
147is a rather subtle issue because randomness means
148different things to different people.
149Consider generating a password randomly,
150simulating a coin tossing experiment or
151choosing a random back-off period when a server does not respond.
152Each of these tasks requires random numbers,
153but the random numbers in each case have different requirements.
154.Pp
155Generation of passwords, session keys and the like
156requires cryptographic randomness.
157A cryptographic random number generator should be designed
158so that its output is difficult to guess,
159even if a lot of auxiliary information is known
160(such as when it was seeded, subsequent or previous output, and so on).
161On
162.Fx ,
163seeding for cryptographic random number generators is provided by the
164.Nm
165device,
166which provides real randomness.
167The
168.Xr arc4random 3
169library call provides a pseudo-random sequence
170which is generally reckoned to be suitable for
171simple cryptographic use.
172The OpenSSL library also provides functions for managing randomness
173via functions such as
174.Xr RAND_bytes 3
175and
176.Xr RAND_add 3 .
177Note that OpenSSL uses the
178.Nm
179device for seeding automatically.
180.Pp
181Randomness for simulation is required in engineering or
182scientific software and games.
183The first requirement of these applications is
184that the random numbers produced conform to some well-known,
185usually uniform, distribution.
186The sequence of numbers should also appear numerically uncorrelated,
187as simulation often assumes independence of its random inputs.
188Often it is desirable to reproduce
189the results of a simulation exactly,
190so that if the generator is seeded in the same way,
191it should produce the same results.
192A peripheral concern for simulation is
193the speed of a random number generator.
194.Pp
195Another issue in simulation is
196the size of the state associated with the random number generator, and
197how frequently it repeats itself.
198For example,
199a program which shuffles a pack of cards should have 52!\& possible outputs,
200which requires the random number generator to have 52!\& starting states.
201This means the seed should have at least log_2(52!) ~ 226 bits of state
202if the program is to stand a chance of outputting all possible sequences,
203and the program needs some unbiased way of generating these bits.
204Again,
205the
206.Nm
207device could be used for seeding here,
208but in practice, smaller seeds are usually considered acceptable.
209.Pp
210.Fx
211provides two families of functions which are considered
212suitable for simulation.
213The
214.Xr random 3
215family of functions provides a random integer
216between 0 to
217.if t 2\u\s731\s10\d\(mi1.
218.if n (2**31)\(mi1.
219The functions
220.Xr srandom 3 ,
221.Xr initstate 3
222and
223.Xr setstate 3
224are provided for deterministically setting
225the state of the generator and
226the function
227.Xr srandomdev 3
228is provided for setting the state via the
229.Nm
230device.
231The
232.Xr drand48 3
233family of functions are also provided,
234which provide random floating point numbers in various ranges.
235.Pp
236Randomness that is used for collision avoidance
237(for example, in certain network protocols)
238has slightly different semantics again.
239It is usually expected that the numbers will be uniform,
240as this produces the lowest chances of collision.
241Here again,
242the seeding of the generator is very important,
243as it is required that different instances of
244the generator produce independent sequences.
245However, the guessability or reproducibility of the sequence is unimportant,
246unlike the previous cases.
247.Pp
248.Fx
249does also provide the traditional
250.Xr rand 3
251library call,
252for compatibility purposes.
253However,
254it is known to be poor for simulation and
255absolutely unsuitable for cryptographic purposes,
256so its use is discouraged.
257.Sh FILES
258.Bl -tag -width ".Pa /dev/random"
259.It Pa /dev/random
260.El
261.Sh SEE ALSO
262.Xr arc4random 3 ,
263.Xr drand48 3 ,
264.Xr rand 3 ,
265.Xr RAND_add 3 ,
266.Xr RAND_bytes 3 ,
267.Xr random 3 ,
268.Xr sysctl 8 ,
269.Xr random 9
270.Rs
271.%A Ferguson
272.%A Schneier
273.%A Kohno
274.%B Cryptography Engineering
275.%I Wiley
276.%O ISBN 978-0-470-47424-2
277.Re
278.Sh HISTORY
279A
280.Nm
281device appeared in
282.Fx 2.2 .
283The current software implementation,
284introduced in
285.Fx 10.0 ,
286is by
287.An Mark R V Murray ,
288and is an implementation of the
289.Em Fortuna
290algorithm by Ferguson
291.Em et al .
292It replaces the previous
293.Em Yarrow
294implementation,
295introduced in
296.Fx 5.0 .
297The older
298.Em Yarrow
299algorithm remains available
300as a compile-time fallback.
301