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