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
31 .Nd the entropy device
33 .Cd "options RANDOM_LOADABLE"
34 .Cd "options RANDOM_ENABLE_ETHER"
35 .Cd "options RANDOM_ENABLE_UMA"
39 device returns an endless supply of random bytes when read.
41 The generator will start in an
43 state, and will block reads until it is seeded for the first time.
45 To provide prompt access to the random device at boot time,
47 automatically saves some entropy data in
51 to provide to the kernel.
52 Additional entropy is regularly saved in
54 This saved entropy is sufficient to unblock the random device on devices with
57 Embedded applications without writable media must determine their own scheme
58 for re-seeding the random device on boot, or accept that the device
59 will remain unseeded and block reads indefinitely.
61 .Sx SECURITY CONSIDERATIONS
66 the direct output of the abstract kernel entropy device can be read with
74 To see the current settings of the software
76 device, use the command line:
78 .Dl "sysctl kern.random"
80 which results in something like:
81 .Bd -literal -offset indent
82 kern.random.block_seeded_status: 0
83 kern.random.fortuna.minpoolsize: 64
84 kern.random.harvest.mask_symbolic: ENABLEDSOURCE,[DISABLEDSOURCE],...,CACHED
85 kern.random.harvest.mask_bin: 00000010000000111011111
86 kern.random.harvest.mask: 66015
87 kern.random.use_chacha20_cipher: 0
88 kern.random.random_sources: 'Intel Secure Key RNG'
89 kern.random.initial_seeding.bypass_before_seeding: 1
90 kern.random.initial_seeding.read_random_bypassed_before_seeding: 0
91 kern.random.initial_seeding.arc4random_bypassed_before_seeding: 0
92 kern.random.initial_seeding.disable_bypass_warnings: 0
96 .Va kern.random.block_seeded_status ,
97 .Va kern.random.fortuna.minpoolsize ,
99 .Va kern.random.harvest.mask ,
100 all settings are read-only via
104 .Pa kern.random.fortuna.minpoolsize
106 to set the seed threshold.
107 A smaller number gives a faster seed,
108 but a less secure one.
110 values between 64 and 256
114 .Va kern.random.harvest.mask
115 bitmask is used to select
116 the possible entropy sources.
117 A 0 (zero) value means
118 the corresponding source
120 as an entropy source.
121 Set the bit to 1 (one)
125 .Va kern.random.harvest.mask_bin
127 .Va kern.random.harvest.mask_symbolic
129 can be used to confirm
130 settings in a human readable form.
133 are listed in square brackets.
136 for more on the harvesting of entropy.
138 .Bl -tag -width ".Pa /dev/urandom"
143 The following tunables are related to initial seeding of the
147 .It Va kern.random.initial_seeding.bypass_before_seeding
149 When set, the system will bypass the
151 device prior to initial seeding.
154 but provides availability on many systems that lack early sources
155 of entropy, or cannot load
157 sufficiently early in boot for
160 When unset (0), the system will block
164 requests if and until the
166 device is initially seeded.
167 .It Va kern.random.initial_seeding.disable_bypass_warnings
169 When set non-zero, disables warnings in dmesg when the
174 The following read-only
176 variables allow programmatic diagnostic of whether
178 device bypass occurred during boot.
179 If they are set (non-zero), the specific functional unit bypassed the strong
181 device output and either produced no output
182 .Xr ( read_random 9 )
183 or seeded itself with minimal, non-cryptographic entropy
184 .Xr ( arc4random 9 ) .
187 .Va kern.random.initial_seeding.read_random_bypassed_before_seeding
189 .Va kern.random.initial_seeding.arc4random_bypassed_before_seeding
202 .%B Cryptography Engineering
204 .%O ISBN 978-0-470-47424-2
211 The implementation was changed to the
212 .Em Yarrow algorithm in
216 the Fortuna algorithm was introduced as the default.
219 Yarrow was removed entirely.
225 .An Mark R V Murray ,
226 with significant contributions from many people.
230 algorithm was designed by
234 .An Tadayoshi Kohno .
237 .Cd "options RANDOM_LOADABLE"
241 device is not created
242 until an "algorithm module"
244 The only module built by default is
246 Loadable random modules
248 than their compiled-in equivalents.
249 This is because some functions
250 must be locked against
251 load and unload events,
252 and also must be indirect calls
253 to allow for removal.
256 .Cd "options RANDOM_ENABLE_UMA"
260 device will obtain entropy
261 from the zone allocator.
262 This is a very high rate source with significant performance impact.
263 Therefore, it is disabled by default.
266 .Cd "options RANDOM_ENABLE_ETHER"
269 device will obtain entropy from
271 structures passing through the network stack.
272 This source is both extremely expensive and a poor source of entropy, so it is
274 .Sh SECURITY CONSIDERATIONS
276 of random number generators
277 is a bootstrapping problem
278 that needs very careful attention.
279 When writable media is available, the
281 paper describes a robust system for rapidly reseeding the device.
283 In some embedded cases, it may be difficult to find enough randomness to seed a
284 random number generator until a system is fully operational.
285 In these cases, is the responsibility of the system architect to ensure that
286 blocking is acceptable, or that the random device is seeded.
287 (This advice does not apply to typical consumer systems.)
289 To emulate embedded systems, developers may set the
290 .Va kern.random.block_seeded_status
291 tunable to 1 to verify boot does not require early availability of the