1.\" $NetBSD: rnd.9,v 1.13 2002/10/14 13:43:31 wiz 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.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd October 20, 1997 38.Dt RND 9 39.Os 40.Sh NAME 41.Nm RND , 42.Nm rnd_attach_source , 43.Nm rnd_detach_source , 44.Nm rnd_add_data , 45.Nm rnd_add_uint32 46.Nd functions to make a device available for entropy collection 47.Sh SYNOPSIS 48.Fd #include \*[Lt]sys/rnd.h\*[Gt] 49.Ft void 50.Fn rnd_attach_source "rndsource_element_t *rnd_source" "char *devname" "u_int32_t source_type" "u_int32_t flags" 51.Ft void 52.Fn rnd_detach_source "rndsource_element_t *rnd_source" 53.Ft void 54.Fn rnd_add_data "rndsource_element_t *rnd_source" "void *data" "u_int32_t len" "u_int32_t entropy" 55.Ft void 56.Fn rnd_add_uint32 "rndsource_element_t *rnd_source" "u_int32_t datum" 57.Sh DESCRIPTION 58These 59.Nm 60functions make a device available for entropy collection for 61.Pa /dev/random . 62.Pp 63Ideally the first argument 64.Fa rnd_source 65of these functions gets included in the devices' entity struct, 66but any means to permanently (static) attach one such argument 67to one incarnation of the device is ok. 68Do not share 69.Fa rnd_source 70structures between two devices. 71.Pp 72.Bl -tag -width 8n 73.It Fn rnd_attach_source "rndsource_element_t *rnd_source" "char *devname" "u_int32_t source_type" "u_int32_t flags" 74This function announces the availability of a device for entropy collection. 75It must be called before the source struct pointed to by 76.Fa rnd_source 77is used in any of the following functions. 78.Pp 79.Fa devname 80is the name of the device. 81It is used to print a message (if the kernel is compiled with 82``options RND_VERBOSE'') and also for status information printed with 83.Xr rndctl 8 . 84.Pp 85.Fa source_type 86is 87.Dv RND_TYPE_NET 88for network devices, 89.Dv RND_TYPE_DISK 90for physical disks, 91.Dv RND_TYPE_TAPE 92for a tape drive, and 93.Dv RND_TYPE_TTY 94for a tty. 95.Dv RND_TYPE_UNKNOWN 96is not to be used as a type. 97It is used internally to the rnd system. 98.Pp 99.Fa flags 100are the logical OR of 101.Dv RND_FLAG_NO_COLLECT 102(don't collect or estimate) 103.Dv RND_FLAG_NO_ESTIMATE 104(don't estimate) 105to control the default setting for collection and estimation. 106Note that devices of type 107.Dv RND_TYPE_NET 108default to 109.Dv RND_FLAG_NO_ESTIMATE . 110.Pp 111.It Fn rnd_detach_source "rndsource_element_t *rnd_source" 112This function disconnects the device from entropy collection. 113.It Fn rnd_add_uint32 "rndsource_element_t *rnd_source" "u_int32_t datum" 114This function adds the value of 115.Va datum 116to the entropy pool. 117No entropy is assumed to be collected from this value, it merely helps 118stir the entropy pool. 119All entropy is gathered from jitter between the timing of events. 120.Pp 121Note that using a constant for 122.Va datum 123does not weaken security, but it does 124not help. 125Try to use something that can change, such as an interrupt status register 126which might have a bit set for receive ready or transmit ready, or other 127device status information. 128.Pp 129To allow the system to gather the timing information accurately, this call 130should be placed within the actual hardware interrupt service routine. 131Care must be taken to ensure that the interrupt was actually serviced by 132the interrupt handler, since on some systems interrupts can be shared. 133.Pp 134This function loses nearly all usefulness if it is called from a scheduled 135software interrupt. 136If that is the only way to add the device as an entropy source, don't. 137.Pp 138If it is desired to mix in the 139.Va datum 140and to add in a timestamp, but not to actually estimate entropy from a source 141of randomness, passing 142.Dv NULL 143for 144.Va rnd_source 145is permitted, and the device does not need to be attached. 146.It Fn rnd_add_data "rndsource_element_t *rnd_source" "void *data" "u_int32_t len" "u_int32_t entropy" 147adds (hopefully) random 148.Fa data 149to the entropy pool. 150.Fa len 151is the number of bytes in 152.Fa data 153and 154.Fa entropy 155is an "entropy quality" measurement. 156If every bit of 157.Fa data 158is known to be random, 159.Fa entropy 160is the number of bits in 161.Fa data . 162.Pp 163Timing information is also used to add entropy into the system, using 164inter-event timings. 165.Pp 166If it is desired to mix in the 167.Va data 168and to add in a timestamp, but not to actually estimate entropy from a source 169of randomness, passing 170.Dv NULL 171for 172.Va rnd_source 173is permitted, and the device does not need to be attached. 174.El 175.\" .Sh ERRORS 176.Sh FILES 177These functions are declared in src/sys/sys/rnd.h and defined in 178src/sys/dev/rnd.c. 179.Sh SEE ALSO 180.Xr rnd 4 , 181.Xr rndctl 8 182.Sh HISTORY 183The random device was introduced in 184.Nx 1.3 . 185.Sh AUTHORS 186This implementation was written by Michael Graff \*[Lt]explorer@flame.org\*[Gt] 187using ideas and algorithms gathered from many sources, including 188the driver written by Ted Ts'o. 189.Sh BUGS 190The only good sources of randomness are quantum mechanical, and most 191computers avidly avoid having true sources of randomness included. 192Don't expect to surpass "pretty good". 193