share/man/man4/rnd.4

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