1.\" $NetBSD: rnd.4,v 1.3 1997/11/04 05:50:54 explorer 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 NetBSD 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 sufficent 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 tyfl; 97} rndsource_t; 98.Ed 99.Pp 100This structure holds the internal representation of a device's timing 101state. The 102.Va name 103field holes the device name, as known to the kernel. The 104.Va last_time 105entry is the timestamp of the last time this device generated an 106event. It is for internal use only, and not in any specific 107representation. The 108.Va last_delta 109and 110.Va last_delta2 111fields hold the last first- and second-order deltas. The 112.Va total 113field holds a count of how many bits this device has potentially 114generated. This is not the same as how many bits were used from it. 115The 116.Va tyfl 117field holds the device flags as well as the device type. The lower 118eight bits hold the device type, and the upper 24 bits are flags 119represented as a bitfield. 120.Pp 121.Bl -tag -width RND_TYPE_DISK 122Currently, these types are defined: 123.It Dv RND_TYPE_DISK 124The device is a physical hard drive. 125.It Dv RND_TYPE_NET 126The device is a network interface. By default, timing information is 127collected from this source type, but entropy is not estimated. 128.It Dv RND_TYPE_TAPE 129The device is a tape device. 130.It Dv RND_TYPE_TTY 131The device is a terminal, mouse, or other user input device. 132.El 133.Pp 134A device can have these flags set: 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 RNDSETENTCNT 154.Pq Li "u_int32_t" 155Sets the internal entropy count (in bits) to the value given. This 156should be used with caution, as artifically increasing the entropy 157count may lead to weakened security. 158.It Dv RNDADDTOENTCNT 159.Pq Li "u_int32_t" 160Increase the entropy count (in bits) by the given amount. This should 161be used with caution, as artifically increasing the entropy count may 162lead to weakened security. 163.It Dv RNDGETPOOL 164.Pq Li "u_char *" 165Return the actual contents of the entropy pool. The area pointed to 166in this call should be 167.Va "RND_POOLWORDS * 4" 168bytes long. As this is the actual contents of the entropy pool and 169not hashes of it, it is extremely important to handle this data with 170care. Leaking any part of this pool would allow an attacker to 171predict future random values. 172.It Dv RNDGETSRCNUM 173.Pq Li "rndstat_t" 174.Bd -literal -offset indent 175typedef struct { 176 u_int32_t start; 177 u_int32_t count; 178 rndsource_t source[RND_MAXSTATCOUNT]; 179} rndstat_t; 180.Ed 181.Pp 182Return data for sources, starting at 183.Va start 184and returning at most 185.Va count 186sources. 187.Pp 188The values returned are actual in-kernel snapshots of the entropy 189status for devices. Leaking the internal timing information will 190weaken security. 191.It Dv RNDGETSRCNAME 192.Pq Li "rndstat_name_t" 193.Bd -literal -offset indent 194typedef struct { 195 char name[16]; 196 rndsource_t source; 197} rndstat_name_t; 198.Ed 199.Pp 200Return the device state for a named device. 201.It Dv RNDCTL 202.Pq Li "rndctl_t" 203.Bd -literal -offset indent 204typedef struct { 205 char name[16]; 206 u_int32_t type; 207 u_int32_t flags; 208 u_int32_t mask; 209} rndctl_t; 210.Ed 211.Pp 212Change bits in the device state information. If 213.Va type 214is 0xff, only the device name stored in 215.Va name 216is used. If it is any other value, all devices of type 217.Va type 218are altered. This allows all network interfaces to be disabled for 219entropy collection with one call, for example. 220The 221.Va flags 222and 223.Va mask 224work together to change flag bits. The 225.Va mask 226field specifies which bits in 227.Va flags 228are to be set or cleared. 229.It Dv RNDADDDATA 230.Pq Li "rnddata_t" 231.Bd -literal -offset indent 232typedef struct { 233 u_int32_t len; 234 u_int32_t entropy; 235 u_char data[RND_POOLWORDS * 4]; 236} rnddata_t; 237.Ed 238.El 239.Sh FILES 240.Bl -tag -width /dev/urandomx -compact 241.It Pa /dev/random 242Returns ``good'' values only 243.It Pa /dev/urandom 244Always returns data, degenerates to a pseudo-random generator 245.El 246.Sh HISTORY 247The random device was first made available in 248.Nx 1.3 . 249.Sh AUTHOR 250This implementation was written by Michael Graff <explorer@flame.org> 251using ideas and algorithms gathered from many sources, including 252the driver written by Ted Ts'o. 253.Sh BUGS 254This system is considered experimental in 255.Nx 1.3 . 256.Sh SEE ALSO 257.Xr rndctl 8 , 258.Xr rnd 9 . 259