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