1.\" 2.\" Copyright (c) 2002 Mark R V Murray 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 15.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 16.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 17.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 18.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 19.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 20.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 21.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 22.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" $FreeBSD$ 27.\" 28.Dd February 6, 2002 29.Dt RANDOM_HARVEST 9 30.Os FreeBSD 31.Sh NAME 32.Nm random_harvest 33.Nd gather entropy from the kernel for the entropy device 34.Sh SYNOPSIS 35.Fd #include <sys/random.h> 36.Ft void 37.Fn random_harvest "void *entropy" "u_int size" "u_int bits" "u_int frac" "enum esource source" 38.Sh DESCRIPTION 39The 40.Nm 41function is used by device drivers 42and other kernel processes to pass data 43that is considered (at least partially) stochastic 44to the entropy device. 45.Pp 46The caller should pass a pointer (to no more than 16 bytes) of 47the ``random'' data in 48.Ar entropy. 49The argument 50.Ar size 51contains the number of bytes pointed to. 52The caller should 53.Em very conservatively 54estimate the number of random bits 55in the sample, 56and pass this in 57.Ar bits 58or 59.Ar frac . 60If the estimated number of bits per sample is an integer, then 61.Ar bits 62is used, and 63.Ar frac is 0. 64Otherwise, 65for low-entropy samples, 66``fractional'' entropy can be supplied in 67.Ar frac 68(This is considered to be 69.Ar frac / 701024 bits of entropy). 71The 72.Ar source 73is chosen from 74.Dv RANDOM_WRITE , 75.Dv RANDOM_KEYBOARD , 76.Dv RANDOM_MOUSE , 77.Dv RANDOM_NET 78and 79.Dv RANDOM_INTERRUPT 80and is used to indicate the source of the entropy. 81.Pp 82Interrupt harvesting has been simplified 83for the kernel programmer. 84If a device driver registers an interrupt handler 85with 86.Fn BUS_SETUP_INTR 87or 88.Fn bus_setup_intr , 89then it is only necessary to 90include the INTR_ENTROPY bit in the 91.Ar flags 92argument to have that interrupt source 93be used for entropy harvesting. 94.Sh SEE ALSO 95.Xr random 4 , 96.Xr BUS_SETUP_INTR 9 97.Sh AUTHOR 98The 99.Fx 100.Pa /dev/random 101entropy device and supporting documentation was written by 102.An Mark R V Murray . 103