1 .\" Copyright (c) 2001-2015 Mark R V Murray. All rights reserved.
3 .\" Redistribution and use in source and binary forms, with or without
4 .\" modification, are permitted provided that the following conditions
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.
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
29 .Nd the entropy device
31 .Cd "options RANDOM_LOADABLE"
32 .Cd "options RANDOM_ENABLE_ETHER"
33 .Cd "options RANDOM_ENABLE_UMA"
37 device returns an endless supply of random bytes when read.
39 The generator will start in an
41 state, and will block reads until it is seeded for the first time.
43 To provide prompt access to the random device at boot time,
45 automatically saves some entropy data in
49 to provide to the kernel.
50 Additional entropy is regularly saved in
52 This saved entropy is sufficient to unblock the random device on devices with
55 Embedded applications without writable media must determine their own scheme
56 for re-seeding the random device on boot, or accept that the device
57 will remain unseeded and block reads indefinitely.
59 .Sx SECURITY CONSIDERATIONS
64 the direct output of the abstract kernel entropy device can be read with
72 To see the current settings of the software
74 device, use the command line:
76 .Dl "sysctl kern.random"
78 which results in something like:
79 .Bd -literal -offset indent
80 kern.random.block_seeded_status: 0
81 kern.random.fortuna.minpoolsize: 64
82 kern.random.harvest.mask_symbolic: ENABLEDSOURCE,[DISABLEDSOURCE],...,CACHED
83 kern.random.harvest.mask_bin: 00000010000000111011111
84 kern.random.harvest.mask: 66015
85 kern.random.use_chacha20_cipher: 0
86 kern.random.random_sources: 'Intel Secure Key RNG'
87 kern.random.initial_seeding.bypass_before_seeding: 1
88 kern.random.initial_seeding.read_random_bypassed_before_seeding: 0
89 kern.random.initial_seeding.arc4random_bypassed_before_seeding: 0
90 kern.random.initial_seeding.disable_bypass_warnings: 0
94 .Va kern.random.block_seeded_status ,
95 .Va kern.random.fortuna.minpoolsize ,
97 .Va kern.random.harvest.mask ,
98 all settings are read-only via
102 .Pa kern.random.fortuna.minpoolsize
104 to set the seed threshold.
105 A smaller number gives a faster seed,
106 but a less secure one.
108 values between 64 and 256
112 .Va kern.random.harvest.mask
113 bitmask is used to select
114 the possible entropy sources.
115 A 0 (zero) value means
116 the corresponding source
118 as an entropy source.
119 Set the bit to 1 (one)
123 .Va kern.random.harvest.mask_bin
125 .Va kern.random.harvest.mask_symbolic
127 can be used to confirm
128 settings in a human readable form.
131 are listed in square brackets.
134 for more on the harvesting of entropy.
136 .Bl -tag -width ".Pa /dev/urandom"
141 The following tunables are related to initial seeding of the
145 .It Va kern.random.initial_seeding.bypass_before_seeding
147 When set, the system will bypass the
149 device prior to initial seeding.
152 but provides availability on many systems that lack early sources
153 of entropy, or cannot load
155 sufficiently early in boot for
158 When unset (0), the system will block
162 requests if and until the
164 device is initially seeded.
165 .It Va kern.random.initial_seeding.disable_bypass_warnings
167 When set non-zero, disables warnings in dmesg when the
172 The following read-only
174 variables allow programmatic diagnostic of whether
176 device bypass occurred during boot.
177 If they are set (non-zero), the specific functional unit bypassed the strong
179 device output and either produced no output
180 .Xr ( read_random 9 )
181 or seeded itself with minimal, non-cryptographic entropy
182 .Xr ( arc4random 9 ) .
185 .Va kern.random.initial_seeding.read_random_bypassed_before_seeding
187 .Va kern.random.initial_seeding.arc4random_bypassed_before_seeding
200 .%B Cryptography Engineering
202 .%O ISBN 978-0-470-47424-2
209 The implementation was changed to the
210 .Em Yarrow algorithm in
214 the Fortuna algorithm was introduced as the default.
217 Yarrow was removed entirely.
223 .An Mark R V Murray ,
224 with significant contributions from many people.
228 algorithm was designed by
232 .An Tadayoshi Kohno .
235 .Cd "options RANDOM_LOADABLE"
239 device is not created
240 until an "algorithm module"
242 The only module built by default is
244 Loadable random modules
246 than their compiled-in equivalents.
247 This is because some functions
248 must be locked against
249 load and unload events,
250 and also must be indirect calls
251 to allow for removal.
254 .Cd "options RANDOM_ENABLE_UMA"
258 device will obtain entropy
259 from the zone allocator.
260 This is a very high rate source with significant performance impact.
261 Therefore, it is disabled by default.
264 .Cd "options RANDOM_ENABLE_ETHER"
267 device will obtain entropy from
269 structures passing through the network stack.
270 This source is both extremely expensive and a poor source of entropy, so it is
272 .Sh SECURITY CONSIDERATIONS
274 of random number generators
275 is a bootstrapping problem
276 that needs very careful attention.
277 When writable media is available, the
279 paper describes a robust system for rapidly reseeding the device.
281 In some embedded cases, it may be difficult to find enough randomness to seed a
282 random number generator until a system is fully operational.
283 In these cases, is the responsibility of the system architect to ensure that
284 blocking is acceptable, or that the random device is seeded.
285 (This advice does not apply to typical consumer systems.)
287 To emulate embedded systems, developers may set the
288 .Va kern.random.block_seeded_status
289 tunable to 1 to verify boot does not require early availability of the