1.\" $NetBSD: cprng.9,v 1.10 2015/02/19 15:38:30 riastradh Exp $ 2.\" 3.\" Copyright (c) 2011-2015 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Thor Lancelot Simon and Taylor R. Campbell. 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 February 19, 2015 31.Dt CPRNG 9 32.Os 33.Sh NAME 34.Nm cprng , 35.Nm cprng_strong_create , 36.Nm cprng_strong_destroy , 37.Nm cprng_strong , 38.Nm cprng_strong32 , 39.Nm cprng_strong64 , 40.Nm cprng_fast , 41.Nm cprng_fast32 , 42.Nm cprng_fast64 , 43.Nd cryptographic pseudorandom number generators 44.Sh SYNOPSIS 45.In sys/cprng.h 46.Ft cprng_strong_t * 47.Fn cprng_strong_create "const char *name" "int ipl" "int flags" 48.Ft void 49.Fn cprng_strong_destroy "cprng_strong_t *cprng" 50.Ft size_t 51.Fn cprng_strong "cprng_strong_t *cprng" "void *buf" "size_t len" "int flags" 52.Ft uint32_t 53.Fn cprng_strong32 "void" 54.Ft uint64_t 55.Fn cprng_strong64 "void" 56.Ft size_t 57.Fn cprng_fast "void *buf" "size_t len" 58.Ft uint32_t 59.Fn cprng_fast32 "void" 60.Ft uint32_t 61.Fn cprng_fast64 "void" 62.Bd -literal 63#define CPRNG_MAX_LEN 524288 64.Ed 65.Sh DESCRIPTION 66The 67.Nm 68family of functions provide cryptographic pseudorandom number 69generators automatically seeded from the kernel entropy pool. 70All applications in the kernel requiring random data or random choices 71should use the 72.Nm cprng_strong 73family of functions, unless performance constraints demand otherwise. 74.Pp 75The 76.Nm cprng_fast 77family of functions may be used in applications that can tolerate 78exposure of past random data, such as initialization vectors or 79transaction ids that are sent over the internet anyway, if the 80applications require higher throughput or lower per-request latency 81than the 82.Nm cprng_strong 83family of functions provide. 84If in doubt, choose 85.Nm cprng_strong . 86.Pp 87A single instance of the fast generator serves the entire kernel. 88A well-known instance of the strong generator, 89.Dv kern_cprng , 90may be used by any in-kernel caller, but separately seeded instances of 91the strong generator can also be created by calling 92.Fn cprng_strong_create . 93.Pp 94The 95.Nm 96functions may be used at interrupt priority level 97.Dv IPL_VM 98or below, 99except for 100.Fn cprng_strong_create 101and 102.Fn cprng_strong_destroy 103which are allowed only at 104.Dv IPL_NONE ; 105see 106.Xr spl 9 . 107.Pp 108The 109.Nm 110functions replace the legacy 111.Xr arc4random 9 112and 113.Xr rnd_extract_data 9 114functions. 115.Sh FUNCTIONS 116.Bl -tag -width abcd 117.It Fn cprng_strong_create "name" "ipl" "flags" 118Create an instance of the cprng_strong generator. 119This generator currently implements the NIST SP 800-90A CTR_DRBG with 120AES-128 as the block transform. 121.Pp 122The 123.Fa name 124argument is used to 125.Dq personalize 126the CTR_DRBG according to the standard, so that its initial state will 127depend both on seed material from the entropy pool and also on the 128personalization string (name). 129.Pp 130The 131.Fa ipl 132argument specifies the interrupt priority level for the mutex which 133will serialize access to the new instance of the generator (see 134.Xr spl 9 ) , 135and must be no higher than 136.Dv IPL_VM . 137.Pp 138The 139.Fa flags 140argument controls the behavior of the generator: 141.Bl -tag -width CPRNG_REKEY_ANY 142.It Dv CPRNG_INIT_ANY 143Suppress a warning message to the console if, during 144.Fn cprng_strong_create , 145only partial entropy for the generator is available from the entropy 146pool. 147.It Dv CPRNG_REKEY_ANY 148Suppress a warning message to the console if, during 149.Fn cprng_strong 150after the generator has been exhausted and must be reseeded, only 151partial entropy for the generator is available from the entropy pool. 152.It Dv CPRNG_USE_CV 153Make 154.Fn cprng_strong 155sleep if the generator has not been seeded with full entropy until full 156entropy is available. 157Otherwise, 158.Fn cprng_strong 159will never sleep when passed this generator. 160.It Dv CPRNG_HARD 161Limit the number of bits of output from the generator before reseeding 162to the number of bits in its seed, so that it approximates the 163information-theoretic entropy of its seed. 164Otherwise, the generator may provide many more bits of output than it 165was seeded with. 166.El 167.Pp 168Creation will succeed even if full entropy for the generator is not 169available. 170In this case, the first request to read from the generator may cause 171reseeding. 172.Pp 173.Fn cprng_strong_create 174may sleep to allocate memory. 175.It Fn cprng_strong_destroy "cprng" 176Destroy 177.Fa cprng . 178.Pp 179.Fn cprng_strong_destroy 180may sleep. 181.It Fn cprng_strong "cprng" "buf" "len" "flags" 182Fill memory location 183.Fa buf 184with up to 185.Fa len 186bytes from the generator 187.Fa cprng , 188and return the number of bytes. 189.Fa len 190must be at most 191.Dv CPRNG_MAX_LEN . 192.Pp 193If 194.Fa cprng 195was created with the 196.Dv CPRNG_USE_CV 197flag and has been exhausted, then 198.Fn cprng_strong 199may sleep until full entropy can be obtained from the entropy pool to 200reseed it. 201However, if 202.Fa flags 203includes the 204.Dv FNONBLOCK 205flag, then 206.Fn cprng_strong 207will immediately return zero in this case instead. 208.Pp 209If 210.Fa cprng 211was created with the 212.Dv CPRNG_HARD 213flag, then 214.Fn cprng_strong 215will return at most as many bytes as are left from its seed size since 216the last reseeding. 217.Pp 218If 219.Fa cprng 220was created with neither the 221.Dv CPRNG_USE_CV 222flag nor the 223.Dv CPRNG_HARD 224flag, then 225.Fn cprng_strong 226is guaranteed to return as many bytes as requested, up to 227.Dv CPRNG_MAX_LEN , 228without sleeping. 229.It Fn cprng_strong32 230Generate 32 bits using the 231.Dv kern_cprng 232strong generator. 233.Pp 234.Fn cprng_strong32 235does not sleep. 236.It Fn cprng_strong64 237Generate 64 bits using the 238.Dv kern_cprng 239strong generator. 240.Pp 241.Fn cprng_strong64 242does not sleep. 243.It Fn cprng_fast "buf" "len" 244Fill memory location 245.Fa buf 246with 247.Fa len 248bytes from the fast generator. 249.Pp 250.Fn cprng_fast 251does not sleep. 252.It Fn cprng_fast32 253Generate 32 bits using the fast generator. 254.Pp 255.Fn cprng_fast32 256does not sleep. 257.It Fn cprng_fast64 258Generate 64 bits using the fast generator. 259.Pp 260.Fn cprng_fast64 261does not sleep. 262.El 263.Sh SECURITY MODEL 264The 265.Nm 266family of functions provide the following security properties: 267.Bl -bullet -offset abcd 268.It 269An attacker who has seen some outputs of any of the 270.Nm 271functions cannot predict past or future unseen outputs. 272.It 273An attacker who has compromised kernel memory cannot predict past 274outputs of the 275.Nm cprng_strong 276functions. 277However, such an attacker may be able to predict past outputs of the 278.Nm cprng_fast 279functions. 280.El 281.Pp 282The second property is sometimes called 283.Dq backtracking resistance , 284.Dq forward secrecy , 285or 286.Dq key erasure 287in the cryptography literature. 288The 289.Nm cprng_strong 290functions provide backtracking resistance; 291the 292.Nm cprng_fast 293functions do not. 294.Sh CODE REFERENCES 295The 296.Nm cprng_strong 297functions are implemented in 298.Pa sys/kern/subr_cprng.c , 299and use the NIST SP 800-90A CTR_DRBG implementation in 300.Pa sys/crypto/nist_ctr_drbg . 301The 302.Nm cprng_fast 303functions are implemented in 304.Pa sys/crypto/cprng_fast/cprng_fast.c , 305and use the ChaCha8 stream cipher. 306.Sh SEE ALSO 307.Xr condvar 9 , 308.Xr rnd 9 , 309.Xr spl 9 310.Rs 311.%A Elaine Barker 312.%A John Kelsey 313.%T Recommendation for Random Number Generation Using Deterministic Random Bit Generators (Revised) 314.%I National Institute of Standards and Technology 315.%D 2011 316.%O NIST Special Publication 800-90A, Rev 1 317.Re 318.Rs 319.%A Daniel J. Bernstein 320.%T ChaCha, a variant of Salsa20 321.%D 2008-01-28 322.%O Document ID: 4027b5256e17b9796842e6d0f68b0b5e 323.%U http://cr.yp.to/papers.html#chacha 324.Re 325.Sh HISTORY 326The cprng family of functions first appeared in 327.Nx 6.0 . 328