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