[src/trunk]: src/share/man/man4 Rewrite /dev/random man page.

[riastradh <riastradh%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/6182a995fa5f
branches:  trunk
changeset: 335459:6182a995fa5f
user:      riastradh <riastradh%NetBSD.org@localhost>
date:      Wed Jan 07 18:50:18 2015 +0000

description:
Rewrite /dev/random man page.

- Describe application usage up front.
- State the security model.
- Explain entropy.
- Describe current implementation strategy near the bottom.

diffstat:

 share/man/man4/rnd.4 |  869 +++++++++++++++++++++++++++++++++-----------------
 1 files changed, 564 insertions(+), 305 deletions(-)

diffs (truncated from 917 to 300 lines):

diff -r aeaaf1662b84 -r 6182a995fa5f share/man/man4/rnd.4
--- a/share/man/man4/rnd.4      Wed Jan 07 10:22:54 2015 +0000
+++ b/share/man/man4/rnd.4      Wed Jan 07 18:50:18 2015 +0000
@@ -1,8 +1,11 @@
-.\"    $NetBSD: rnd.4,v 1.20 2012/04/17 08:28:20 wiz Exp $
+.\"    $NetBSD: rnd.4,v 1.21 2015/01/07 18:50:18 riastradh Exp $
 .\"
-.\" Copyright (c) 1997 Michael Graff
+.\" Copyright (c) 2014 The NetBSD Foundation, Inc.
 .\" All rights reserved.
 .\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Taylor R. Campbell.
+.\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
 .\" are met:
@@ -11,340 +14,596 @@
 .\" 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.
-.\" 3. The name of the author may not be used to endorse or promote products
-.\"    derived from this software without specific prior written permission.
 .\"
-.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 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.
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. 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 FOUNDATION 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.
 .\"
-.Dd April 17, 2012
+.Dd November 16, 2014
 .Dt RND 4
 .Os
 .Sh NAME
 .Nm rnd
-.Nd in kernel entropy collection and random number generation
-.Sh SYNOPSIS
-.Cd pseudo-device rnd
+.Nd random number generator
 .Sh DESCRIPTION
 The
+.Pa /dev/random
+and
+.Pa /dev/urandom
+devices generate bytes randomly with uniform distribution.
+Every read from them is independent.
+.Bl -tag -width /dev/urandom
+.It Pa /dev/urandom
+Never blocks.
+.It Pa /dev/random
+Sometimes blocks.
+Will block early at boot if the system's state is known to be
+predictable.
+.El
+.Pp
+Applications should read from
+.Pa /dev/urandom
+when they need randomly generated data, e.g. key material for
+cryptography or seeds for simulations.
+.Pp
+Systems should be engineered to judiciously read at least once from
+.Pa /dev/random
+at boot before running any services that talk to the internet or
+otherwise require cryptography, in order to avoid generating keys
+predictably.
+.Pp
+.Pa /dev/random
+may block at any time, so programs that read from it must be prepared
+to handle blocking.
+Interactive programs that block due to reads from
+.Pa /dev/random
+can be especially frustrating.
+.Pp
+If interrupted by a signal, reads from either
+.Pa /dev/random
+or
+.Pa /dev/urandom
+may return short, so programs that handle signals must be prepared to
+retry reads.
+.Pp
+Writing to either
+.Pa /dev/random
+or
+.Pa /dev/urandom
+influences subsequent output of both devices, guaranteed to take
+effect at next open.
+.Pp
+If you have a coin in your pocket, you can flip it 256 times and feed
+the outputs to
+.Pa /dev/random
+to guarantee your system is in a state that nobody but you and the
+bored security guard watching the surveillance camera in your office
+can guess:
+.Bd -literal -offset abcd
+% echo tthhhhhthhhththtthhhhthtththttth... > /dev/random
+.Ed
+.Pp
+(Sequence generated from a genuine US quarter dollar, guaranteed
+random.)
+.Sh SECURITY MODEL
+The
 .Nm
-pseudo-device has three purposes.
-On read, it returns cryptographically
-strong random data from a generator keyed from the kernel entropy pool.
-On write, data may be added to the entropy pool.
-By ioctl, the behavior of the entropy pool (which sources are used;
-how their entropy is estimated, etc.) may be controlled.
-.Pp
-The kernel uses event timing information collected from many
-devices, and mixes this into an entropy pool.
-This pool is used to
-key a stream generator (the CTR_DRBG generator specified by NIST
-SP 800-90) which is used to generate values returned to userspace when
-the pseudo-device is read.
-.Pp
-The pseudodevice is cloning, which means that each time it is opened,
-a new instance of the stream generator may be created.
-Interposing a stream
-generator between the entropy pool and readers in this manner protects
-readers from each other (each reader's random stream is generated from a
-unique key) and protects all users of the entropy pool from any attack
-which might correlate its successive outputs to each other, such as
-iterative guessing attacks.
+subsystem provides the following security properties against two
+different classes of attackers, provided that there is enough entropy
+from entropy sources not seen by attackers:
+.Bl -bullet -offset abcd
+.It
+An attacker who has seen some outputs and can supply some entropy
+sources' inputs to the operating system cannot predict past or future
+unseen outputs.
+.It
+An attacker who has seen the entire state of the machine cannot predict
+past outputs.
+.El
 .Pp
-Certain programs make very short reads from
-.Pa /dev/urandom
-each time they begin execution.
-One program with this behavior is
-.Xr perl 1 .
-If such a program is run repeatedly (for example from a network
-service or shell script), the resulting repeated keying of the stream
-generator can quickly drain the entropy pool dry.
-As an optimization for such cases, a separate per-CPU instance of
-the stream generator is used to handle reads from
-.Pa /dev/urandom
-which are smaller than the key length of the underlying cipher.
-Any read of a larger size causes an immediate allocation of a
-private instance of the stream generator for the reader.
-Since all stream
-generators are automatically rekeyed upon use when sufficient entropy
-is available, the shared short-request generators do still offer
-some protection against other consumers of
-.Pa /dev/urandom ,
-though less than is provided for consumers making larger requests.
-.Sh USER ACCESS
-User code can obtain random values from the kernel in two ways.
-.Pp
-Reading from
-.Pa /dev/random
-provides information-theoretic properties desirable for some callers:
-it will guarantee that the stream generator never outputs more bits
-than the length of its key, which may in some sense mean that all the
-entropy provided to it by the entropy pool is "preserved" in its output.
-.Pp
-Reading from
-.Pa /dev/random
-may return
-.Er EAGAIN
-(for non-blocking reads), block, or return less data than requested, if
-the pool does not have sufficient entropy
-to provide a new key for the stream generator when sufficient bits have
-been read to require rekeying.
-.Pp
-Reading from
-.Pa /dev/urandom
-will return as many values as requested.
-The stream generator may be
-initially keyed from the entropy pool even if the pool's estimate of
-its own entropy is less than the number of bits in the stream generator's
-key.
-If this occurs, the generator will be rekeyed with fresh entropy
-from the pool as soon as sufficient entropy becomes available.
-The generator will also be rekeyed whenever the pool's entropy estimate
-exceeds the size of the pool's internal state (when the pool "is full").
-.Pp
-In some sense, this data is not as good as reading from
-.Pa /dev/random ,
-for at least two reasons.
-First, the generator may initially be keyed
-from a pool that has never had as many bits of entropy mixed into it as
-there are bits in the generator's key.
-Second, the generator may produce
-many more bits of output than are contained in its own key, though it
-will never produce more output on one key than is allowed by the
-CTR_DRBG specification.
+One
+.Sq output
+means a single read, no matter how short it is.
 .Pp
-However, reading large amounts of data from a single opened instance of
-.Pa /dev/urandom
-will
-.Em not
-deplete the kernel entropy pool, as it would with some other
-implementations.
-This preserves entropy for other callers and will
-produce a more fair distribution of the available entropy over many
-potential readers on the same system.
-.Pp
-Users of these interfaces must carefully consider their application's
-actual security requirements and the characteristics of the system
-on which they are reading from the pseudodevice.
-For many applications, the depletion of the entropy pool caused by the
+.Sq Cannot predict
+means it is conjectured of the cryptography in
+.Fa /dev/random
+that any computationally bounded attacker who tries to distinguish
+outputs from uniform random cannot do more than negligibly better than
+uniform random guessing.
+.Sh ENTROPY
+The operating system contiuously makes observations of hardware
+devices, such as network packet timings, disk seek delays, and
+keystrokes.
+The observations are combined into a seed for a cryptographic
+pseudorandom number generator (PRNG) which is used to generate the
+outputs of both
 .Pa /dev/random
-pseudodevice's continual rekeying of the stream generator will cause
-application behavior (or, perhaps more precisely, nonbehavior) which
-is less secure than relying on the
-.Pa /dev/urandom
-interface, which is guaranteed to rekey the stream generator as often
-as it can.
-.Pp
-Excessive use of
-.Pa /dev/random
-can deplete the entropy pool (or, at least, its estimate of how many
-bits of entropy it "contains") and reduce security for other consumers
-of randomness both in userspace
-.Em and within the kernel .
-Some system administrators may wish therefore to remove the
-.Pa /dev/random
-device node and replace it with a second copy of the node for the nonblocking
-.Pa /dev/urandom
-device.
-.Pp
-In any event, as the Linux manual page notes, one should
-be very suspicious of any application which attempts to read more than
-32 bytes (256 bits) from the blocking
-.Pa /dev/random
-pseudodevice, since no practical cryptographic algorithm in current
-use is believed to have a security strength greater than 256 bits.
+and
+.Pa /dev/urandom .
 .Pp
-Writing to either device node will mix the data written into the
-entropy pool, but will have no effect on the pool's entropy estimate.
-The
-.Xr ioctl 2
-interface to the device may be used -- once only, and only when the
-system is in insecure mode at security level 0 or lower -- to add
-data with an explicit entropy estimate.
-.Sh IOCTL INTERFACE
-Various
-.Xr ioctl 2
-functions are available to control device behavior, gather statistics,
-and add data to the entropy pool.
-These are all defined in the
-.In sys/rnd.h
-file, along with the data types and constants.
-The structures and ioctl functions are also listed below.
-.Sh DATA TYPES
-Each source has a state structure which summarizes the kernel's state
-for that entropy source.
-.Bd -literal -offset indent
-typedef struct {
-        char            name[16];
-        uint32_t       total;
-        uint32_t       type;