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