share/man/man4/random.4

   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 April 19, 2019
  27 .Dt RANDOM 4
  28 .Os
  29 .Sh NAME
  30 .Nm random
  31 .Nd the entropy device
  32 .Sh SYNOPSIS
  33 .Cd "options RANDOM_LOADABLE"
  34 .Cd "options RANDOM_ENABLE_ETHER"
  35 .Cd "options RANDOM_ENABLE_UMA"
  36 .Sh DESCRIPTION
  37 The
  38 .Nm
  39 device returns an endless supply of random bytes when read.
  40 .Pp
  41 The generator will start in an
  42 .Em unseeded
  43 state, and will block reads until it is seeded for the first time.
  44 .Pp
  45 To provide prompt access to the random device at boot time,
  46 .Fx
  47 automatically saves some entropy data in
  48 .Pa /boot/entropy
  49 for the
  50 .Xr loader 8
  51 to provide to the kernel.
  52 Additional entropy is regularly saved in
  53 .Pa /var/db/entropy .
  54 This saved entropy is sufficient to unblock the random device on devices with
  55 writeable media.
  56 .Pp
  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.
  60 See
  61 .Sx SECURITY CONSIDERATIONS
  62 for more detail.
  63 .Pp
  64 In addition to
  65 .Xr read 2 ,
  66 the direct output of the abstract kernel entropy device can be read with
  67 .Xr getrandom 2 ,
  68 .Xr getentropy 3 ,
  69 or the
  70 .Xr sysctl 8
  71 pseudo-variable
  72 .Va kern.arandom .
  73 .Pp
  74 To see the current settings of the software
  75 .Nm
  76 device, use the command line:
  77 .Pp
  78 .Dl "sysctl kern.random"
  79 .Pp
  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
  93 .Ed
  94 .Pp
  95 Other than
  96 .Va kern.random.block_seeded_status ,
  97 .Va kern.random.fortuna.minpoolsize ,
  98 and
  99 .Va kern.random.harvest.mask ,
 100 all settings are read-only via
 101 .Xr sysctl 8 .
 102 .Pp
 103 The
 104 .Pa kern.random.fortuna.minpoolsize
 105 sysctl is used
 106 to set the seed threshold.
 107 A smaller number gives a faster seed,
 108 but a less secure one.
 109 In practice,
 110 values between 64 and 256
 111 are acceptable.
 112 .Pp
 113 The
 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
 119 is not considered
 120 as an entropy source.
 121 Set the bit to 1 (one)
 122 if you wish to use
 123 that source.
 124 The
 125 .Va kern.random.harvest.mask_bin
 126 and
 127 .Va kern.random.harvest.mask_symbolic
 128 sysctls
 129 can be used to confirm
 130 settings in a human readable form.
 131 Disabled items
 132 in the latter
 133 are listed in square brackets.
 134 See
 135 .Xr random_harvest 9
 136 for more on the harvesting of entropy.
 137 .Sh FILES
 138 .Bl -tag -width ".Pa /dev/urandom"
 139 .It Pa /dev/random
 140 .It Pa /dev/urandom
 141 .El
 142 .Sh DIAGNOSTICS
 143 The following tunables are related to initial seeding of the
 144 .Nm
 145 device:
 146 .Bl -tag -width 4
 147 .It Va kern.random.initial_seeding.bypass_before_seeding
 148 Defaults to 1 (on).
 149 When set, the system will bypass the
 150 .Nm
 151 device prior to initial seeding.
 152 On is
 153 .Em unsafe ,
 154 but provides availability on many systems that lack early sources
 155 of entropy, or cannot load
 156 .Pa /boot/entropy
 157 sufficiently early in boot for
 158 .Nm
 159 consumers.
 160 When unset (0), the system will block
 161 .Xr read_random 9
 162 and
 163 .Xr arc4random 9
 164 requests if and until the
 165 .Nm
 166 device is initially seeded.
 167 .It Va kern.random.initial_seeding.disable_bypass_warnings
 168 Defaults to 0 (off).
 169 When set non-zero, disables warnings in dmesg when the
 170 .Nm
 171 device is bypassed.
 172 .El
 173 .Pp
 174 The following read-only
 175 .Xr sysctl 8
 176 variables allow programmatic diagnostic of whether
 177 .Nm
 178 device bypass occurred during boot.
 179 If they are set (non-zero), the specific functional unit bypassed the strong
 180 .Nm
 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 ) .
 185 .Bl -bullet
 186 .It
 187 .Va kern.random.initial_seeding.read_random_bypassed_before_seeding
 188 .It
 189 .Va kern.random.initial_seeding.arc4random_bypassed_before_seeding
 190 .El
 191 .Sh SEE ALSO
 192 .Xr getrandom 2 ,
 193 .Xr arc4random 3 ,
 194 .Xr getentropy 3 ,
 195 .Xr random 3 ,
 196 .Xr sysctl 8 ,
 197 .Xr random 9
 198 .Rs
 199 .%A Ferguson
 200 .%A Schneier
 201 .%A Kohno
 202 .%B Cryptography Engineering
 203 .%I Wiley
 204 .%O ISBN 978-0-470-47424-2
 205 .Re
 206 .Sh HISTORY
 207 A
 208 .Nm
 209 device appeared in
 210 .Fx 2.2 .
 211 The implementation was changed to the
 212 .Em Yarrow algorithm in
 213 .Fx 5.0 .
 214 In
 215 .Fx 11.0 ,
 216 the Fortuna algorithm was introduced as the default.
 217 In
 218 .Fx 12.0 ,
 219 Yarrow was removed entirely.
 220 .Sh AUTHORS
 221 .An -nosplit
 222 The current
 223 .Nm
 224 code was authored by
 225 .An Mark R V Murray ,
 226 with significant contributions from many people.
 227 .Pp
 228 The
 229 .Em Fortuna
 230 algorithm was designed by
 231 .An Niels Ferguson ,
 232 .An Bruce Schneier ,
 233 and
 234 .An Tadayoshi Kohno .
 235 .Sh CAVEATS
 236 When
 237 .Cd "options RANDOM_LOADABLE"
 238 is enabled,
 239 the
 240 .Pa /dev/random
 241 device is not created
 242 until an "algorithm module"
 243 is loaded.
 244 The only module built by default is
 245 .Em random_fortuna .
 246 Loadable random modules
 247 are less efficient
 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.
 254 .Pp
 255 When
 256 .Cd "options RANDOM_ENABLE_UMA"
 257 is enabled,
 258 the
 259 .Pa /dev/random
 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.
 264 .Pp
 265 When
 266 .Cd "options RANDOM_ENABLE_ETHER"
 267 is enabled, the
 268 .Nm
 269 device will obtain entropy from
 270 .Vt mbuf
 271 structures passing through the network stack.
 272 This source is both extremely expensive and a poor source of entropy, so it is
 273 disabled by default.
 274 .Sh SECURITY CONSIDERATIONS
 275 The initial seeding
 276 of random number generators
 277 is a bootstrapping problem
 278 that needs very careful attention.
 279 When writable media is available, the
 280 .Em Fortuna
 281 paper describes a robust system for rapidly reseeding the device.
 282 .Pp
 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.)
 288 .Pp
 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
 292 .Nm
 293 device.