336 lines
10 KiB
Groff
336 lines
10 KiB
Groff
.\" Copyright (c) 2001 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 3, 2004
|
|
.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
|
|
If the device has is using
|
|
the software generator,
|
|
writing data to
|
|
.Nm
|
|
would perturb the internal state.
|
|
This perturbation of the internal state
|
|
is the only userland method of introducing
|
|
extra entropy into the device.
|
|
If the writer has superuser privilege,
|
|
then closing the device after writing
|
|
will make the software generator reseed itself.
|
|
This can be used for extra security,
|
|
as it immediately introduces any/all new entropy
|
|
into the PRNG.
|
|
The hardware generators will generate
|
|
sufficient quantities of entropy,
|
|
and will therefore ignore user-supplied input.
|
|
The software
|
|
.Nm
|
|
device may be controlled with
|
|
.Xr sysctl 8 .
|
|
.Pp
|
|
To see the devices' current settings, use the command line:
|
|
.Pp
|
|
.Dl sysctl kern.random
|
|
.Pp
|
|
which results in something like:
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
kern.random.sys.seeded: 1
|
|
kern.random.sys.burst: 20
|
|
kern.random.sys.harvest.ethernet: 0
|
|
kern.random.sys.harvest.point_to_point: 0
|
|
kern.random.sys.harvest.interrupt: 0
|
|
kern.random.yarrow.gengateinterval: 10
|
|
kern.random.yarrow.bins: 10
|
|
kern.random.yarrow.fastthresh: 100
|
|
kern.random.yarrow.slowthresh: 160
|
|
kern.random.yarrow.slowoverthresh: 2
|
|
.Ed
|
|
.Pp
|
|
(These would not be seen if a
|
|
hardware generator is present.)
|
|
.Pp
|
|
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
|
|
(which can be from an explicit write,
|
|
or as a result of entropy harvesting).
|
|
A reseed will set the value to 1 (non-blocking).
|
|
.Pp
|
|
The
|
|
.Va kern.random.sys.burst
|
|
variable instructs the kernel thread
|
|
that processes the harvest queue
|
|
to
|
|
.Xr tsleep 9
|
|
briefly after that many events
|
|
have been processed.
|
|
This helps prevent the random device
|
|
from being so compute-bound
|
|
that it takes over all processing ability.
|
|
A value of 0 (zero) is treated as
|
|
.Em infinity ,
|
|
and will only allow the kernel to pause
|
|
if the queue is empty.
|
|
Only values in the range
|
|
.Bq 0..20
|
|
are accepted.
|
|
.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 interrupts
|
|
are not considered as an entropy source.
|
|
Set the variable to 1 (one)
|
|
if you wish to use them for entropy harvesting.
|
|
All interrupt harvesting is setup by the
|
|
individual device drivers.
|
|
.Pp
|
|
The other variables are explained in the paper describing the
|
|
.Em Yarrow
|
|
algorithm at
|
|
.Pa http://www.counterpane.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
|
|
One final consideration for the seeding of random number generators
|
|
is a bootstrapping problem.
|
|
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.
|
|
There is no substitute for careful thought here,
|
|
but the
|
|
.Fx
|
|
.Nm
|
|
device,
|
|
which is based on the Yarrow system,
|
|
should be of some help in this area.
|
|
.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 .
|
|
The only hardware implementation
|
|
currently is for the
|
|
.Tn VIA C3 Nehemiah
|
|
(stepping 3 or greater)
|
|
CPU.
|
|
More will be added in the future.
|
|
.Pp
|
|
The author gratefully acknowledges
|
|
significant assistance from VIA Technologies, Inc.
|