1.\" $NetBSD: rnd.4,v 1.18 2011/12/17 21:21:59 wiz 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 December 17, 2011 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 has three purposes. 41On read, it returns cryptographically 42strong random data from a generator keyed from the kernel entropy pool. 43On write, data may be added to the entropy pool. 44By ioctl, the behavior of the entropy pool (which sources are used; 45how their entropy is estimated, etc.) may be controlled. 46.Pp 47The kernel uses event timing information collected from many 48devices, and mixes this into an entropy pool. 49This pool is used to 50key a stream generator (the CTR_DRBG generator specified by NIST 51SP 800-90) which is used to generate values returned to userspace when 52the pseudo-device is read. 53.Pp 54The pseudodevice is cloning, which means that each time it is opened, 55a new instance of the stream generator is created. 56Interposing a stream 57generator between the entropy pool and readers in this manner protects 58readers from each other (each reader's random stream is generated from a 59unique key) and protects all users of the entropy pool from any attack 60which might correlate its successive outputs to each other, such as 61iterative guessing attacks. 62.Sh USER ACCESS 63User code can obtain random values from the kernel in two ways. 64.Pp 65Reading from 66.Pa /dev/random 67provides information-theoretic properties desirable for some callers: 68it will guarantee that the stream generator never outputs more bits 69than the length of its key, which may in some sense mean that all the 70entropy provided to it by the entropy pool is "preserved" in its output. 71.Pp 72Reading from 73.Pa /dev/random 74may return 75.Er EAGAIN 76(for non-blocking reads), block, or return less data than requested, if 77the pool does not have sufficient entropy 78to provide a new key for the stream generator when sufficient bits have 79been read to require rekeying. 80.Pp 81Reading from 82.Pa /dev/urandom 83will return as many values as requested. 84The stream generator may be 85initially keyed from the entropy pool even if the pool's estimate of 86its own entropy is less than the number of bits in the stream generator's 87key. 88If this occurs, the generator will be rekeyed with fresh entropy 89from the pool as soon as sufficient entropy becomes available. 90The generator will also be rekeyed whenever the pool's entropy estimate 91exceeds the size of the pool's internal state (when the pool "is full"). 92.Pp 93In some sense, this data is not as good as reading from 94.Pa /dev/random , 95for at least two reasons. 96First, the generator may initially be keyed 97from a pool that has never had as many bits of entropy mixed into it as 98there are bits in the generator's key. 99Second, the generator may produce 100many more bits of output than are contained in its own key, though it 101will never produce more output on one key than is allowed by the 102CTR_DRBG specification. 103.Pp 104However, reading large amounts of data from a single opened instance of 105.Pa /dev/urandom 106will 107.Em not 108deplete the kernel entropy pool, as it would with some other 109implementations. 110This preserves entropy for other callers and will 111produce a more fair distribution of the available entropy over many 112potential readers on the same system. 113.Pp 114Users of these interfaces must carefully consider their application's 115actual security requirements and the characteristics of the system 116on which they are reading from the pseudodevice. 117For many applications, the depletion of the entropy pool caused by the 118.Pa /dev/random 119pseudodevice's continual rekeying of the stream generator will cause 120application behavior (or, perhaps more precisely, nonbehavior) which 121is less secure than relying on the 122.Pa /dev/urandom 123interface, which is guaranteed to rekey the stream generator as often 124as it can. 125.Pp 126Excessive use of 127.Pa /dev/random 128can deplete the entropy pool (or, at least, its estimate of how many 129bits of entropy it "contains") and reduce security for other consumers 130of randomness both in userspace 131.Em and within the kernel. 132Some system administrators may wish therefore to remove the 133.Pa /dev/random 134device node and replace it with a second copy of the node for the nonblocking 135.Pa /dev/urandom 136device. 137.Pp 138In any event, as the Linux manual page notes, one should 139be very suspicious of any application which attempts to read more than 14032 bytes (256 bits) from the blocking 141.Pa /dev/random 142pseudodevice, since no practical cryptographic algorithm in current 143use is believed to have a security strength greater than 256 bits. 144.Pp 145Writing to either device node will mix the data written into the 146entropy pool, but will have no effect on the pool's entropy estimate. 147The 148.Xr ioctl 2 149interface to the device may be used -- once only, and only when the 150system is in insecure mode at security level 0 or lower -- to add 151data with an explicit entropy estimate. 152.Sh IOCTL INTERFACE 153Various 154.Xr ioctl 2 155functions are available to control device behavior, gather statistics, 156and add data to the entropy pool. 157These are all defined in the 158.In sys/rnd.h 159file, along with the data types and constants. 160The structures and ioctl functions are also listed below. 161.Sh DATA TYPES 162Each source has a state structure which summarizes the kernel's state 163for that entropy source. 164.Bd -literal -offset indent 165typedef struct { 166 char name[16]; 167 uint32_t total; 168 uint32_t type; 169 uint32_t flags; 170} rndsource_t; 171.Ed 172The 173.Va name 174field holds the device name, as known to the kernel. 175The 176.Va type 177field holds the device type. 178.Pp 179Currently, these types are defined: 180.Bl -tag -width RND_TYPE_DISK 181.It Dv RND_TYPE_DISK 182The device is a physical hard drive. 183.It Dv RND_TYPE_NET 184The device is a network interface. 185By default, timing information is 186collected from this source type, but entropy is not estimated. 187.It Dv RND_TYPE_TAPE 188The device is a tape device. 189.It Dv RND_TYPE_TTY 190The device is a terminal, mouse, or other user input device. 191.It Dv RND_TYPE_RNG 192The device is a random number generator. 193.El 194.Pp 195.Va flags 196is a bitfield. 197.Bl -tag -width RND_FLAG_NO_ESTIMATE 198.It Dv RND_FLAG_NO_ESTIMATE 199Do not assume any entropy is in the timing information. 200.It Dv RND_FLAG_NO_COLLECT 201Do not even add timing information to the pool. 202.El 203.Pp 204.Bl -tag -width RNDADDTOENTCNT 205.It Dv RNDGETENTCNT 206.Pq Li "uint32_t" 207Return the current entropy count (in bits). 208.It Dv RNDGETPOOLSTAT 209.Pq Li "rndpoolstat_t" 210.Bd -literal -offset indent 211typedef struct 212{ 213 uint32_t poolsize; 214 uint32_t threshold; 215 uint32_t maxentropy; 216 217 uint32_t added; 218 uint32_t curentropy; 219 uint32_t removed; 220 uint32_t discarded; 221 uint32_t generated; 222} rndpoolstat_t; 223.Ed 224.Pp 225Return statistics on the current state of the random collection pool. 226.It Dv RNDGETSRCNUM 227.Pq Li "rndstat_t" 228.Bd -literal -offset indent 229typedef struct { 230 uint32_t start; 231 uint32_t count; 232 rndsource_t source[RND_MAXSTATCOUNT]; 233} rndstat_t; 234.Ed 235.Pp 236Return data for sources, starting at 237.Va start 238and returning at most 239.Va count 240sources. 241.Pp 242The values returned are actual in-kernel snapshots of the entropy 243status for devices. 244Leaking the internal timing information will weaken security. 245.It Dv RNDGETSRCNAME 246.Pq Li "rndstat_name_t" 247.Bd -literal -offset indent 248typedef struct { 249 char name[16]; 250 rndsource_t source; 251} rndstat_name_t; 252.Ed 253.Pp 254Return the device state for a named device. 255.It Dv RNDCTL 256.Pq Li "rndctl_t" 257.Bd -literal -offset indent 258typedef struct { 259 char name[16]; 260 uint32_t type; 261 uint32_t flags; 262 uint32_t mask; 263} rndctl_t; 264.Ed 265.Pp 266Change bits in the device state information. 267If 268.Va type 269is 0xff, only the device name stored in 270.Va name 271is used. 272If it is any other value, all devices of type 273.Va type 274are altered. 275This allows all network interfaces to be disabled for 276entropy collection with one call, for example. 277The 278.Va flags 279and 280.Va mask 281work together to change flag bits. 282The 283.Va mask 284field specifies which bits in 285.Va flags 286are to be set or cleared. 287.It Dv RNDADDDATA 288.Pq Li "rnddata_t" 289.Bd -literal -offset indent 290typedef struct { 291 uint32_t len; 292 uint32_t entropy; 293 u_char data[RND_SAVEWORDS * sizeof(uint32_t)]; 294} rnddata_t; 295.Ed 296.El 297.Sh FILES 298.Bl -tag -width /dev/urandomx -compact 299.It Pa /dev/random 300Returns ``good'' values only 301.It Pa /dev/urandom 302Always returns data. 303.El 304.Sh SEE ALSO 305.Xr rndctl 8 , 306.Xr rnd 9 307.Sh HISTORY 308The random device was first made available in 309.Nx 1.3 . 310.Sh AUTHORS 311This implementation was written by Thor Lancelot Simon. 312It retains 313some code (particularly for the ioctl interface) from the earlier 314implementation by Michael Graff 315.Aq explorer@flame.org . 316