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