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 August 17, 2015
  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_UMA"
  36 .Sh DESCRIPTION
  37 The
  38 .Nm
  39 device
  40 returns an endless supply of random bytes when read.
  41 It also accepts and reads data
  42 as any ordinary file.
  43 .Pp
  44 The generator will start in an
  45 .Em unseeded
  46 state, and will block reads until
  47 it is seeded for the first time.
  48 This may cause trouble at system boot
  49 when keys and the like
  50 are generated from
  51 .Nm
  52 so steps should be taken to ensure a
  53 seeding as soon as possible.
  54 .Pp
  55 It is also possible
  56 to read random bytes
  57 by using the KERN_ARND sysctl.
  58 On the command line
  59 this could be done by
  60 .Pp
  61 .Dl "sysctl -x -B 16 kern.arandom"
  62 .Pp
  63 This sysctl will not return
  64 random bytes unless
  65 the
  66 .Nm
  67 device is seeded.
  68 .Pp
  69 This initial seeding
  70 of random number generators
  71 is a bootstrapping problem
  72 that needs very careful attention.
  73 In some cases,
  74 it may be difficult
  75 to find enough randomness
  76 to seed a random number generator
  77 until a system is fully operational,
  78 but the system requires random numbers
  79 to become fully operational.
  80 It is (or more accurately should be)
  81 critically important that the
  82 .Nm
  83 device is seeded
  84 before the first time it is used.
  85 In the case where a dummy or "blocking-only"
  86 device is used,
  87 it is the responsibility
  88 of the system architect
  89 to ensure that no blocking reads
  90 hold up critical processes.
  91 .Pp
  92 To see the current settings of the software
  93 .Nm
  94 device, use the command line:
  95 .Pp
  96 .Dl "sysctl kern.random"
  97 .Pp
  98 which results in something like:
  99 .Bd -literal -offset indent
 100 kern.random.fortuna.minpoolsize: 64
 101 kern.random.harvest.mask_symbolic: [HIGH_PERFORMANCE], ... ,CACHED
 102 kern.random.harvest.mask_bin: 00111111111
 103 kern.random.harvest.mask: 511
 104 kern.random.random_sources: 'Intel Secure Key RNG'
 105 .Ed
 106 .Pp
 107 Other than
 108 .Dl kern.random.fortuna.minpoolsize
 109 and
 110 .Dl kern.random.harvest.mask
 111 all settings are read-only.
 112 .Pp
 113 The
 114 .Pa kern.random.fortuna.minpoolsize
 115 sysctl is used
 116 to set the seed threshold.
 117 A smaller number gives a faster seed,
 118 but a less secure one.
 119 In practice,
 120 values between 64 and 256
 121 are acceptable.
 122 .Pp
 123 The
 124 .Va kern.random.harvest.mask
 125 bitmask is used to select
 126 the possible entropy sources.
 127 A 0 (zero) value means
 128 the corresponding source
 129 is not considered
 130 as an entropy source.
 131 Set the bit to 1 (one)
 132 if you wish to use
 133 that source.
 134 The
 135 .Va kern.random.harvest.mask_bin
 136 and
 137 .Va kern.random.harvest.mask_symbolic
 138 sysctls
 139 can be used to confirm
 140 that the choices are correct.
 141 Note that disabled items
 142 in the latter item
 143 are listed in square brackets.
 144 See
 145 .Xr random_harvest 9
 146 for more on the harvesting of entropy.
 147 .Pp
 148 When
 149 .Cd "options RANDOM_LOADABLE"
 150 is used,
 151 the
 152 .Pa /dev/random
 153 device is not created
 154 until an "algorithm module"
 155 is loaded.
 156 Two of these modules
 157 are built by default,
 158 .Em random_fortuna
 159 and
 160 .Em random_yarrow .
 161 The
 162 .Em random_yarrow
 163 module is deprecated,
 164 and will be removed in
 165 .Fx 12.
 166 Use of the Yarrow algorithm
 167 is not encouraged,
 168 but while still present
 169 in the kernel source,
 170 it can be selected with the
 171 .Cd "options RANDOM_YARROW"
 172 kernel option.
 173 Note that these loadable modules
 174 are slightly less efficient
 175 than their compiled-in equivalents.
 176 This is because some functions
 177 must be locked against
 178 load and unload events,
 179 and also must be indirect calls
 180 to allow for removal.
 181 .Pp
 182 When
 183 .Cd "options RANDOM_ENABLE_UMA"
 184 is used,
 185 the
 186 .Pa /dev/random
 187 device will obtain entropy
 188 from the zone allocator.
 189 This is potentially very high rate,
 190 and if so will be of questionable use.
 191 If this is the case,
 192 use of this option
 193 is not recommended.
 194 Determining this is not trivial,
 195 so experimenting and measurement
 196 using tools such as
 197 .Xr dtrace 1
 198 will be required.
 199 .Sh RANDOMNESS
 200 The use of randomness in the field of computing
 201 is a rather subtle issue because randomness means
 202 different things to different people.
 203 Consider generating a password randomly,
 204 simulating a coin tossing experiment or
 205 choosing a random back-off period when a server does not respond.
 206 Each of these tasks requires random numbers,
 207 but the random numbers in each case have different requirements.
 208 .Pp
 209 Generation of passwords, session keys and the like
 210 requires cryptographic randomness.
 211 A cryptographic random number generator should be designed
 212 so that its output is difficult to guess,
 213 even if a lot of auxiliary information is known
 214 (such as when it was seeded, subsequent or previous output, and so on).
 215 On
 216 .Fx ,
 217 seeding for cryptographic random number generators is provided by the
 218 .Nm
 219 device,
 220 which provides real randomness.
 221 The
 222 .Xr arc4random 3
 223 library call provides a pseudo-random sequence
 224 which is generally reckoned to be suitable for
 225 simple cryptographic use.
 226 The OpenSSL library also provides functions for managing randomness
 227 via functions such as
 228 .Xr RAND_bytes 3
 229 and
 230 .Xr RAND_add 3 .
 231 Note that OpenSSL uses the
 232 .Nm
 233 device for seeding automatically.
 234 .Pp
 235 Randomness for simulation is required in engineering or
 236 scientific software and games.
 237 The first requirement of these applications is
 238 that the random numbers produced conform to some well-known,
 239 usually uniform, distribution.
 240 The sequence of numbers should also appear numerically uncorrelated,
 241 as simulation often assumes independence of its random inputs.
 242 Often it is desirable to reproduce
 243 the results of a simulation exactly,
 244 so that if the generator is seeded in the same way,
 245 it should produce the same results.
 246 A peripheral concern for simulation is
 247 the speed of a random number generator.
 248 .Pp
 249 Another issue in simulation is
 250 the size of the state associated with the random number generator, and
 251 how frequently it repeats itself.
 252 For example,
 253 a program which shuffles a pack of cards should have 52!\& possible outputs,
 254 which requires the random number generator to have 52!\& starting states.
 255 This means the seed should have at least log_2(52!) ~ 226 bits of state
 256 if the program is to stand a chance of outputting all possible sequences,
 257 and the program needs some unbiased way of generating these bits.
 258 Again,
 259 the
 260 .Nm
 261 device could be used for seeding here,
 262 but in practice, smaller seeds are usually considered acceptable.
 263 .Pp
 264 .Fx
 265 provides two families of functions which are considered
 266 suitable for simulation.
 267 The
 268 .Xr random 3
 269 family of functions provides a random integer
 270 between 0 to
 271 .if t 2\u\s731\s10\d\(mi1.
 272 .if n (2**31)\(mi1.
 273 The functions
 274 .Xr srandom 3 ,
 275 .Xr initstate 3
 276 and
 277 .Xr setstate 3
 278 are provided for deterministically setting
 279 the state of the generator and
 280 the function
 281 .Xr srandomdev 3
 282 is provided for setting the state via the
 283 .Nm
 284 device.
 285 The
 286 .Xr drand48 3
 287 family of functions are also provided,
 288 which provide random floating point numbers in various ranges.
 289 .Pp
 290 Randomness that is used for collision avoidance
 291 (for example, in certain network protocols)
 292 has slightly different semantics again.
 293 It is usually expected that the numbers will be uniform,
 294 as this produces the lowest chances of collision.
 295 Here again,
 296 the seeding of the generator is very important,
 297 as it is required that different instances of
 298 the generator produce independent sequences.
 299 However, the guessability or reproducibility of the sequence is unimportant,
 300 unlike the previous cases.
 301 .Pp
 302 .Fx
 303 does also provide the traditional
 304 .Xr rand 3
 305 library call,
 306 for compatibility purposes.
 307 However,
 308 it is known to be poor for simulation and
 309 absolutely unsuitable for cryptographic purposes,
 310 so its use is discouraged.
 311 .Sh FILES
 312 .Bl -tag -width ".Pa /dev/random"
 313 .It Pa /dev/random
 314 .El
 315 .Sh SEE ALSO
 316 .Xr arc4random 3 ,
 317 .Xr drand48 3 ,
 318 .Xr rand 3 ,
 319 .Xr RAND_add 3 ,
 320 .Xr RAND_bytes 3 ,
 321 .Xr random 3 ,
 322 .Xr sysctl 8 ,
 323 .Xr random 9
 324 .Rs
 325 .%A Ferguson
 326 .%A Schneier
 327 .%A Kohno
 328 .%B Cryptography Engineering
 329 .%I Wiley
 330 .%O ISBN 978-0-470-47424-2
 331 .Re
 332 .Sh HISTORY
 333 A
 334 .Nm
 335 device appeared in
 336 .Fx 2.2 .
 337 The current software implementation,
 338 introduced in
 339 .Fx 10.0 ,
 340 is by
 341 .An Mark R V Murray ,
 342 and is an implementation of the
 343 .Em Fortuna
 344 algorithm by Ferguson
 345 .Em et al .
 346 It replaces the previous
 347 .Em Yarrow
 348 implementation,
 349 introduced in
 350 .Fx 5.0 .
 351 The Yarrow algorithm
 352 is no longer supported
 353 by its authors,
 354 and is therefore deprecated.