diff options
Diffstat (limited to 'share/man/man4/random.4')
| -rw-r--r-- | share/man/man4/random.4 | 330 |
1 files changed, 330 insertions, 0 deletions
diff --git a/share/man/man4/random.4 b/share/man/man4/random.4 new file mode 100644 index 0000000..a87a2ed7 --- /dev/null +++ b/share/man/man4/random.4 @@ -0,0 +1,330 @@ +.\" Copyright (c) 2001-2013 Mark R V Murray. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd October 12, 2013 +.Dt RANDOM 4 +.Os +.Sh NAME +.Nm random +.Nd the entropy device +.Sh SYNOPSIS +.Cd "device random" +.Sh DESCRIPTION +The +.Nm +device +returns an endless supply of random bytes when read. +It also accepts and reads data +as any ordinary (and willing) file, +but discards data written to it. +The device will probe for +certain hardware entropy sources, +and use these in preference to the fallback, +which is a generator implemented in software. +.Pp +The software generator will start in an +.Em unseeded +state, and will block reads until +it is (re)seeded. +This may cause trouble at system boot +when keys and the like +are generated from +/dev/random +so steps should be taken to ensure a +reseed as soon as possible. +The +.Xr sysctl 8 +controlling the +.Em seeded +status (see below) may be used +if security is not an issue +or for convenience +during setup or development. +.Pp +This initial seeding +of random number generators +is a bootstrapping problem +that needs very careful attention. +In some cases, +it may be difficult +to find enough randomness +to seed a random number generator +until a system is fully operational, +but the system requires random numbers +to become fully operational. +It is (or more accurately should be) +critically important that the +.Nm +device is seeded +before the first time it is used. +In the case where a dummy or "blocking-only" +device is used, +it is the responsibility +of the system architect +to ensure that no blocking reads +hold up critical processes. +.Pp +To see the current settings of the software +.Nm +device, use the command line: +.Pp +.Dl sysctl kern.random +.Pp +which results in something like: +.Bd -literal -offset indent +kern.random.adaptors: yarrow,dummy +kern.random.active_adaptor: yarrow +kern.random.yarrow.gengateinterval: 10 +kern.random.yarrow.bins: 10 +kern.random.yarrow.fastthresh: 96 +kern.random.yarrow.slowthresh: 128 +kern.random.yarrow.slowoverthresh: 2 +kern.random.sys.seeded: 1 +kern.random.sys.harvest.ethernet: 1 +kern.random.sys.harvest.point_to_point: 1 +kern.random.sys.harvest.interrupt: 1 +kern.random.sys.harvest.swi: 1 +.Ed +.Pp +Other than +.Dl kern.random.adaptors +all settings are read/write. +.Pp +The +.Va kern.random.sys.seeded +variable indicates whether or not the +.Nm +device is in an acceptably secure state +as a result of reseeding. +If set to 0, +the device will block (on read) +until the next reseed +as a result of entropy harvesting. +A reseed will set the value to 1 (non-blocking). +.Pp +The +.Va kern.random.sys.harvest.ethernet +variable is used to select LAN traffic as an entropy source. +A 0 (zero) value means that LAN traffic +is not considered as an entropy source. +Set the variable to 1 (one) +if you wish to use LAN traffic for entropy harvesting. +.Pp +The +.Va kern.random.sys.harvest.point_to_point +variable is used to select serial line traffic as an entropy source. +(Serial line traffic includes PPP, SLIP and all tun0 traffic.) +A 0 (zero) value means such traffic +is not considered as an entropy source. +Set the variable to 1 (one) +if you wish to use it for entropy harvesting. +.Pp +The +.Va kern.random.sys.harvest.interrupt +variable is used to select hardware interrupts +as an entropy source. +A 0 (zero) value means hardware interrupts +are not considered as an entropy source. +Set the variable to 1 (one) +if you wish to use them for entropy harvesting. +All hardware interrupt harvesting is set up by the +individual device drivers. +.Pp +The +.Va kern.random.sys.harvest.swi +variable is used to select software interrupts +as an entropy source. +A 0 (zero) value means software interrupts +are not considered as an entropy source. +Set the variable to 1 (one) +if you wish to use them for entropy harvesting. +.Pp +The other variables are explained in the paper describing the +.Em Yarrow +algorithm at +.Pa http://www.schneier.com/yarrow.html . +.Pp +These variables are all limited +in terms of the values they may contain: +.Bl -tag -width "kern.random.yarrow.gengateinterval" -compact -offset indent +.It Va kern.random.yarrow.gengateinterval +.Bq 4..64 +.It Va kern.random.yarrow.bins +.Bq 2..16 +.It Va kern.random.yarrow.fastthresh +.Bq 64..256 +.It Va kern.random.yarrow.slowthresh +.Bq 64..256 +.It Va kern.random.yarrow.slowoverthresh +.Bq 1..5 +.El +.Pp +Internal +.Xr sysctl 3 +handlers force the above variables +into the stated ranges. +.Sh RANDOMNESS +The use of randomness in the field of computing +is a rather subtle issue because randomness means +different things to different people. +Consider generating a password randomly, +simulating a coin tossing experiment or +choosing a random back-off period when a server does not respond. +Each of these tasks requires random numbers, +but the random numbers in each case have different requirements. +.Pp +Generation of passwords, session keys and the like +requires cryptographic randomness. +A cryptographic random number generator should be designed +so that its output is difficult to guess, +even if a lot of auxiliary information is known +(such as when it was seeded, subsequent or previous output, and so on). +On +.Fx , +seeding for cryptographic random number generators is provided by the +.Nm +device, +which provides real randomness. +The +.Xr arc4random 3 +library call provides a pseudo-random sequence +which is generally reckoned to be suitable for +simple cryptographic use. +The OpenSSL library also provides functions for managing randomness +via functions such as +.Xr RAND_bytes 3 +and +.Xr RAND_add 3 . +Note that OpenSSL uses the +.Nm +device for seeding automatically. +.Pp +Randomness for simulation is required in engineering or +scientific software and games. +The first requirement of these applications is +that the random numbers produced conform to some well-known, +usually uniform, distribution. +The sequence of numbers should also appear numerically uncorrelated, +as simulation often assumes independence of its random inputs. +Often it is desirable to reproduce +the results of a simulation exactly, +so that if the generator is seeded in the same way, +it should produce the same results. +A peripheral concern for simulation is +the speed of a random number generator. +.Pp +Another issue in simulation is +the size of the state associated with the random number generator, and +how frequently it repeats itself. +For example, +a program which shuffles a pack of cards should have 52!\& possible outputs, +which requires the random number generator to have 52!\& starting states. +This means the seed should have at least log_2(52!) ~ 226 bits of state +if the program is to stand a chance of outputting all possible sequences, +and the program needs some unbiased way of generating these bits. +Again, +the +.Nm +device could be used for seeding here, +but in practice, smaller seeds are usually considered acceptable. +.Pp +.Fx +provides two families of functions which are considered +suitable for simulation. +The +.Xr random 3 +family of functions provides a random integer +between 0 to +.if t 2\u\s731\s10\d\(mi1. +.if n (2**31)\(mi1. +The functions +.Xr srandom 3 , +.Xr initstate 3 +and +.Xr setstate 3 +are provided for deterministically setting +the state of the generator and +the function +.Xr srandomdev 3 +is provided for setting the state via the +.Nm +device. +The +.Xr drand48 3 +family of functions are also provided, +which provide random floating point numbers in various ranges. +.Pp +Randomness that is used for collision avoidance +(for example, in certain network protocols) +has slightly different semantics again. +It is usually expected that the numbers will be uniform, +as this produces the lowest chances of collision. +Here again, +the seeding of the generator is very important, +as it is required that different instances of +the generator produce independent sequences. +However, the guessability or reproducibility of the sequence is unimportant, +unlike the previous cases. +.Pp +.Fx +does also provide the traditional +.Xr rand 3 +library call, +for compatibility purposes. +However, +it is known to be poor for simulation and +absolutely unsuitable for cryptographic purposes, +so its use is discouraged. +.Sh FILES +.Bl -tag -width ".Pa /dev/random" +.It Pa /dev/random +.El +.Sh SEE ALSO +.Xr arc4random 3 , +.Xr drand48 3 , +.Xr rand 3 , +.Xr RAND_add 3 , +.Xr RAND_bytes 3 , +.Xr random 3 , +.Xr sysctl 8 +.Sh HISTORY +A +.Nm +device appeared in +.Fx 2.2 . +The early version was taken from Theodore Ts'o's entropy driver for Linux. +The current software implementation, +introduced in +.Fx 5.0 , +is a complete rewrite by +.An Mark R V Murray , +and is an implementation of the +.Em Yarrow +algorithm by Bruce Schneier, +.Em et al . +Significant infrastructure work was done by Arthur Mesh. +.Pp +The author gratefully acknowledges +significant assistance from VIA Technologies, Inc. |
