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