1.\" $NetBSD: rnd.9,v 1.29 2020/05/04 15:13:45 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 April 25, 2020 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.Vt typedef struct krndsource krndsource_t; 44.Ft void 45.Fn rndsource_setcb "krndsource_t *rnd_source" "void (*callback)(size_t, void *)" "void *cookie" 46.Ft void 47.Fn rnd_attach_source "krndsource_t *rnd_source" "char *devname" "uint32_t source_type" "uint32_t flags" 48.Ft void 49.Fn rnd_detach_source "krndsource_t *rnd_source" 50.Ft void 51.Fn rnd_add_data "krndsource_t *rnd_source" "void *data" "uint32_t len" "uint32_t entropy" 52.Ft void 53.Fn rnd_add_data_sync "krndsource_t *rnd_source" "void *data" "uint32_t len" "uint32_t entropy" 54.Ft void 55.Fn rnd_add_uint32 "krndsource_t *rnd_source" "uint32_t datum" 56.Sh DESCRIPTION 57The 58.Nm 59functions enable drivers to collect samples of physical observations, 60such as network packet timings or hardware random number generator 61outputs, into a kernel entropy pool to derive key material for 62.Xr cprng 9 63and 64.Xr rnd 4 65.Pq Pa /dev/random , Pa /dev/urandom . 66.Pp 67Usage model: 68.Bl -enum -compact 69.It 70Allocate and zero a 71.Vt struct krndsource 72object before using the 73.Nm 74functions. 75.It 76Optionally, set a callback with 77.Fn rndsource_setcb 78if appropriate, e.g. for an on-demand hardware random number 79generator. 80.It 81Attach the random source with 82.Fn rnd_attach_source . 83.It 84Enter data with 85.Fn rnd_add_data 86or 87.Fn rnd_add_uint32 , 88or, if in the callback, 89.Fn rnd_add_data_sync . 90.It 91When the driver is done, detach it with 92.Fn rnd_detach_source . 93.El 94.Pp 95The following types of random sources are defined: 96.Bl -tag -width "Dv RND_TYPE_UNKNOWN" -compact 97.It Dv RND_TYPE_DISK 98Disk devices, typically sampling seek timings. 99.It Dv RND_TYPE_ENV 100Environmental sensors. 101.It Dv RND_TYPE_POWER 102Power sensors and timing of power-related events. 103.It Dv RND_TYPE_NET 104Network interfaces, typically sampling packet timings. 105By default, sample from network interfaces are ignored, for hysterical 106raisins. 107.It Dv RND_TYPE_RNG 108Hardware random number generators. 109.It Dv RND_TYPE_SKEW 110Skew between clocks. 111.It Dv RND_TYPE_TAPE 112Tape devices, typically sampling I/O timings. 113.It Dv RND_TYPE_TTY 114Tty devices, typically sampling interrupt timings. 115.It Dv RND_TYPE_VM 116Virtual memory fault timings. 117.It Dv RND_TYPE_UNKNOWN 118Unknown sources, or sources not otherwise classified. 119.El 120.Sh FUNCTIONS 121.Bl -tag -width abcd 122.It Fn rndsource_setcb "rnd_source" "callback" "cookie" 123Sets a callback to be invoked when the entropy pool is hungry 124to draw data from this source on demand. 125Optional; if used, must be used 126.Em before 127.Fn rnd_attach_source , 128and the caller must pass 129.Dv RND_FLAG_HASCB 130to 131.Fn rnd_attach_source . 132.Pp 133The callback is invoked as 134.Fo callback 135.Fa nbytes 136.Fa cookie 137.Fc , 138where 139.Fa nbytes 140is the number of bytes requested for the entropy pool, and 141.Fa cookie 142is the cookie that was passed to 143.Fn rndsource_setcb . 144The callback normally does one of two things: 145.Bl -dash 146.It 147Sends a request to a hardware device for entropy and returns. 148The hardware will later return data asynchronously by an interrupt, and 149the callback will use 150.Fn rnd_add_data 151or 152.Fn rnd_add_uint32 153to add the data to the pool. 154.It 155Synchronously gathers entropy from hardware \(em for example, by a CPU 156instruction like Intel RDSEED. 157In this case, in order to add data to the pool 158.Em before 159returning, the callback 160.Em must 161use 162.Fn rnd_add_data_sync , 163not 164.Fn rnd_add_data 165or 166.Fn rnd_add_uint32 . 167.El 168.It Fn rnd_attach_source "rnd_source" "devname" "type" "flags" 169Makes 170.Fa rnd_source 171available for entropy collection. 172Must be called 173.Em before 174the source struct pointed to by 175.Fa rnd_source 176is used in any of the following functions. 177If a callback was specified with 178.Fn rndsource_setcb , 179the kernel may invoke it at any time after 180.Fn rnd_attach_source 181until 182.Fn rnd_detach_source , 183so the callback must be ready to be invoked 184.Em before 185calling 186.Fn rnd_attach_source . 187.Pp 188The 189.Fa devname 190is exposed via 191.Xr rnd 4 192and 193.Xr rndctl 8 . 194The 195.Fa type 196must be one of the 197.Dv RND_TYPE_* 198constants above. 199The 200.Fa flags 201are the bitwise-or of any of the following constants: 202.Bl -tag -width abcd 203.It Dv RND_FLAG_HASCB 204The random source has a callback, which must have been set with 205.Fn rndsource_setcb . 206.It Dv RND_FLAG_COLLECT_TIME 207Enter the timing of each 208.Fn rnd_add_* 209call into the entropy pool. 210If not set, at most only the data arguments to 211.Fn rnd_add_* 212will be entered. 213.It Dv RND_FLAG_COLLECT_VALUE 214Enter the data arguments passed to the 215.Fn rnd_add_* 216functions into the pool. 217If not set, the data will be ignored; at most the timing of the sample 218will be entered. 219.It Dv RND_FLAG_DEFAULT 220Equivalent to 221.Dv RND_FLAG_COLLECT_TIME | RND_FLAG_COLLECT_VALUE . 222.It Dv RND_FLAG_ESTIMATE_TIME , RND_FLAG_ESTIMATE_VALUE 223Legacy options no longer used. 224.El 225.It Fn rnd_detach_source "rnd_source" 226Disconnects 227.Fa rnd_source 228from entropy collection. 229The kernel will cease to invoke the callback, if any, and the caller 230must not use 231.Fa rnd_source 232with any of the 233.Fn rnd_add_* 234functions after 235.Fn rnd_detach_source . 236The caller may release the memory for 237.Fa rnd_source 238afterward. 239.It Fn rnd_add_data "rnd_source" "data" "len" "entropy" 240Enters 241.Fa len 242bytes at 243.Fa data 244into the entropy pool, if 245.Dv RND_FLAG_COLLECT_VALUE 246was specified for 247.Fa rnd_source , 248and a timestamp, if 249.Dv RND_FLAG_COLLECT_TIME 250was specified. 251.Pp 252The argument 253.Fa entropy 254provides a conservative estimate for the number of bits of entropy in 255the 256.Em physical process 257that generated the data, given all the past samples. 258Drivers for devices for which this is not known should pass zero; 259typically only drivers for hardware random number generators pass 260nonzero values. 261Hardware random number generator drivers should perform on-line 262self-tests before advertising nonzero entropy for samples. 263.Pp 264.Fn rnd_add_data 265.Em must not 266be used during a callback as set with 267.Fn rndsource_setcb ; 268use 269.Fn rnd_add_data_sync 270instead. 271.It Fn rnd_add_data_sync "rnd_source" "data" "len" "entropy" 272Like 273.Fn rnd_add_data , 274but may be used in a callback as set with 275.Fn rndsource_setcb . 276.It Fn rnd_add_uint32 "rnd_source" "datum" 277Equivalent to 278.Li rnd_add_data Ns ( Ns Fa rnd_source , Li & Ns Fa datum , Li 4 , 0 ) . 279.Pp 280.Fn rnd_add_uint32 281.Em must not 282be used during a callback as set with 283.Fn rndsource_setcb ; 284use 285.Fn rnd_add_data_sync 286instead. 287.El 288.Sh FILES 289These functions are declared in src/sys/sys/rndsource.h and defined in 290src/sys/kern/kern_entropy.c. 291.Sh EXAMPLES 292.Bd -literal 293struct xyz_softc { 294 ... 295 struct krndsource sc_rndsource; 296}; 297 298static void 299xyz_attach(device_t parent, device_t self, void *aux) 300{ 301 struct xyz_softc *sc = device_private(self); 302 ... 303 rndsource_setcb(&sc->sc_rndsource, xyz_get, sc); 304 rnd_attach_source(&sc->sc_rndsource, device_xname(self), 305 RND_TYPE_RNG, RND_FLAG_DEFAULT); 306} 307 308static int 309xyz_detach(device_t self, int flags) 310{ 311 ... 312 rnd_detach_source(&sc->sc_rndsource); 313 ... 314 return 0; 315} 316 317static void 318xyz_get(size_t nbytes, void *cookie) 319{ 320 struct xyz_softc *sc = cookie; 321 uint32_t v; 322 unsigned timo = 10; 323 324 while (nbytes) { 325 while (bus_space_read_4(sc->sc_bst, sc->sc_bsh, 326 XYZ_RNGREADY) == 0) { 327 if (--timo == 0) 328 return; 329 DELAY(10); 330 } 331 v = bus_space_read_4(sc->sc_bst, sc->sc_bsh, 332 XYZ_RNGDATUM); 333 /* data sheet sez 18 bits entropy in 32-bit sample */ 334 rnd_add_data_sync(&sc->sc_rndsource, &v, sizeof v, 18); 335 nbytes -= 18/NBBY; 336 } 337} 338 339static void 340xyz_intr(void *cookie) 341{ 342 struct xyz_softc *sc = cookie; 343 uint32_t isr; 344 345 isr = bus_space_read_4(sc->sc_bst, sc->sc_bsh, XYZ_ISR); 346 bus_space_write_4(sc->sc_bst, sc->sc_bsh, XYZ_ISR, isr); 347 rnd_add_uint32(&sc->sc_rndsource, isr); 348 ... 349} 350.Ed 351.Sh SEE ALSO 352.Xr rnd 4 , 353.Xr rndctl 8 , 354.Xr cprng 9 355.Sh HISTORY 356The random device was introduced in 357.Nx 1.3 . 358It was substantially rewritten in 359.Nx 6.0 , 360and again in 361.Nx 10.0 . 362.Sh AUTHORS 363This implementation was written by 364.An Taylor R Campbell Aq Mt riastradh@NetBSD.org . 365