share/man/man4/random.4

   1 .\" Copyright (c) 2001  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 7, 2013
  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 .Sh DESCRIPTION
  35 The
  36 .Nm
  37 device
  38 returns an endless supply of random bytes when read.
  39 It also accepts and reads data
  40 as any ordinary (and willing) file,
  41 but discards data written to it.
  42 The device will probe for
  43 certain hardware entropy sources,
  44 and use these in preference to the fallback,
  45 which is a generator implemented in software.
  46 If the kernel environment MIB's
  47 .Va hw.nehemiah_rng_enable
  48 or
  49 .Va hw.ivy_rng_enable
  50 are set to
  51 .Dq Li 0 ,
  52 the associated hardware entropy source will be ignored.
  53 .Pp
  54 If the device is using
  55 the software generator,
  56 writing data to
  57 .Nm
  58 would perturb the internal state.
  59 This perturbation of the internal state
  60 is the only userland method of introducing
  61 extra entropy into the device.
  62 If the writer has superuser privilege,
  63 then closing the device after writing
  64 will make the software generator reseed itself.
  65 This can be used for extra security,
  66 as it immediately introduces any/all new entropy
  67 into the PRNG.
  68 The hardware generators will generate
  69 sufficient quantities of entropy,
  70 and will therefore ignore user-supplied input.
  71 The software
  72 .Nm
  73 device may be controlled with
  74 .Xr sysctl 8 .
  75 .Pp
  76 To see the current settings of the software
  77 .Nm
  78 device, use the command line:
  79 .Pp
  80 .Dl sysctl kern.random
  81 .Pp
  82 which results in something like:
  83 .Bd -literal -offset indent
  84 kern.random.adaptors: yarrow
  85 kern.random.sys.seeded: 1
  86 kern.random.sys.harvest.ethernet: 1
  87 kern.random.sys.harvest.point_to_point: 1
  88 kern.random.sys.harvest.interrupt: 1
  89 kern.random.sys.harvest.swi: 0
  90 kern.random.yarrow.gengateinterval: 10
  91 kern.random.yarrow.bins: 10
  92 kern.random.yarrow.fastthresh: 192
  93 kern.random.yarrow.slowthresh: 256
  94 kern.random.yarrow.slowoverthresh: 2
  95 .Ed
  96 .Pp
  97 (These would not be seen if a
  98 hardware generator is present.)
  99 .Pp
 100 Other than
 101 .Dl kern.random.adaptors
 102 all settings are read/write.
 103 .Pp
 104 The
 105 .Va kern.random.sys.seeded
 106 variable indicates whether or not the
 107 .Nm
 108 device is in an acceptably secure state
 109 as a result of reseeding.
 110 If set to 0, the device will block (on read) until the next reseed
 111 (which can be from an explicit write,
 112 or as a result of entropy harvesting).
 113 A reseed will set the value to 1 (non-blocking).
 114 .Pp
 115 The
 116 .Va kern.random.sys.harvest.ethernet
 117 variable is used to select LAN traffic as an entropy source.
 118 A 0 (zero) value means that LAN traffic
 119 is not considered as an entropy source.
 120 Set the variable to 1 (one)
 121 if you wish to use LAN traffic for entropy harvesting.
 122 .Pp
 123 The
 124 .Va kern.random.sys.harvest.point_to_point
 125 variable is used to select serial line traffic as an entropy source.
 126 (Serial line traffic includes PPP, SLIP and all tun0 traffic.)
 127 A 0 (zero) value means such traffic
 128 is not considered as an entropy source.
 129 Set the variable to 1 (one)
 130 if you wish to use it for entropy harvesting.
 131 .Pp
 132 The
 133 .Va kern.random.sys.harvest.interrupt
 134 variable is used to select hardware interrupts
 135 as an entropy source.
 136 A 0 (zero) value means hardware interrupts
 137 are not considered as an entropy source.
 138 Set the variable to 1 (one)
 139 if you wish to use them for entropy harvesting.
 140 All hardware interrupt harvesting is set up by the
 141 individual device drivers.
 142 .Pp
 143 The
 144 .Va kern.random.sys.harvest.swi
 145 variable is used to select software interrupts
 146 as an entropy source.
 147 A 0 (zero) value means software interrupts
 148 are not considered as an entropy source.
 149 Set the variable to 1 (one)
 150 if you wish to use them for entropy harvesting.
 151 .Pp
 152 The other variables are explained in the paper describing the
 153 .Em Yarrow
 154 algorithm at
 155 .Pa http://www.schneier.com/yarrow.html .
 156 .Pp
 157 These variables are all limited
 158 in terms of the values they may contain:
 159 .Bl -tag -width "kern.random.yarrow.gengateinterval" -compact -offset indent
 160 .It Va kern.random.yarrow.gengateinterval
 161 .Bq 4..64
 162 .It Va kern.random.yarrow.bins
 163 .Bq 2..16
 164 .It Va kern.random.yarrow.fastthresh
 165 .Bq 64..256
 166 .It Va kern.random.yarrow.slowthresh
 167 .Bq 64..256
 168 .It Va kern.random.yarrow.slowoverthresh
 169 .Bq 1..5
 170 .El
 171 .Pp
 172 Internal
 173 .Xr sysctl 3
 174 handlers force the above variables
 175 into the stated ranges.
 176 .Sh RANDOMNESS
 177 The use of randomness in the field of computing
 178 is a rather subtle issue because randomness means
 179 different things to different people.
 180 Consider generating a password randomly,
 181 simulating a coin tossing experiment or
 182 choosing a random back-off period when a server does not respond.
 183 Each of these tasks requires random numbers,
 184 but the random numbers in each case have different requirements.
 185 .Pp
 186 Generation of passwords, session keys and the like
 187 requires cryptographic randomness.
 188 A cryptographic random number generator should be designed
 189 so that its output is difficult to guess,
 190 even if a lot of auxiliary information is known
 191 (such as when it was seeded, subsequent or previous output, and so on).
 192 On
 193 .Fx ,
 194 seeding for cryptographic random number generators is provided by the
 195 .Nm
 196 device,
 197 which provides real randomness.
 198 The
 199 .Xr arc4random 3
 200 library call provides a pseudo-random sequence
 201 which is generally reckoned to be suitable for
 202 simple cryptographic use.
 203 The OpenSSL library also provides functions for managing randomness
 204 via functions such as
 205 .Xr RAND_bytes 3
 206 and
 207 .Xr RAND_add 3 .
 208 Note that OpenSSL uses the
 209 .Nm
 210 device for seeding automatically.
 211 .Pp
 212 Randomness for simulation is required in engineering or
 213 scientific software and games.
 214 The first requirement of these applications is
 215 that the random numbers produced conform to some well-known,
 216 usually uniform, distribution.
 217 The sequence of numbers should also appear numerically uncorrelated,
 218 as simulation often assumes independence of its random inputs.
 219 Often it is desirable to reproduce
 220 the results of a simulation exactly,
 221 so that if the generator is seeded in the same way,
 222 it should produce the same results.
 223 A peripheral concern for simulation is
 224 the speed of a random number generator.
 225 .Pp
 226 Another issue in simulation is
 227 the size of the state associated with the random number generator, and
 228 how frequently it repeats itself.
 229 For example,
 230 a program which shuffles a pack of cards should have 52!\& possible outputs,
 231 which requires the random number generator to have 52!\& starting states.
 232 This means the seed should have at least log_2(52!) ~ 226 bits of state
 233 if the program is to stand a chance of outputting all possible sequences,
 234 and the program needs some unbiased way of generating these bits.
 235 Again,
 236 the
 237 .Nm
 238 device could be used for seeding here,
 239 but in practice, smaller seeds are usually considered acceptable.
 240 .Pp
 241 .Fx
 242 provides two families of functions which are considered
 243 suitable for simulation.
 244 The
 245 .Xr random 3
 246 family of functions provides a random integer
 247 between 0 to
 248 .if t 2\u\s731\s10\d\(mi1.
 249 .if n (2**31)\(mi1.
 250 The functions
 251 .Xr srandom 3 ,
 252 .Xr initstate 3
 253 and
 254 .Xr setstate 3
 255 are provided for deterministically setting
 256 the state of the generator and
 257 the function
 258 .Xr srandomdev 3
 259 is provided for setting the state via the
 260 .Nm
 261 device.
 262 The
 263 .Xr drand48 3
 264 family of functions are also provided,
 265 which provide random floating point numbers in various ranges.
 266 .Pp
 267 Randomness that is used for collision avoidance
 268 (for example, in certain network protocols)
 269 has slightly different semantics again.
 270 It is usually expected that the numbers will be uniform,
 271 as this produces the lowest chances of collision.
 272 Here again,
 273 the seeding of the generator is very important,
 274 as it is required that different instances of
 275 the generator produce independent sequences.
 276 However, the guessability or reproducibility of the sequence is unimportant,
 277 unlike the previous cases.
 278 .Pp
 279 One final consideration for the seeding of random number generators
 280 is a bootstrapping problem.
 281 In some cases, it may be difficult to find enough randomness to
 282 seed a random number generator until a system is fully operational,
 283 but the system requires random numbers to become fully operational.
 284 There is no substitute for careful thought here,
 285 but the
 286 .Fx
 287 .Nm
 288 device,
 289 which is based on the Yarrow system,
 290 should be of some help in this area.
 291 .Pp
 292 .Fx
 293 does also provide the traditional
 294 .Xr rand 3
 295 library call,
 296 for compatibility purposes.
 297 However,
 298 it is known to be poor for simulation and
 299 absolutely unsuitable for cryptographic purposes,
 300 so its use is discouraged.
 301 .Sh FILES
 302 .Bl -tag -width ".Pa /dev/random"
 303 .It Pa /dev/random
 304 .El
 305 .Sh SEE ALSO
 306 .Xr arc4random 3 ,
 307 .Xr drand48 3 ,
 308 .Xr rand 3 ,
 309 .Xr RAND_add 3 ,
 310 .Xr RAND_bytes 3 ,
 311 .Xr random 3 ,
 312 .Xr sysctl 8
 313 .Sh HISTORY
 314 A
 315 .Nm
 316 device appeared in
 317 .Fx 2.2 .
 318 The early version was taken from Theodore Ts'o's entropy driver for Linux.
 319 The current software implementation,
 320 introduced in
 321 .Fx 5.0 ,
 322 is a complete rewrite by
 323 .An Mark R V Murray ,
 324 and is an implementation of the
 325 .Em Yarrow
 326 algorithm by Bruce Schneier,
 327 .Em et al .
 328 The only hardware implementations
 329 currently are for the
 330 .Tn VIA C3 Nehemiah
 331 (stepping 3 or greater)
 332 CPU
 333 and the
 334 .Tn Intel
 335 .Dq Bull Mountain
 336 .Em RdRand
 337 instruction and underlying random number generator (RNG).
 338 More will be added in the future.
 339 .Pp
 340 The author gratefully acknowledges
 341 significant assistance from VIA Technologies, Inc.