1.\" Copyright (c) 2001 Mark R V Murray. All rights reserved. 2.\" 3.\" Redistribution and use in source and binary forms, with or without 4.\" modification, are permitted provided that the following conditions 5.\" are met: 6.\" 1. Redistributions of source code must retain the above copyright 7.\" notice, this list of conditions and the following disclaimer. 8.\" 2. Redistributions in binary form must reproduce the above copyright 9.\" notice, this list of conditions and the following disclaimer in the 10.\" documentation and/or other materials provided with the distribution. 11.\" 12.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 13.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 14.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 15.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 16.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 17.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 18.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 19.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 20.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 21.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 22.\" SUCH DAMAGE. 23.\" 24.\" $FreeBSD$ 25.\" 26.Dd February 10, 2001 27.Dt RANDOM 4 28.Os 29.Sh NAME 30.Nm random 31.Nd the entropy device 32.Sh DESCRIPTION 33The 34.Nm 35device accepts and reads data as any ordinary (and willing) file, 36but throws away any data written to it, 37and returns an endless supply of random bytes when read. 38.Pp 39The only purpose of writing data to 40.Nm 41is to perturb the internal state. 42This perturbation of the internal state 43is the only userland method of introducing 44extra entropy into the device. 45If the writer has superuser privilege, 46then closing the device after writing 47will make the internal generator reseed itself. 48This can be used for extra security, 49as it immediately introduces any/all new entropy 50into the PRNG. 51The 52.Nm 53device can be controlled with 54.Xr sysctl 8 . 55.Pp 56To see the devices' current settings, use the command line: 57.Pp 58.Dl sysctl kern.random 59.Pp 60which results in something like: 61.Pp 62.Bd -literal -offset indent 63kern.random.sys.seeded: 1 64kern.random.sys.burst: 20 65kern.random.sys.harvest.ethernet: 0 66kern.random.sys.harvest.point_to_point: 0 67kern.random.sys.harvest.interrupt: 0 68kern.random.yarrow.gengateinterval: 10 69kern.random.yarrow.bins: 10 70kern.random.yarrow.fastthresh: 100 71kern.random.yarrow.slowthresh: 160 72kern.random.yarrow.slowoverthresh: 2 73.Ed 74.Pp 75All settings are read/write. 76.Pp 77The 78.Va kern.random.sys.seeded 79variable indicates whether or not the 80.Nm 81device is in an acceptably secure state 82as a result of reseeding. 83If set to 0, the device will block (on read) until the next reseed 84(which can be from an explicit write, 85or as a result of entropy harvesting). 86A reseed will set the value to 1 (non-blocking). 87.Pp 88The 89.Va kern.random.sys.burst 90variable instructs the kernel thread 91that processes the harvest queue 92to 93.Xr tsleep 9 94briefly after that many events 95have been processed. 96This helps prevent the random device 97from being so compute-bound 98that it takes over all processing ability. 99A value of zero (0) is treated as 100.Em infinity , 101and will only allow the kernel to pause 102if the queue is empty. 103Only values in the range 104.Bq 0..20 105are accepted. 106.Pp 107The 108.Va kern.random.sys.harvest.ethernet 109variable is used to select LAN traffic as an entropy source. 110A zero (0) value means that LAN traffic 111is not considered as an entropy source. 112Set the variable to one (1) 113if you wish to use LAN traffic for entropy harvesting. 114.Pp 115The 116.Va kern.random.sys.harvest.point_to_point 117variable is used to select serial line traffic as an entropy source. 118(Serial line traffic includes PPP, SLIP and all tun0 traffic.) 119A zero (0) value means such traffic 120is not considered as an entropy source. 121Set the variable to one (1) 122if you wish to use it for entropy harvesting. 123.Pp 124The 125.Va kern.random.sys.harvest.interrupt 126variable is used to select hardware interrupts 127as an entropy source. 128A zero (0) value means interrupts 129are not considered as an entropy source. 130Set the variable to one (1) 131if you wish to use them for entropy harvesting. 132All interrupt harvesting is setup by the 133individual device drivers. 134.Pp 135The other variables are explained in the paper describing the 136.Em Yarrow 137algorithm at 138.Pa http://www.counterpane.com/yarrow.html . 139.Pp 140These variables are all limited 141in terms of the values they may contain: 142.Bl -tag -width "kern.random.yarrow.gengateinterval" -compact -offset indent 143.It Va kern.random.yarrow.gengateinterval 144.Bq 4..64 145.It Va kern.random.yarrow.bins 146.Bq 2..16 147.It Va kern.random.yarrow.fastthresh 148.Bq 64..256 149.It Va kern.random.yarrow.slowthresh 150.Bq 64..256 151.It Va kern.random.yarrow.slowoverthresh 152.Bq 1..5 153.El 154.Pp 155Internal 156.Xr sysctl 3 157handlers force the above variables 158into the stated ranges. 159.Sh FILES 160.Bl -tag -width /dev/random 161.It Pa /dev/random 162.El 163.Sh SEE ALSO 164.Xr sysctl 8 165.Sh HISTORY 166A 167.Nm 168device appeared in 169.Fx 2.2 . 170The early version was taken from Theodore Ts'o's entropy driver for Linux. 171The current implementation, 172introduced in 173.Fx 5.0 , 174is a complete rewrite by 175.An Mark R V Murray , 176and is an implementation of the 177.Em Yarrow 178algorithm by Bruce Schneier, 179.Em et al . 180