1.\" 2.\" Copyright (c) 2002-2015 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 August 26, 2018 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/types.h 36.In sys/random.h 37.Ft void 38.Fo random_harvest_direct 39.Fa "void *entropy" 40.Fa "u_int size" 41.Fa "enum esource source" 42.Fc 43.Ft void 44.Fo random_harvest_fast 45.Fa "void *entropy" 46.Fa "u_int size" 47.Fa "enum esource source" 48.Fc 49.Ft void 50.Fo random_harvest_queue 51.Fa "void *entropy" 52.Fa "u_int size" 53.Fa "enum esource source" 54.Fc 55.Sh DESCRIPTION 56The 57.Fn random_harvest_* 58functions are used by device drivers 59and other kernel processes to pass data 60that is considered (at least partially) stochastic 61to the entropy device. 62.Pp 63The caller should pass 64a pointer pointing to the 65.Dq random 66data in 67.Fa entropy . 68The argument 69.Fa size 70contains the number of bytes pointed to. 71The 72.Fa source 73is chosen from one of 74the values enumerated in 75.Pa sys/dev/random.h . 76and is used to indicate the source of the entropy. 77.Pp 78The 79.Fo random_harvest_direct 80.Fc 81variant is used 82for early harvesting 83before any multitasking 84is enabled. 85.Pp 86The 87.Fn random_harvest_fast 88variant is used 89by sources that 90should not take 91a performance hit 92from harvesting, 93as they are high-rate 94sources. 95Some entropy is sacrificed, 96but the high rate of supply 97will compensate for this. 98.Pp 99The 100.Fn random_harvest_queue 101variant is used 102for general harvesting 103and is the default 104choice for most entropy sources 105such as interrupts 106or console events. 107.Pp 108Interrupt harvesting has been 109in part simplified 110for the kernel programmer. 111If a device driver registers an interrupt handler 112with 113.Xr BUS_SETUP_INTR 9 114or 115.Xr bus_setup_intr 9 , 116then it is only necessary to 117include the 118.Dv INTR_ENTROPY 119bit in the 120.Fa flags 121argument to have that interrupt source 122be used for entropy harvesting. 123This should be done wherever practicable. 124.Sh SEE ALSO 125.Xr random 4 , 126.Xr BUS_SETUP_INTR 9 127.Sh AUTHORS 128The 129.Fx 130.Xr random 4 131entropy device and supporting documentation was written by 132.An Mark R V Murray . 133