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