1.\" $NetBSD: cprng.9,v 1.16 2022/05/17 15:00:05 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 August 16, 2020 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 uint64_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 in soft interrupt context, 97except for 98.Fn cprng_strong_create 99and 100.Fn cprng_strong_destroy 101which are allowed only at 102.Dv IPL_NONE 103in thread context; see 104.Xr spl 9 . 105.Pp 106The 107.Nm 108functions replace the legacy 109.Xr arc4random 9 110and 111.Xr rnd_extract_data 9 112functions. 113.Sh FUNCTIONS 114.Bl -tag -width abcd 115.It Fn cprng_strong_create "name" "ipl" "flags" 116Create an instance of the cprng_strong generator. 117This generator currently implements the NIST SP 800-90A Hash_DRBG with 118SHA-256 as the hash function. 119.Pp 120The 121.Fa name 122argument is used to 123.Dq personalize 124the Hash_DRBG according to the standard, so that its initial state will 125depend both on seed material from the entropy pool and also on the 126personalization string (name). 127.Pp 128The 129.Fa ipl 130argument specifies the interrupt priority level for the mutex which 131will serialize access to the new instance of the generator (see 132.Xr spl 9 ) , 133and must be no higher than 134.Dv IPL_SOFTSERIAL . 135.Pp 136The 137.Fa flags 138argument must be zero. 139.Pp 140Creation will succeed even if full entropy for the generator is not 141available. 142In this case, the first request to read from the generator may cause 143reseeding. 144.Pp 145.Fn cprng_strong_create 146may sleep to allocate memory. 147.It Fn cprng_strong_destroy "cprng" 148Destroy 149.Fa cprng . 150.Pp 151.Fn cprng_strong_destroy 152may sleep. 153.It Fn cprng_strong "cprng" "buf" "len" "flags" 154Fill memory location 155.Fa buf 156with up to 157.Fa len 158bytes from the generator 159.Fa cprng , 160and return the number of bytes. 161.Fa len 162must be at most 163.Dv CPRNG_MAX_LEN . 164.Fa flags 165must be zero. 166.It Fn cprng_strong32 167Generate 32 bits using the 168.Dv kern_cprng 169strong generator. 170.Pp 171.Fn cprng_strong32 172does not sleep. 173.It Fn cprng_strong64 174Generate 64 bits using the 175.Dv kern_cprng 176strong generator. 177.Pp 178.Fn cprng_strong64 179does not sleep. 180.It Fn cprng_fast "buf" "len" 181Fill memory location 182.Fa buf 183with 184.Fa len 185bytes from the fast generator. 186.Pp 187.Fn cprng_fast 188does not sleep. 189.It Fn cprng_fast32 190Generate 32 bits using the fast generator. 191.Pp 192.Fn cprng_fast32 193does not sleep. 194.It Fn cprng_fast64 195Generate 64 bits using the fast generator. 196.Pp 197.Fn cprng_fast64 198does not sleep. 199.El 200.Sh SECURITY MODEL 201The 202.Nm 203family of functions provide the following security properties: 204.Bl -bullet -offset abcd 205.It 206An attacker who has seen some outputs of any of the 207.Nm 208functions cannot predict past or future unseen outputs. 209.It 210An attacker who has compromised kernel memory cannot predict past 211outputs of the 212.Nm cprng_strong 213functions. 214However, such an attacker may be able to predict past outputs of the 215.Nm cprng_fast 216functions. 217.El 218.Pp 219The second property is sometimes called 220.Dq backtracking resistance , 221.Dq forward secrecy , 222or 223.Dq key erasure 224in the cryptography literature. 225The 226.Nm cprng_strong 227functions provide backtracking resistance; 228the 229.Nm cprng_fast 230functions do not. 231.Sh CODE REFERENCES 232The 233.Nm cprng_strong 234functions are implemented in 235.Pa sys/kern/subr_cprng.c , 236and use the NIST SP 800-90A Hash_DRBG implementation in 237.Pa sys/crypto/nist_hash_drbg . 238The 239.Nm cprng_fast 240functions are implemented in 241.Pa sys/crypto/cprng_fast/cprng_fast.c , 242and use the ChaCha8 stream cipher. 243.Sh SEE ALSO 244.Xr condvar 9 , 245.Xr rnd 9 , 246.Xr spl 9 247.Rs 248.%A Elaine Barker 249.%A John Kelsey 250.%T Recommendation for Random Number Generation Using Deterministic Random Bit Generators (Revised) 251.%I National Institute of Standards and Technology 252.%D 2011 253.%O NIST Special Publication 800-90A, Rev 1 254.Re 255.Rs 256.%A Daniel J. Bernstein 257.%T ChaCha, a variant of Salsa20 258.%D 2008-01-28 259.%O Document ID: 4027b5256e17b9796842e6d0f68b0b5e 260.%U http://cr.yp.to/papers.html#chacha 261.Re 262.Sh HISTORY 263The cprng family of functions first appeared in 264.Nx 6.0 . 265