330 lines
9.7 KiB
Groff
330 lines
9.7 KiB
Groff
.\" 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 August 7, 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 .
|
|
.Pp
|
|
The author gratefully acknowledges
|
|
significant assistance from VIA Technologies, Inc.
|