1.\" $NetBSD: rnd.9,v 1.16 2008/04/30 13:10:58 martin 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 October 20, 1997 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, and 86.Dv RND_TYPE_TTY 87for a tty. 88.Dv RND_TYPE_UNKNOWN 89is not to be used as a type. 90It is used internally to the rnd system. 91.Pp 92.Fa flags 93are the logical OR of 94.Dv RND_FLAG_NO_COLLECT 95(don't collect or estimate) 96.Dv RND_FLAG_NO_ESTIMATE 97(don't estimate) 98to control the default setting for collection and estimation. 99Note that devices of type 100.Dv RND_TYPE_NET 101default to 102.Dv RND_FLAG_NO_ESTIMATE . 103.Pp 104.It Fn rnd_detach_source "rndsource_element_t *rnd_source" 105This function disconnects the device from entropy collection. 106.It Fn rnd_add_uint32 "rndsource_element_t *rnd_source" "uint32_t datum" 107This function adds the value of 108.Va datum 109to the entropy pool. 110No entropy is assumed to be collected from this value, it merely helps 111stir the entropy pool. 112All entropy is gathered from jitter between the timing of events. 113.Pp 114Note that using a constant for 115.Va datum 116does not weaken security, but it does 117not help. 118Try to use something that can change, such as an interrupt status register 119which might have a bit set for receive ready or transmit ready, or other 120device status information. 121.Pp 122To allow the system to gather the timing information accurately, this call 123should be placed within the actual hardware interrupt service routine. 124Care must be taken to ensure that the interrupt was actually serviced by 125the interrupt handler, since on some systems interrupts can be shared. 126.Pp 127This function loses nearly all usefulness if it is called from a scheduled 128software interrupt. 129If that is the only way to add the device as an entropy source, don't. 130.Pp 131If it is desired to mix in the 132.Va datum 133and to add in a timestamp, but not to actually estimate entropy from a source 134of randomness, passing 135.Dv NULL 136for 137.Va rnd_source 138is permitted, and the device does not need to be attached. 139.It Fn rnd_add_data "rndsource_element_t *rnd_source" "void *data" "uint32_t len" "uint32_t entropy" 140adds (hopefully) random 141.Fa data 142to the entropy pool. 143.Fa len 144is the number of bytes in 145.Fa data 146and 147.Fa entropy 148is an "entropy quality" measurement. 149If every bit of 150.Fa data 151is known to be random, 152.Fa entropy 153is the number of bits in 154.Fa data . 155.Pp 156Timing information is also used to add entropy into the system, using 157inter-event timings. 158.Pp 159If it is desired to mix in the 160.Va data 161and to add in a timestamp, but not to actually estimate entropy from a source 162of randomness, passing 163.Dv NULL 164for 165.Va rnd_source 166is permitted, and the device does not need to be attached. 167.El 168.\" .Sh ERRORS 169.Sh FILES 170These functions are declared in src/sys/sys/rnd.h and defined in 171src/sys/dev/rnd.c. 172.Sh SEE ALSO 173.Xr rnd 4 , 174.Xr rndctl 8 175.Sh HISTORY 176The random device was introduced in 177.Nx 1.3 . 178.Sh AUTHORS 179This implementation was written by Michael Graff \*[Lt]explorer@flame.org\*[Gt] 180using ideas and algorithms gathered from many sources, including 181the driver written by Ted Ts'o. 182.Sh BUGS 183The only good sources of randomness are quantum mechanical, and most 184computers avidly avoid having true sources of randomness included. 185Don't expect to surpass "pretty good". 186