.\" $NetBSD: rnd.4,v 1.5 1999/03/16 01:19:17 garbled Exp $ .\" .\" Copyright (c) 1997 Michael Graff .\" 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. .\" 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. .\" .Dd October 12, 1997 .Dt RND 4 .Os .Sh NAME .Nm rnd .Nd in kernel entropy collection and random number generation .Sh SYNOPSIS .Cd pseudo-device rnd .Sh DESCRIPTION The .Nm pseudo-device uses event timing information collected from many devices, and mixes this into an entropy pool. This pool is stirred with a cryptographically strong hash function when data is extracted from the pool. .Sh INTERNAL ENTROPY POOL MANAGEMENT When a hardware event occurs (such as completion of a hard drive transfer or an interrupt from a network device) a timestamp is generated. This timestamp is compared to the previous timestamp recorded for the device, and the first, second, and third order differentials are calculated. .Pp If any of these differentials is zero, no entropy is assumed to have been gathered. If all are non-zero, one bit is assumed. Next, data is mixed into the entropy pool using an LFSR (linear feedback shift register). .Pp To extract data from the entropy pool, a cryptographically strong hash function is used. The output of this hash is mixed back into the pool using the LFSR, and then folded in half before being returned to the caller. .Pp Mixing the actual hash into the pool causes the next extraction to return a different value, even if no timing events were added to the pool. Folding the data in half prevents the caller to derive the actual hash of the pool, preventing some attacks. .Sh USER ACCESS User code can obtain random values from the kernel in two ways. .Pp Reading from .Pa /dev/random will only return values while sufficient entropy exists in the internal pool. When sufficent entropy does not exist, EAGAIN is returned for non-blocking reads, or the read will block for blocking reads. .Pp Reading from .Pa /dev/urandom will return as many values as requested, even when the entropy pool is empty. This data is not as good as reading from .Pa /dev/random since when the pool is empty, data is still returned, degenerating to a pseudo-random generator. .Pp Writing to either device will mix the data written into the pool using the LFSR as above, without modifying the entropy estimation for the pool. .Sh RANDOM SOURCE STRUCTURE Each source has a state structure which the kernel uses to hold the timing information and other state for that source. .Bd -literal -offset indent typedef struct { char name[16]; u_int32_t last_time; u_int32_t last_delta; u_int32_t last_delta2; u_int32_t total; u_int32_t type; u_int32_t flags; } rndsource_t; .Ed .Pp This structure holds the internal representation of a device's timing state. The .Va name field holes the device name, as known to the kernel. The .Va last_time entry is the timestamp of the last time this device generated an event. It is for internal use only, and not in any specific representation. The .Va last_delta and .Va last_delta2 fields hold the last first- and second-order deltas. The .Va total field holds a count of how many bits this device has potentially generated. This is not the same as how many bits were used from it. The .Va type field holds the device type. .Pp .Bl -tag -width RND_TYPE_DISK Currently, these types are defined: .It Dv RND_TYPE_DISK The device is a physical hard drive. .It Dv RND_TYPE_NET The device is a network interface. By default, timing information is collected from this source type, but entropy is not estimated. .It Dv RND_TYPE_TAPE The device is a tape device. .It Dv RND_TYPE_TTY The device is a terminal, mouse, or other user input device. .El .Pp .Va flags is a bitfield. .Bl -tag -width RND_FLAG_NO_ESTIMATE .It Dv RND_FLAG_NO_ESTIMATE Do not assume any entropy is in the timing information. .It Dv RND_FLAG_NO_COLLECT Do not even add timing information to the pool. .El .Sh IOCTL 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 .Aq Pa sys/rnd.h file, along with the data types and constants. .Pp .Bl -tag -width RNDADDTOENTCNT .It Dv RNDGETENTCNT .Pq Li "u_int32_t" Return the current entropy count (in bits). .It Dv RNDGETSRCNUM .Pq Li "rndstat_t" .Bd -literal -offset indent typedef struct { u_int32_t start; u_int32_t count; rndsource_t source[RND_MAXSTATCOUNT]; } rndstat_t; .Ed .Pp Return data for sources, starting at .Va start and returning at most .Va count sources. .Pp The values returned are actual in-kernel snapshots of the entropy status for devices. Leaking the internal timing information will weaken security. .It Dv RNDGETSRCNAME .Pq Li "rndstat_name_t" .Bd -literal -offset indent typedef struct { char name[16]; rndsource_t source; } rndstat_name_t; .Ed .Pp Return the device state for a named device. .It Dv RNDCTL .Pq Li "rndctl_t" .Bd -literal -offset indent typedef struct { char name[16]; u_int32_t type; u_int32_t flags; u_int32_t mask; } rndctl_t; .Ed .Pp Change bits in the device state information. If .Va type is 0xff, only the device name stored in .Va name is used. If it is any other value, all devices of type .Va type are altered. This allows all network interfaces to be disabled for entropy collection with one call, for example. The .Va flags and .Va mask work together to change flag bits. The .Va mask field specifies which bits in .Va flags are to be set or cleared. .It Dv RNDADDDATA .Pq Li "rnddata_t" .Bd -literal -offset indent typedef struct { u_int32_t len; u_int32_t entropy; u_char data[RND_POOLWORDS * 4]; } rnddata_t; .Ed .El .Sh FILES .Bl -tag -width /dev/urandomx -compact .It Pa /dev/random Returns ``good'' values only .It Pa /dev/urandom Always returns data, degenerates to a pseudo-random generator .El .Sh HISTORY The random device was first made available in .Nx 1.3 . .Sh AUTHOR This implementation was written by Michael Graff using ideas and algorithms gathered from many sources, including the driver written by Ted Ts'o. .Sh SEE ALSO .Xr rndctl 8 , .Xr rnd 9 .