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