1.\" $NetBSD: rnd.9,v 1.25 2015/04/13 22:23:54 riastradh Exp $ 2.\" 3.\" Copyright (c) 1997 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This documentation is derived from text contributed to The NetBSD 7.\" Foundation by S.P.Zeidler (aka stargazer). 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd August 10, 2014 31.Dt RND 9 32.Os 33.Sh NAME 34.Nm RND , 35.Nm rnd_attach_source , 36.Nm rnd_detach_source , 37.Nm rnd_add_data , 38.Nm rnd_add_uint32 39.Nd functions to make a device available for entropy collection 40.Sh SYNOPSIS 41.In sys/rndsource.h 42.Ft void 43.Fn rnd_attach_source "krndsource_t *rnd_source" "char *devname" "uint32_t source_type" "uint32_t flags" 44.Ft void 45.Fn rnd_detach_source "krndsource_t *rnd_source" 46.Ft void 47.Fn rnd_add_data "krndsource_t *rnd_source" "void *data" "uint32_t len" "uint32_t entropy" 48.Ft void 49.Fn rnd_add_uint32 "krndsource_t *rnd_source" "uint32_t datum" 50.Sh DESCRIPTION 51These 52.Nm 53functions make a device available for entropy collection for 54the kernel entropy pool, which provides key material for the 55.Xr cprng 9 56and 57.Xr rnd 4 58.Pa ( /dev/random ) 59interfaces. 60.Pp 61Ideally the first argument 62.Fa rnd_source 63of these functions gets included in the devices' entity struct, 64but any means to permanently (statically) attach one such argument 65to one incarnation of the device is ok. 66Do not share 67.Fa rnd_source 68structures between two devices. 69.Pp 70.Bl -tag -width 8n 71.It Fn rnd_attach_source "krndsource_t *rnd_source" "char *devname" "uint32_t source_type" "uint32_t flags" 72This function announces the availability of a device for entropy collection. 73It must be called before the source struct pointed to by 74.Fa rnd_source 75is used in any of the following functions. 76.Pp 77.Fa devname 78is the name of the device. 79It is used to print a message (if the kernel is compiled with 80``options RND_VERBOSE'') and also for status information printed with 81.Xr rndctl 8 . 82.Pp 83.Fa source_type 84is 85.Dv RND_TYPE_NET 86for network devices, 87.Dv RND_TYPE_DISK 88for physical disks, 89.Dv RND_TYPE_TAPE 90for a tape drive, 91.Dv RND_TYPE_TTY 92for a tty, 93.Dv RND_TYPE_RNG 94for a random number generator, and 95.Dv RND_TYPE_ENV 96for an environment sensor. 97.Dv RND_TYPE_UNKNOWN 98is not to be used as a type. 99It is used internally to the rnd system. 100.Pp 101.Fa flags 102are the logical OR of 103.Dv RND_FLAG_COLLECT_VALUE 104(mix data provided by this source into the pool) 105.Dv RND_FLAG_COLLECT_TIME 106(mix timestamps from this source into the pool) 107.Dv RND_FLAG_ESTIMATE_VALUE 108(use a delta estimator to count bits of entropy from this source's data towards 109the pool estimate) 110.Dv RND_FLAG_ESTIMATE_TIME 111(use a delta estimator to count bits of entropy from this source's timestamps 112towards the pool estimate). 113For many devices, 114.Dv RND_FLAG_DEFAULT 115.Dv ( RND_FLAG_COLLECT_VALUE | RND_FLAG_COLLECT_TIME | RND_FLAG_ESTIMATE_TIME ) 116is the best choice. 117Note that devices of type 118.Dv RND_TYPE_NET 119default to 120.Dv RND_FLAG_COLLECT_VALUE | RND_FLAG_COLLECT_TIME 121(no entropy counted). 122.Pp 123.It Fn rnd_detach_source "krndsource_t *rnd_source" 124This function disconnects the device from entropy collection. 125.It Fn rnd_add_uint32 "krndsource_t *rnd_source" "uint32_t datum" 126This function adds the value of 127.Va datum 128to the entropy pool. 129No entropy is assumed to be collected from this value, it merely helps 130stir the entropy pool. 131All entropy is gathered from jitter between the timing of events. 132.Pp 133Note that using a constant for 134.Va datum 135does not weaken security, but it does 136not help. 137Try to use something that can change, such as an interrupt status register 138which might have a bit set for receive ready or transmit ready, or other 139device status information. 140.Pp 141To allow the system to gather the timing information accurately, this call 142should be placed within the actual hardware interrupt service routine. 143Care must be taken to ensure that the interrupt was actually serviced by 144the interrupt handler, since on some systems interrupts can be shared. 145.Pp 146This function loses nearly all usefulness if it is called from a scheduled 147software interrupt. 148If that is the only way to add the device as an entropy source, don't. 149.Pp 150If it is desired to mix in the 151.Va datum 152and to add in a timestamp, but not to actually estimate entropy from a source 153of randomness, passing 154.Dv NULL 155for 156.Va rnd_source 157is permitted, and the device does not need to be attached. 158.It Fn rnd_add_data "krndsource_t *rnd_source" "void *data" "uint32_t len" "uint32_t entropy" 159adds (hopefully) random 160.Fa data 161to the entropy pool. 162.Fa len 163is the number of bytes in 164.Fa data 165and 166.Fa entropy 167is an "entropy quality" measurement. 168If every bit of 169.Fa data 170is known to be random, 171.Fa entropy 172is the number of bits in 173.Fa data . 174.Pp 175Timing information is also used to add entropy into the system, using 176inter-event timings. 177.Pp 178If it is desired to mix in the 179.Va data 180and to add in a timestamp, but not to actually estimate entropy from a source 181of randomness, passing 182.Dv NULL 183for 184.Va rnd_source 185is permitted, and the device does not need to be attached. 186.El 187.Sh INTERNAL ENTROPY POOL MANAGEMENT 188When a hardware event occurs (such as completion of a hard drive 189transfer or an interrupt from a network device) a timestamp is 190generated. 191This timestamp is compared to the previous timestamp 192recorded for the device, and the first, second, and third order 193differentials are calculated. 194.Pp 195If any of these differentials is zero, no entropy is assumed to 196have been gathered. 197If all are non-zero, one bit is assumed. 198Next, data is mixed into the entropy pool using an LFSR (linear 199feedback shift register). 200.Pp 201To extract data from the entropy pool, a cryptographically strong hash 202function is used. 203The output of this hash is mixed back into the pool using the LFSR, 204and then folded in half before being returned to the caller. 205.Pp 206Mixing the actual hash into the pool causes the next extraction to 207return a different value, even if no timing events were added to the 208pool. 209Folding the data in half prevents the caller to derive the 210actual hash of the pool, preventing some attacks. 211.Pp 212In the 213.Nx 214kernel, values should be extracted from the entropy pool 215.Em only 216via the 217.Xr cprng 9 218interface. 219Direct access to the entropy pool is unsupported and may be dangerous. 220There is no supported API for direct access to the output of the entropy pool. 221.\" .Sh ERRORS 222.Sh FILES 223These functions are declared in src/sys/sys/rndsource.h and defined in 224src/sys/kern/kern_rndq.c. 225.Sh SEE ALSO 226.Xr rnd 4 , 227.Xr rndctl 8 , 228.Xr cprng 9 229.Sh HISTORY 230The random device was introduced in 231.Nx 1.3 . 232.Sh AUTHORS 233This implementation was written by 234.An Michael Graff Aq Mt explorer@flame.org 235using ideas and algorithms gathered from many sources, including 236the driver written by Ted Ts'o. 237.Sh BUGS 238The only good sources of randomness are quantum mechanical, and most 239computers avidly avoid having true sources of randomness included. 240Don't expect to surpass "pretty good". 241