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 31.Sh NAME 32.Nm random_harvest 33.Nd gather entropy from the kernel for the entropy device 34.Sh SYNOPSIS 35.In sys/random.h 36.Ft void 37.Fo random_harvest 38.Fa "void *entropy" 39.Fa "u_int size" 40.Fa "u_int bits" 41.Fa "u_int frac" 42.Fa "enum esource source" 43.Fc 44.Sh DESCRIPTION 45The 46.Fn random_harvest 47function is used by device drivers 48and other kernel processes to pass data 49that is considered (at least partially) stochastic 50to the entropy device. 51.Pp 52The caller should pass a pointer (to no more than 16 bytes) of 53the 54.Dq random 55data in 56.Fa entropy . 57The argument 58.Fa size 59contains the number of bytes pointed to. 60The caller should 61.Em "very conservatively" 62estimate the number of random bits 63in the sample, 64and pass this in 65.Fa bits 66or 67.Fa frac . 68If the estimated number of bits per sample is an integer, then 69.Fa bits 70is used, and 71.Fa frac 72is 0. 73Otherwise, 74for low-entropy samples, 75.Dq fractional 76entropy can be supplied in 77.Fa frac . 78(This is considered to be 79.Fa frac / 801024 bits of entropy.) 81The 82.Fa source 83is chosen from 84.Dv RANDOM_WRITE , RANDOM_KEYBOARD , RANDOM_MOUSE , RANDOM_NET 85and 86.Dv RANDOM_INTERRUPT , 87and is used to indicate the source of the entropy. 88.Pp 89Interrupt harvesting has been simplified 90for the kernel programmer. 91If a device driver registers an interrupt handler 92with 93.Xr BUS_SETUP_INTR 9 94or 95.Xr bus_setup_intr 9 , 96then it is only necessary to 97include the 98.Dv INTR_ENTROPY 99bit in the 100.Fa flags 101argument to have that interrupt source 102be used for entropy harvesting. 103.Sh SEE ALSO 104.Xr random 4 , 105.Xr BUS_SETUP_INTR 9 106.Sh AUTHORS 107The 108.Fx 109.Xr random 4 110entropy device and supporting documentation was written by 111.An Mark R V Murray . 112