1.\" $NetBSD: rnd.4,v 1.11 2002/08/20 00:48:31 enami Exp $ 2.\" 3.\" Copyright (c) 1997 Michael Graff 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. The name of the author may not be used to endorse or promote products 15.\" derived from this software without specific prior written permission. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 18.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 19.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 20.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 21.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 22.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 23.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 24.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 25.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 26.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 27.\" SUCH DAMAGE. 28.\" 29.Dd October 12, 1997 30.Dt RND 4 31.Os 32.Sh NAME 33.Nm rnd 34.Nd in kernel entropy collection and random number generation 35.Sh SYNOPSIS 36.Cd pseudo-device rnd 37.Sh DESCRIPTION 38The 39.Nm 40pseudo-device uses event timing information collected from many 41devices, and mixes this into an entropy pool. This pool is stirred 42with a cryptographically strong hash function when data is extracted 43from the pool. 44.Sh INTERNAL ENTROPY POOL MANAGEMENT 45When a hardware event occurs (such as completion of a hard drive 46transfer or an interrupt from a network device) a timestamp is 47generated. This timestamp is compared to the previous timestamp 48recorded for the device, and the first, second, and third order 49differentials are calculated. 50.Pp 51If any of these differentials is zero, no entropy is assumed to 52have been gathered. If all are non-zero, one bit is assumed. 53Next, data is mixed into the entropy pool using an LFSR (linear 54feedback shift register). 55.Pp 56To extract data from the entropy pool, a cryptographically strong hash 57function is used. The output of this hash is mixed back into the pool 58using the LFSR, and then folded in half before being returned to the 59caller. 60.Pp 61Mixing the actual hash into the pool causes the next extraction to 62return a different value, even if no timing events were added to the 63pool. Folding the data in half prevents the caller to derive the 64actual hash of the pool, preventing some attacks. 65.Sh USER ACCESS 66User code can obtain random values from the kernel in two ways. 67.Pp 68Reading from 69.Pa /dev/random 70will only return values while sufficient entropy exists in the 71internal pool. When sufficient entropy does not exist, EAGAIN is 72returned for non-blocking reads, or the read will block for blocking 73reads. 74.Pp 75Reading from 76.Pa /dev/urandom 77will return as many values as requested, even when the entropy pool is 78empty. This data is not as good as reading from 79.Pa /dev/random 80since when the pool is empty, data is still returned, degenerating to a 81pseudo-random generator. 82.Pp 83Writing to either device will mix the data written into the pool using 84the LFSR as above, without modifying the entropy estimation for the 85pool. 86.Sh RANDOM SOURCE STRUCTURE 87Each source has a state structure which the kernel uses to hold the 88timing information and other state for that source. 89.Bd -literal -offset indent 90typedef struct { 91 char name[16]; 92 u_int32_t last_time; 93 u_int32_t last_delta; 94 u_int32_t last_delta2; 95 u_int32_t total; 96 u_int32_t type; 97 u_int32_t flags; 98} rndsource_t; 99.Ed 100.Pp 101This structure holds the internal representation of a device's timing 102state. The 103.Va name 104field holes the device name, as known to the kernel. The 105.Va last_time 106entry is the timestamp of the last time this device generated an 107event. It is for internal use only, and not in any specific 108representation. The 109.Va last_delta 110and 111.Va last_delta2 112fields hold the last first- and second-order deltas. The 113.Va total 114field holds a count of how many bits this device has potentially 115generated. This is not the same as how many bits were used from it. 116The 117.Va type 118field holds the device type. 119.Pp 120.Bl -tag -width RND_TYPE_DISK 121Currently, these types are defined: 122.It Dv RND_TYPE_DISK 123The device is a physical hard drive. 124.It Dv RND_TYPE_NET 125The device is a network interface. By default, timing information is 126collected from this source type, but entropy is not estimated. 127.It Dv RND_TYPE_TAPE 128The device is a tape device. 129.It Dv RND_TYPE_TTY 130The device is a terminal, mouse, or other user input device. 131.It Dv RND_TYPE_RNG 132The device is a random number generator. 133.El 134.Pp 135.Va flags 136is a bitfield. 137.Bl -tag -width RND_FLAG_NO_ESTIMATE 138.It Dv RND_FLAG_NO_ESTIMATE 139Do not assume any entropy is in the timing information. 140.It Dv RND_FLAG_NO_COLLECT 141Do not even add timing information to the pool. 142.El 143.Sh IOCTL 144Various 145.Xr ioctl 2 146functions are available to control device behavior, gather statistics, 147and add data to the entropy pool. These are all defined in the 148.Aq Pa sys/rnd.h 149file, along with the data types and constants. 150.Pp 151.Bl -tag -width RNDADDTOENTCNT 152.It Dv RNDGETENTCNT 153.Pq Li "u_int32_t" 154Return the current entropy count (in bits). 155.It Dv RNDGETSRCNUM 156.Pq Li "rndstat_t" 157.Bd -literal -offset indent 158typedef struct { 159 u_int32_t start; 160 u_int32_t count; 161 rndsource_t source[RND_MAXSTATCOUNT]; 162} rndstat_t; 163.Ed 164.Pp 165Return data for sources, starting at 166.Va start 167and returning at most 168.Va count 169sources. 170.Pp 171The values returned are actual in-kernel snapshots of the entropy 172status for devices. Leaking the internal timing information will 173weaken security. 174.It Dv RNDGETSRCNAME 175.Pq Li "rndstat_name_t" 176.Bd -literal -offset indent 177typedef struct { 178 char name[16]; 179 rndsource_t source; 180} rndstat_name_t; 181.Ed 182.Pp 183Return the device state for a named device. 184.It Dv RNDCTL 185.Pq Li "rndctl_t" 186.Bd -literal -offset indent 187typedef struct { 188 char name[16]; 189 u_int32_t type; 190 u_int32_t flags; 191 u_int32_t mask; 192} rndctl_t; 193.Ed 194.Pp 195Change bits in the device state information. If 196.Va type 197is 0xff, only the device name stored in 198.Va name 199is used. If it is any other value, all devices of type 200.Va type 201are altered. This allows all network interfaces to be disabled for 202entropy collection with one call, for example. 203The 204.Va flags 205and 206.Va mask 207work together to change flag bits. The 208.Va mask 209field specifies which bits in 210.Va flags 211are to be set or cleared. 212.It Dv RNDADDDATA 213.Pq Li "rnddata_t" 214.Bd -literal -offset indent 215typedef struct { 216 u_int32_t len; 217 u_int32_t entropy; 218 u_char data[RND_POOLWORDS * 4]; 219} rnddata_t; 220.Ed 221.El 222.Sh FILES 223.Bl -tag -width /dev/urandomx -compact 224.It Pa /dev/random 225Returns ``good'' values only 226.It Pa /dev/urandom 227Always returns data, degenerates to a pseudo-random generator 228.El 229.Sh SEE ALSO 230.Xr rndctl 8 , 231.Xr rnd 9 232.Sh HISTORY 233The random device was first made available in 234.Nx 1.3 . 235.Sh AUTHORS 236This implementation was written by Michael Graff \*[Lt]explorer@flame.org\*[Gt] 237using ideas and algorithms gathered from many sources, including 238the driver written by Ted Ts'o. 239