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