1.\" $NetBSD: rnd.9,v 1.17 2008/09/16 23:29:49 jmcneill 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 September 16, 2008 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/rnd.h 42.Ft void 43.Fn rnd_attach_source "rndsource_element_t *rnd_source" "char *devname" "uint32_t source_type" "uint32_t flags" 44.Ft void 45.Fn rnd_detach_source "rndsource_element_t *rnd_source" 46.Ft void 47.Fn rnd_add_data "rndsource_element_t *rnd_source" "void *data" "uint32_t len" "uint32_t entropy" 48.Ft void 49.Fn rnd_add_uint32 "rndsource_element_t *rnd_source" "uint32_t datum" 50.Sh DESCRIPTION 51These 52.Nm 53functions make a device available for entropy collection for 54.Pa /dev/random . 55.Pp 56Ideally the first argument 57.Fa rnd_source 58of these functions gets included in the devices' entity struct, 59but any means to permanently (static) attach one such argument 60to one incarnation of the device is ok. 61Do not share 62.Fa rnd_source 63structures between two devices. 64.Pp 65.Bl -tag -width 8n 66.It Fn rnd_attach_source "rndsource_element_t *rnd_source" "char *devname" "uint32_t source_type" "uint32_t flags" 67This function announces the availability of a device for entropy collection. 68It must be called before the source struct pointed to by 69.Fa rnd_source 70is used in any of the following functions. 71.Pp 72.Fa devname 73is the name of the device. 74It is used to print a message (if the kernel is compiled with 75``options RND_VERBOSE'') and also for status information printed with 76.Xr rndctl 8 . 77.Pp 78.Fa source_type 79is 80.Dv RND_TYPE_NET 81for network devices, 82.Dv RND_TYPE_DISK 83for physical disks, 84.Dv RND_TYPE_TAPE 85for a tape drive, 86.Dv RND_TYPE_TTY 87for a tty, and 88.Dv RND_TYPE_RNG 89for a random number generator. 90.Dv RND_TYPE_UNKNOWN 91is not to be used as a type. 92It is used internally to the rnd system. 93.Pp 94.Fa flags 95are the logical OR of 96.Dv RND_FLAG_NO_COLLECT 97(don't collect or estimate) 98.Dv RND_FLAG_NO_ESTIMATE 99(don't estimate) 100to control the default setting for collection and estimation. 101Note that devices of type 102.Dv RND_TYPE_NET 103default to 104.Dv RND_FLAG_NO_ESTIMATE . 105.Pp 106.It Fn rnd_detach_source "rndsource_element_t *rnd_source" 107This function disconnects the device from entropy collection. 108.It Fn rnd_add_uint32 "rndsource_element_t *rnd_source" "uint32_t datum" 109This function adds the value of 110.Va datum 111to the entropy pool. 112No entropy is assumed to be collected from this value, it merely helps 113stir the entropy pool. 114All entropy is gathered from jitter between the timing of events. 115.Pp 116Note that using a constant for 117.Va datum 118does not weaken security, but it does 119not help. 120Try to use something that can change, such as an interrupt status register 121which might have a bit set for receive ready or transmit ready, or other 122device status information. 123.Pp 124To allow the system to gather the timing information accurately, this call 125should be placed within the actual hardware interrupt service routine. 126Care must be taken to ensure that the interrupt was actually serviced by 127the interrupt handler, since on some systems interrupts can be shared. 128.Pp 129This function loses nearly all usefulness if it is called from a scheduled 130software interrupt. 131If that is the only way to add the device as an entropy source, don't. 132.Pp 133If it is desired to mix in the 134.Va datum 135and to add in a timestamp, but not to actually estimate entropy from a source 136of randomness, passing 137.Dv NULL 138for 139.Va rnd_source 140is permitted, and the device does not need to be attached. 141.It Fn rnd_add_data "rndsource_element_t *rnd_source" "void *data" "uint32_t len" "uint32_t entropy" 142adds (hopefully) random 143.Fa data 144to the entropy pool. 145.Fa len 146is the number of bytes in 147.Fa data 148and 149.Fa entropy 150is an "entropy quality" measurement. 151If every bit of 152.Fa data 153is known to be random, 154.Fa entropy 155is the number of bits in 156.Fa data . 157.Pp 158Timing information is also used to add entropy into the system, using 159inter-event timings. 160.Pp 161If it is desired to mix in the 162.Va data 163and to add in a timestamp, but not to actually estimate entropy from a source 164of randomness, passing 165.Dv NULL 166for 167.Va rnd_source 168is permitted, and the device does not need to be attached. 169.El 170.\" .Sh ERRORS 171.Sh FILES 172These functions are declared in src/sys/sys/rnd.h and defined in 173src/sys/dev/rnd.c. 174.Sh SEE ALSO 175.Xr rnd 4 , 176.Xr rndctl 8 177.Sh HISTORY 178The random device was introduced in 179.Nx 1.3 . 180.Sh AUTHORS 181This implementation was written by Michael Graff \*[Lt]explorer@flame.org\*[Gt] 182using ideas and algorithms gathered from many sources, including 183the driver written by Ted Ts'o. 184.Sh BUGS 185The only good sources of randomness are quantum mechanical, and most 186computers avidly avoid having true sources of randomness included. 187Don't expect to surpass "pretty good". 188