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