1.\" $NetBSD: rnd.4,v 1.10 2002/02/13 08:17:44 ross 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.El 132.Pp 133.Va flags 134is a bitfield. 135.Bl -tag -width RND_FLAG_NO_ESTIMATE 136.It Dv RND_FLAG_NO_ESTIMATE 137Do not assume any entropy is in the timing information. 138.It Dv RND_FLAG_NO_COLLECT 139Do not even add timing information to the pool. 140.El 141.Sh IOCTL 142Various 143.Xr ioctl 2 144functions are available to control device behavior, gather statistics, 145and add data to the entropy pool. These are all defined in the 146.Aq Pa sys/rnd.h 147file, along with the data types and constants. 148.Pp 149.Bl -tag -width RNDADDTOENTCNT 150.It Dv RNDGETENTCNT 151.Pq Li "u_int32_t" 152Return the current entropy count (in bits). 153.It Dv RNDGETSRCNUM 154.Pq Li "rndstat_t" 155.Bd -literal -offset indent 156typedef struct { 157 u_int32_t start; 158 u_int32_t count; 159 rndsource_t source[RND_MAXSTATCOUNT]; 160} rndstat_t; 161.Ed 162.Pp 163Return data for sources, starting at 164.Va start 165and returning at most 166.Va count 167sources. 168.Pp 169The values returned are actual in-kernel snapshots of the entropy 170status for devices. Leaking the internal timing information will 171weaken security. 172.It Dv RNDGETSRCNAME 173.Pq Li "rndstat_name_t" 174.Bd -literal -offset indent 175typedef struct { 176 char name[16]; 177 rndsource_t source; 178} rndstat_name_t; 179.Ed 180.Pp 181Return the device state for a named device. 182.It Dv RNDCTL 183.Pq Li "rndctl_t" 184.Bd -literal -offset indent 185typedef struct { 186 char name[16]; 187 u_int32_t type; 188 u_int32_t flags; 189 u_int32_t mask; 190} rndctl_t; 191.Ed 192.Pp 193Change bits in the device state information. If 194.Va type 195is 0xff, only the device name stored in 196.Va name 197is used. If it is any other value, all devices of type 198.Va type 199are altered. This allows all network interfaces to be disabled for 200entropy collection with one call, for example. 201The 202.Va flags 203and 204.Va mask 205work together to change flag bits. The 206.Va mask 207field specifies which bits in 208.Va flags 209are to be set or cleared. 210.It Dv RNDADDDATA 211.Pq Li "rnddata_t" 212.Bd -literal -offset indent 213typedef struct { 214 u_int32_t len; 215 u_int32_t entropy; 216 u_char data[RND_POOLWORDS * 4]; 217} rnddata_t; 218.Ed 219.El 220.Sh FILES 221.Bl -tag -width /dev/urandomx -compact 222.It Pa /dev/random 223Returns ``good'' values only 224.It Pa /dev/urandom 225Always returns data, degenerates to a pseudo-random generator 226.El 227.Sh SEE ALSO 228.Xr rndctl 8 , 229.Xr rnd 9 230.Sh HISTORY 231The random device was first made available in 232.Nx 1.3 . 233.Sh AUTHORS 234This implementation was written by Michael Graff \*[Lt]explorer@flame.org\*[Gt] 235using ideas and algorithms gathered from many sources, including 236the driver written by Ted Ts'o. 237