1.\" $NetBSD: cprng.9,v 1.14 2020/08/17 06:07:53 wiz 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 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 Hash_DRBG with 120SHA-256 as the hash function. 121.Pp 122The 123.Fa name 124argument is used to 125.Dq personalize 126the Hash_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 must be zero. 141.Pp 142Creation will succeed even if full entropy for the generator is not 143available. 144In this case, the first request to read from the generator may cause 145reseeding. 146.Pp 147.Fn cprng_strong_create 148may sleep to allocate memory. 149.It Fn cprng_strong_destroy "cprng" 150Destroy 151.Fa cprng . 152.Pp 153.Fn cprng_strong_destroy 154may sleep. 155.It Fn cprng_strong "cprng" "buf" "len" "flags" 156Fill memory location 157.Fa buf 158with up to 159.Fa len 160bytes from the generator 161.Fa cprng , 162and return the number of bytes. 163.Fa len 164must be at most 165.Dv CPRNG_MAX_LEN . 166.Fa flags 167must be zero. 168.It Fn cprng_strong32 169Generate 32 bits using the 170.Dv kern_cprng 171strong generator. 172.Pp 173.Fn cprng_strong32 174does not sleep. 175.It Fn cprng_strong64 176Generate 64 bits using the 177.Dv kern_cprng 178strong generator. 179.Pp 180.Fn cprng_strong64 181does not sleep. 182.It Fn cprng_fast "buf" "len" 183Fill memory location 184.Fa buf 185with 186.Fa len 187bytes from the fast generator. 188.Pp 189.Fn cprng_fast 190does not sleep. 191.It Fn cprng_fast32 192Generate 32 bits using the fast generator. 193.Pp 194.Fn cprng_fast32 195does not sleep. 196.It Fn cprng_fast64 197Generate 64 bits using the fast generator. 198.Pp 199.Fn cprng_fast64 200does not sleep. 201.El 202.Sh SECURITY MODEL 203The 204.Nm 205family of functions provide the following security properties: 206.Bl -bullet -offset abcd 207.It 208An attacker who has seen some outputs of any of the 209.Nm 210functions cannot predict past or future unseen outputs. 211.It 212An attacker who has compromised kernel memory cannot predict past 213outputs of the 214.Nm cprng_strong 215functions. 216However, such an attacker may be able to predict past outputs of the 217.Nm cprng_fast 218functions. 219.El 220.Pp 221The second property is sometimes called 222.Dq backtracking resistance , 223.Dq forward secrecy , 224or 225.Dq key erasure 226in the cryptography literature. 227The 228.Nm cprng_strong 229functions provide backtracking resistance; 230the 231.Nm cprng_fast 232functions do not. 233.Sh CODE REFERENCES 234The 235.Nm cprng_strong 236functions are implemented in 237.Pa sys/kern/subr_cprng.c , 238and use the NIST SP 800-90A Hash_DRBG implementation in 239.Pa sys/crypto/nist_hash_drbg . 240The 241.Nm cprng_fast 242functions are implemented in 243.Pa sys/crypto/cprng_fast/cprng_fast.c , 244and use the ChaCha8 stream cipher. 245.Sh SEE ALSO 246.Xr condvar 9 , 247.Xr rnd 9 , 248.Xr spl 9 249.Rs 250.%A Elaine Barker 251.%A John Kelsey 252.%T Recommendation for Random Number Generation Using Deterministic Random Bit Generators (Revised) 253.%I National Institute of Standards and Technology 254.%D 2011 255.%O NIST Special Publication 800-90A, Rev 1 256.Re 257.Rs 258.%A Daniel J. Bernstein 259.%T ChaCha, a variant of Salsa20 260.%D 2008-01-28 261.%O Document ID: 4027b5256e17b9796842e6d0f68b0b5e 262.%U http://cr.yp.to/papers.html#chacha 263.Re 264.Sh HISTORY 265The cprng family of functions first appeared in 266.Nx 6.0 . 267