1.\" $NetBSD: rnd.4,v 1.16 2010/03/22 18:58:31 joerg 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 February 22, 2009 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. 42This pool is stirred with a cryptographically strong hash function 43when data is extracted from 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. 48This timestamp is compared to the previous timestamp 49recorded for the device, and the first, second, and third order 50differentials are calculated. 51.Pp 52If any of these differentials is zero, no entropy is assumed to 53have been gathered. 54If all are non-zero, one bit is assumed. 55Next, data is mixed into the entropy pool using an LFSR (linear 56feedback shift register). 57.Pp 58To extract data from the entropy pool, a cryptographically strong hash 59function is used. 60The output of this hash is mixed back into the pool using the LFSR, 61and then folded in half before being returned to the caller. 62.Pp 63Mixing the actual hash into the pool causes the next extraction to 64return a different value, even if no timing events were added to the 65pool. 66Folding the data in half prevents the caller to derive the 67actual hash of the pool, preventing some attacks. 68.Sh USER ACCESS 69User code can obtain random values from the kernel in two ways. 70.Pp 71Reading from 72.Pa /dev/random 73will only return values while sufficient entropy exists in the 74internal pool. 75When sufficient entropy does not exist, 76.Er EAGAIN 77is returned for non-blocking reads, or the read will block for 78blocking reads. 79.Pp 80Reading from 81.Pa /dev/urandom 82will return as many values as requested, even when the entropy pool is 83empty. 84This data is not as good as reading from 85.Pa /dev/random 86since when the pool is empty, data is still returned, degenerating to a 87pseudo-random generator. 88.Pp 89Writing to either device will mix the data written into the pool using 90the LFSR as above, without modifying the entropy estimation for the 91pool. 92.Sh RANDOM SOURCE STRUCTURE 93Each source has a state structure which the kernel uses to hold the 94timing information and other state for that source. 95.Bd -literal -offset indent 96typedef struct { 97 char name[16]; 98 uint32_t last_time; 99 uint32_t last_delta; 100 uint32_t last_delta2; 101 uint32_t total; 102 uint32_t type; 103 uint32_t flags; 104} rndsource_t; 105.Ed 106.Pp 107This structure holds the internal representation of a device's timing 108state. 109The 110.Va name 111field holes the device name, as known to the kernel. 112The 113.Va last_time 114entry is the timestamp of the last time this device generated an 115event. 116It is for internal use only, and not in any specific representation. 117The 118.Va last_delta 119and 120.Va last_delta2 121fields hold the last first- and second-order deltas. 122The 123.Va total 124field holds a count of how many bits this device has potentially 125generated. 126This is not the same as how many bits were used from it. 127The 128.Va type 129field holds the device type. 130.Pp 131Currently, these types are defined: 132.Bl -tag -width RND_TYPE_DISK 133.It Dv RND_TYPE_DISK 134The device is a physical hard drive. 135.It Dv RND_TYPE_NET 136The device is a network interface. 137By default, timing information is 138collected from this source type, but entropy is not estimated. 139.It Dv RND_TYPE_TAPE 140The device is a tape device. 141.It Dv RND_TYPE_TTY 142The device is a terminal, mouse, or other user input device. 143.It Dv RND_TYPE_RNG 144The device is a random number generator. 145.El 146.Pp 147.Va flags 148is a bitfield. 149.Bl -tag -width RND_FLAG_NO_ESTIMATE 150.It Dv RND_FLAG_NO_ESTIMATE 151Do not assume any entropy is in the timing information. 152.It Dv RND_FLAG_NO_COLLECT 153Do not even add timing information to the pool. 154.El 155.Sh IOCTL 156Various 157.Xr ioctl 2 158functions are available to control device behavior, gather statistics, 159and add data to the entropy pool. 160These are all defined in the 161.In sys/rnd.h 162file, along with the data types and constants. 163.Pp 164.Bl -tag -width RNDADDTOENTCNT 165.It Dv RNDGETENTCNT 166.Pq Li "uint32_t" 167Return the current entropy count (in bits). 168.It Dv RNDGETPOOLSTAT 169.Pq Li "rndpoolstat_t" 170.Bd -literal -offset indent 171typedef struct 172{ 173 uint32_t poolsize; 174 uint32_t threshold; 175 uint32_t maxentropy; 176 177 uint32_t added; 178 uint32_t curentropy; 179 uint32_t removed; 180 uint32_t discarded; 181 uint32_t generated; 182} rndpoolstat_t; 183.Ed 184.Pp 185Return statistics on the current state of the random collection pool. 186.It Dv RNDGETSRCNUM 187.Pq Li "rndstat_t" 188.Bd -literal -offset indent 189typedef struct { 190 uint32_t start; 191 uint32_t count; 192 rndsource_t source[RND_MAXSTATCOUNT]; 193} rndstat_t; 194.Ed 195.Pp 196Return data for sources, starting at 197.Va start 198and returning at most 199.Va count 200sources. 201.Pp 202The values returned are actual in-kernel snapshots of the entropy 203status for devices. 204Leaking the internal timing information will weaken security. 205.It Dv RNDGETSRCNAME 206.Pq Li "rndstat_name_t" 207.Bd -literal -offset indent 208typedef struct { 209 char name[16]; 210 rndsource_t source; 211} rndstat_name_t; 212.Ed 213.Pp 214Return the device state for a named device. 215.It Dv RNDCTL 216.Pq Li "rndctl_t" 217.Bd -literal -offset indent 218typedef struct { 219 char name[16]; 220 uint32_t type; 221 uint32_t flags; 222 uint32_t mask; 223} rndctl_t; 224.Ed 225.Pp 226Change bits in the device state information. 227If 228.Va type 229is 0xff, only the device name stored in 230.Va name 231is used. 232If it is any other value, all devices of type 233.Va type 234are altered. 235This allows all network interfaces to be disabled for 236entropy collection with one call, for example. 237The 238.Va flags 239and 240.Va mask 241work together to change flag bits. 242The 243.Va mask 244field specifies which bits in 245.Va flags 246are to be set or cleared. 247.It Dv RNDADDDATA 248.Pq Li "rnddata_t" 249.Bd -literal -offset indent 250typedef struct { 251 uint32_t len; 252 uint32_t entropy; 253 u_char data[RND_POOLWORDS * 4]; 254} rnddata_t; 255.Ed 256.El 257.Sh FILES 258.Bl -tag -width /dev/urandomx -compact 259.It Pa /dev/random 260Returns ``good'' values only 261.It Pa /dev/urandom 262Always returns data, degenerates to a pseudo-random generator 263.El 264.Sh SEE ALSO 265.Xr rndctl 8 , 266.Xr rnd 9 267.Sh HISTORY 268The random device was first made available in 269.Nx 1.3 . 270.Sh AUTHORS 271This implementation was written by Michael Graff \*[Lt]explorer@flame.org\*[Gt] 272using ideas and algorithms gathered from many sources, including 273the driver written by Ted Ts'o. 274