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 persists some entropy data in
49 for the loader 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.
101 .Pa kern.random.fortuna.minpoolsize
103 to set the seed threshold.
104 A smaller number gives a faster seed,
105 but a less secure one.
107 values between 64 and 256
111 .Va kern.random.harvest.mask
112 bitmask is used to select
113 the possible entropy sources.
114 A 0 (zero) value means
115 the corresponding source
117 as an entropy source.
118 Set the bit to 1 (one)
122 .Va kern.random.harvest.mask_bin
124 .Va kern.random.harvest.mask_symbolic
126 can be used to confirm
127 settings in a human readable form.
130 are listed in square brackets.
133 for more on the harvesting of entropy.
135 .Bl -tag -width ".Pa /dev/urandom"
140 The following tunables are related to initial seeding of the
144 .It Va kern.random.initial_seeding.bypass_before_seeding
146 When set, the system will bypass the
148 device prior to initial seeding.
151 but provides availability on many systems that lack early sources
152 of entropy, or cannot load
154 sufficiently early in boot for
157 When unset (0), the system will block
161 requests if and until the
163 device is initially seeded.
164 .It Va kern.random.initial_seeding.disable_bypass_warnings
166 When set non-zero, disables warnings in dmesg when the
171 The following read-only
173 variables allow programmatic diagnostic of whether
175 device bypass occurred during boot.
176 If they are set (non-zero), the specific functional unit bypassed the strong
178 device output and either produced no output
179 .Xr ( read_random 9 )
180 or seeded itself with minimal, non-cryptographic entropy
181 .Xr ( arc4random 9 ) .
184 .Va kern.random.initial_seeding.read_random_bypassed_before_seeding
186 .Va kern.random.initial_seeding.arc4random_bypassed_before_seeding
199 .%B Cryptography Engineering
201 .%O ISBN 978-0-470-47424-2
208 The implementation was changed to the
209 .Em Yarrow algorithm in
213 the Fortuna algorithm was introduced as the default.
216 Yarrow was removed entirely.
222 .An Mark R V Murray ,
223 with significant contributions from many people.
227 algorithm was designed by
231 .An Tadayoshi Kohno .
234 .Cd "options RANDOM_LOADABLE"
238 device is not created
239 until an "algorithm module"
241 The only module built by default is
243 Loadable random modules
245 than their compiled-in equivalents.
246 This is because some functions
247 must be locked against
248 load and unload events,
249 and also must be indirect calls
250 to allow for removal.
253 .Cd "options RANDOM_ENABLE_UMA"
257 device will obtain entropy
258 from the zone allocator.
259 This is a very high rate source with significant performance impact.
260 Therefore, it is disabled by default.
263 .Cd "options RANDOM_ENABLE_ETHER"
266 device will obtain entropy from
268 structures passing through the network stack.
269 This source is both extremely expensive and a poor source of entropy, so it is
271 .Sh SECURITY CONSIDERATIONS
273 of random number generators
274 is a bootstrapping problem
275 that needs very careful attention.
276 When writable media is available, the
278 paper describes a robust system for rapidly reseeding the device.
280 In some embedded cases, it may be difficult to find enough randomness to seed a
281 random number generator until a system is fully operational.
282 In these cases, is the responsibility of the system architect to ensure that
283 blocking is acceptable, or that the random device is seeded.
284 (This advice does not apply to typical consumer systems.)
286 To emulate embedded systems, developers may set the
287 .Va kern.random.block_seeded_status
288 tunable to 1 to verify boot does not require early availability of the