1.\" $NetBSD: rnd.9,v 1.27 2019/12/07 12:26:05 wiz 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.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd August 10, 2014 31.Dt RND 9 32.Os 33.Sh NAME 34.Nm RND , 35.Nm rnd_attach_source , 36.Nm rnd_detach_source , 37.Nm rnd_add_data , 38.Nm rnd_add_data_sync , 39.Nm rnd_add_uint32 40.Nd functions to make a device available for entropy collection 41.Sh SYNOPSIS 42.In sys/rndsource.h 43.Ft void 44.Fn rndsource_setcb "krndsource_t *rnd_source" "void (*callback)(size_t, void *)" "void *cookie" 45.Ft void 46.Fn rnd_attach_source "krndsource_t *rnd_source" "char *devname" "uint32_t source_type" "uint32_t flags" 47.Ft void 48.Fn rnd_detach_source "krndsource_t *rnd_source" 49.Ft void 50.Fn rnd_add_data "krndsource_t *rnd_source" "void *data" "uint32_t len" "uint32_t entropy" 51.Ft void 52.Fn rnd_add_data_sync "krndsource_t *rnd_source" "void *data" "uint32_t len" "uint32_t entropy" 53.Ft void 54.Fn rnd_add_uint32 "krndsource_t *rnd_source" "uint32_t datum" 55.Sh DESCRIPTION 56These 57.Nm 58functions make a device available for entropy collection for 59the kernel entropy pool, which provides key material for the 60.Xr cprng 9 61and 62.Xr rnd 4 63.Pa ( /dev/random ) 64interfaces. 65.Pp 66The caller must zero an 67.Fa rnd_source 68object before using it. 69Ideally the first argument 70.Fa rnd_source 71of these functions gets included in the devices' entity struct, 72but any means to permanently (statically) attach one such argument 73to one incarnation of the device is ok. 74Do not share 75.Fa rnd_source 76structures between two devices, and make sure to serialize all access 77to each 78.Fa rnd_source , 79for example with 80.Xr mutex 9 . 81.Bl -tag -width 8n 82.It Fn rndsource_setcb "krndsource_t *rnd_source" "void (*callback)(size_t, void *)" "void *cookie" 83This function sets a callback to be invoked when the kernel entropy 84pool is hungry. 85It is optional; if used, it must be used 86.Em before 87.Fn rnd_attach_source , 88and the caller must pass 89.Dv RND_FLAG_HASCB 90to 91.Fn rnd_attach_source 92in order for the callback to be used. 93The callback is invoked as 94.Fa callback ( Fa nbytes , Fa cookie ) , 95where 96.Fa nbytes 97is the number of bytes requested for the entropy pool, and 98.Fa cookie 99is the cookie that was passed to 100.Fn rndsource_setcb . 101The callback normally does one of two things: 102.Bl -dash 103.It 104Sends a request to a hardware device for entropy and returns. 105The hardware will later return data asynchronously by an interrupt, and 106the callback will use 107.Fn rnd_add_data 108or 109.Fn rnd_add_uint32 110to add the data to the pool. 111.It 112Synchronously gathers entropy from hardware \(em for example, by a CPU 113instruction like Intel RDSEED. 114In this case, in order to add data to the pool 115.Em before 116returning, the callback 117.Em must 118use 119.Fn rnd_add_data_sync , 120not 121.Fn rnd_add_data 122or 123.Fn rnd_add_uint32 . 124.El 125.It Fn rnd_attach_source "krndsource_t *rnd_source" "char *devname" "uint32_t source_type" "uint32_t flags" 126This function announces the availability of a device for entropy collection. 127It must be called before the source struct pointed to by 128.Fa rnd_source 129is used in any of the following functions. 130.Pp 131.Fa devname 132is the name of the device. 133It is used to print a message (if the kernel is compiled with 134``options RND_VERBOSE'') and also for status information printed with 135.Xr rndctl 8 . 136.Pp 137.Fa source_type 138is 139.Dv RND_TYPE_NET 140for network devices, 141.Dv RND_TYPE_DISK 142for physical disks, 143.Dv RND_TYPE_TAPE 144for a tape drive, 145.Dv RND_TYPE_TTY 146for a tty, 147.Dv RND_TYPE_RNG 148for a random number generator, and 149.Dv RND_TYPE_ENV 150for an environment sensor. 151.Dv RND_TYPE_UNKNOWN 152is not to be used as a type. 153It is used internally to the rnd system. 154.Pp 155.Fa flags 156are the logical OR of 157.Dv RND_FLAG_COLLECT_VALUE 158(mix data provided by this source into the pool) 159.Dv RND_FLAG_COLLECT_TIME 160(mix timestamps from this source into the pool) 161.Dv RND_FLAG_ESTIMATE_VALUE 162(use a delta estimator to count bits of entropy from this source's data towards 163the pool estimate) 164.Dv RND_FLAG_ESTIMATE_TIME 165(use a delta estimator to count bits of entropy from this source's timestamps 166towards the pool estimate) 167.Dv RND_FLAG_HASCB 168(caller specified a callback with 169.Fn rndsource_setcb ) . 170For many devices, 171.Dv RND_FLAG_DEFAULT 172.Dv ( RND_FLAG_COLLECT_VALUE | RND_FLAG_COLLECT_TIME | RND_FLAG_ESTIMATE_TIME ) 173is the best choice. 174Note that devices of type 175.Dv RND_TYPE_NET 176default to 177.Dv RND_FLAG_COLLECT_VALUE | RND_FLAG_COLLECT_TIME 178(no entropy counted). 179.It Fn rnd_detach_source "krndsource_t *rnd_source" 180This function disconnects the device from entropy collection. 181.It Fn rnd_add_uint32 "krndsource_t *rnd_source" "uint32_t datum" 182This function adds the value of 183.Va datum 184to the entropy pool. 185No entropy is assumed to be collected from this value, it merely helps 186stir the entropy pool. 187All entropy is gathered from jitter between the timing of events. 188.Pp 189Note that using a constant for 190.Va datum 191does not weaken security, but it does 192not help. 193Try to use something that can change, such as an interrupt status register 194which might have a bit set for receive ready or transmit ready, or other 195device status information. 196.Pp 197To allow the system to gather the timing information accurately, this call 198should be placed within the actual hardware interrupt service routine. 199Care must be taken to ensure that the interrupt was actually serviced by 200the interrupt handler, since on some systems interrupts can be shared. 201.Pp 202This function loses nearly all usefulness if it is called from a scheduled 203software interrupt. 204If that is the only way to add the device as an entropy source, don't. 205.Pp 206If it is desired to mix in the 207.Va datum 208and to add in a timestamp, but not to actually estimate entropy from a source 209of randomness, passing 210.Dv NULL 211for 212.Va rnd_source 213is permitted, and the device does not need to be attached. 214.Pp 215.Fn rnd_add_uint32 216.Em must not 217be used during a callback as set with 218.Fn rndsource_setcb ; 219use 220.Fn rnd_add_data_sync 221instead. 222.It Fn rnd_add_data "krndsource_t *rnd_source" "void *data" "uint32_t len" "uint32_t entropy" 223adds (hopefully) random 224.Fa data 225to the entropy pool. 226.Fa len 227is the number of bytes in 228.Fa data 229and 230.Fa entropy 231is an "entropy quality" measurement. 232If every bit of 233.Fa data 234is known to be random, 235.Fa entropy 236is the number of bits in 237.Fa data . 238.Pp 239Timing information is also used to add entropy into the system, using 240inter-event timings. 241.Pp 242If it is desired to mix in the 243.Va data 244and to add in a timestamp, but not to actually estimate entropy from a source 245of randomness, passing 246.Dv NULL 247for 248.Va rnd_source 249is permitted, and the device does not need to be attached. 250.Pp 251.Fn rnd_add_data 252.Em must not 253be used during a callback as set with 254.Fn rndsource_setcb ; 255use 256.Fn rnd_add_data_sync 257instead. 258.El 259.Sh INTERNAL ENTROPY POOL MANAGEMENT 260When a hardware event occurs (such as completion of a hard drive 261transfer or an interrupt from a network device) a timestamp is 262generated. 263This timestamp is compared to the previous timestamp 264recorded for the device, and the first, second, and third order 265differentials are calculated. 266.Pp 267If any of these differentials is zero, no entropy is assumed to 268have been gathered. 269If all are non-zero, one bit is assumed. 270Next, data is mixed into the entropy pool using an LFSR (linear 271feedback shift register). 272.Pp 273To extract data from the entropy pool, a cryptographically strong hash 274function is used. 275The output of this hash is mixed back into the pool using the LFSR, 276and then folded in half before being returned to the caller. 277.Pp 278Mixing the actual hash into the pool causes the next extraction to 279return a different value, even if no timing events were added to the 280pool. 281Folding the data in half prevents the caller to derive the 282actual hash of the pool, preventing some attacks. 283.Pp 284In the 285.Nx 286kernel, values should be extracted from the entropy pool 287.Em only 288via the 289.Xr cprng 9 290interface. 291Direct access to the entropy pool is unsupported and may be dangerous. 292There is no supported API for direct access to the output of the entropy pool. 293.\" .Sh ERRORS 294.Sh FILES 295These functions are declared in src/sys/sys/rndsource.h and defined in 296src/sys/kern/kern_rndq.c. 297.Sh SEE ALSO 298.Xr rnd 4 , 299.Xr rndctl 8 , 300.Xr cprng 9 301.Sh HISTORY 302The random device was introduced in 303.Nx 1.3 . 304.Sh AUTHORS 305This implementation was written by 306.An Michael Graff Aq Mt explorer@flame.org 307using ideas and algorithms gathered from many sources, including 308the driver written by Ted Ts'o. 309.Sh BUGS 310The only good sources of randomness are quantum mechanical, and most 311computers avidly avoid having true sources of randomness included. 312Don't expect to surpass "pretty good". 313