1.\" $NetBSD: cprng.9,v 1.2 2011/11/28 23:27:59 wiz Exp $ 2.\" 3.\" Copyright (c) 2011 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. 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 November 28, 2011 31.Dt CPRNG 9 32.Os 33.Sh NAME 34.Nm cprng , 35.Nm cprng_strong_create , 36.Nm cprng_strong , 37.Nm cprng_strong32 , 38.Nm cprng_strong64 , 39.Nm cprng_strong_getflags , 40.Nm cprng_strong_setflags , 41.Nm cprng_strong_destroy , 42.Nm cprng_fast , 43.Nm cprng_fast32 , 44.Nm cprng_fast64 , 45.Nd cryptographic pseudorandom number generators 46.Sh SYNOPSIS 47.In sys/cprng.h 48.Ft cprng_strong_t 49.Fn cprng_strong_create "const char *const name" "int ipl" "int flags" 50.Ft void 51.Fn cprng_strong_destroy "cprng_strong_t *cprng" 52.Ft size_t 53.Fn cprng_strong "cprng_strong_t *const cprng" "void *buf" "size_t len" 54.Ft size_t 55.Fn cprng_fast "void *buf" "size_t len" 56.Ft uint32_t 57.Fn cprng_strong32 "void" 58.Ft uint64_t 59.Fn cprng_strong64 "void" 60.Ft uint32_t 61.Fn cprng_fast32 "void" 62.Ft uint32_t 63.Fn cprng_fast64 "void" 64.Ft int 65.Fn cprng_strong_getflags "cprng_strong_t *const cprng" 66.Ft void 67.Fn cprng_strong_setflags "cprng_strong_t *const cprng" "int flags" 68.Bd -literal 69#define CPRNG_MAX_LEN 524288 70 71typedef struct _cprng_strong { 72 kmutex_t mtx; 73 kcondvar_t cv; 74 NIST_CTR_DRBG drbg; 75 int flags; 76 char name[16]; 77 int reseed_pending; 78 rndsink_t reseed; 79} cprng_strong_t; 80.Ed 81.Sh DESCRIPTION 82The 83.Nm 84family of functions supply randomness to callers within the 85.Nx 86kernel. 87They replace the 88.Xr arc4random 9 89and 90.Xr rnd_extract_data 9 91functions for this purpose. 92The 93.Nm 94functions provide stream generators automatically keyed (and if 95necessary rekeyed) from the kernel entropy pool. 96The 97.Nx 98kernel no longer supports direct reading from the kernel entropy pool; all 99access is mediated by the 100.Nm 101functions. 102.Pp 103The 104.Dq strong 105family of functions supply cryptographically strong random numbers 106suitable for keying cryptosystems and similar purposes. 107Calls to 108.Xr rnd_extract_data 9 109should be replaced with calls to 110.Nm cprng_strong . 111.Pp 112The 113.Dq fast 114family of functions supply less strong random numbers, suitable for 115initialization vectors, nonces in certain protocols, and other 116similar purposes, using a faster but less secure stream-cipher generator. 117stream-cipher generator. 118Calls to 119.Xr arc4random 9 120should be replaced with calls to 121.Nm cprng_fast32 , 122and calls to 123.Xr arc4randbytes 9 124should be replaced with calls to 125.Nm cprng_fast . 126.Pp 127A single instance of the 128.Nm cprng_fast 129generator serves the entire kernel. 130A single, well-known instance of the 131.Nm cprng_strong 132generator, 133.Dv kern_cprng , 134may be used by any in-kernel caller, but 135new separately-keyed instances of the 136.Nm cprng_strong 137generator can also be created by calling 138.Nm cprng_strong_create . 139.Sh FUNCTIONS 140.Bl -tag -width abcd 141.It Fn cprng_strong_create "name" "ipl" "flags" 142.Pp 143Create an instance of the cprng_strong generator. 144This generator 145implements the NIST SP 800-90 CTR_DRBG with AES128 as the block transform. 146The 147.Fa name 148argument is used to "personalize" the CTR_DRBG according to the standard, 149so that its initial state will depend both on keying material from the 150entropy pool and also on the personalization string (name). 151The 152.Fa ipl 153argument specifies the interrupt priority level for the mutex which will 154serialize access to the new instance of the generator (see 155.Xr spl 9 ) . 156The 157.Fa flags 158argument controls the behavior of the generator: 159.Bl -tag -width CPRNG_REKEY_ANY 160.It Dv CPRNG_INIT_ANY 161Perform initial keying of the generator from the entropy pool even if 162the current estimate of entropy in the pool is less than the required 163number of key bits for the generator. 164.It Dv CPRNG_REKEY_ANY 165When rekeying of the generator is required, key the generator from the 166entrpy pool even if the current estimate of entropy in the pool is less 167than the required number of key bits for the generator. 168.It Dv CPRNG_USE_CV 169Perform a 170.Xr cv_broadcast 9 171operation on the "cv" member of the returned cprng_strong_t each time 172the generator is successfully rekeyed. 173.El 174.Pp 175Creation will succeed even if key material for the generator is not 176available. 177In this case, the first request to read from the generator 178may cause rekeying. 179.It Fn cprng_strong_destroy "cprng" 180.Pp 181Destroy an instance of the cprng_strong generator. 182.It Fn cprng_strong "cprng" "buf" "len" 183.Pp 184Fill memory location 185.Fa buf 186with 187.Fa len 188bytes from the generator 189.Fa cprng . 190If less than 191.Fa len 192bytes are returned, the generator requires rekeying. 193If the 194.Dv CPRNG_USE_CV 195flag is set on the generator, the caller can wait on 196.Dv cprng->cv 197for notification that the generator can again supply bytes. 198A maximum of 199.Dv CPRNG_MAX_LEN 200bytes may be requested at once; this is a restriction of the 201CTR_DRBG specification. 202.It Fn cprng_strong32 "cprng" 203.Pp 204Generate 32 bits using cprng_strong generator 205.Fa cprng . 206.It Fn cprng_strong64 "cprng" 207.Pp 208Generate 64 bits using cprng_strong generator 209.Fa cprng . 210.It Fn cprng_strong_getflags "cprng" 211.Pp 212Get the flags currently in use by generator 213.Fa cprng . 214.It Fn cprng_strong_setflags "cprng" "flags" 215Set the flags on generator 216.Fa cprng 217to 218.Fa flags . 219.It Fn cprng_fast "buf" "len" 220Fill memory location 221.Fa buf 222with 223.Fa len 224bytes from the fast generator. 225.It Fn cprng_fast32 226Generate 32 bits using the fast generator. 227.It Fn cprng_fast64 228Generate 64 bits using the fast generator. 229.El 230.Sh CODE REFERENCES 231The cprng API is implemented by 232.Pa sys/kern/subr_cprng.c 233and 234.Pa sys/sys/cprng.h . 235The 236.Dq strong 237generator uses the CTR_DRBG implementation in 238.Pa sys/crypto/nist_ctr_drbg . 239The 240.Dq fast 241generator uses the arc4random implementation in 242.Pa sys/lib/libkern/arc4random.c . 243.Sh SEE ALSO 244.Xr condvar 9 , 245.Xr rnd 9 , 246.Xr spl 9 247.Pp 248.Rs 249.%A Elaine Barker 250.%A John Kelsey 251.%T Recommendation for Random Number Generation Using Deterministic Random Bit Generators (Revised) 252.%I National Institute of Standards and Technology 253.%D 2011 254.%O NIST Special Publication 800-90A, Rev 1 255.Re 256.Sh HISTORY 257The cprng family of functions first appeared in 258.Nx 6.0 . 259