.\" $NetBSD: cprng.9,v 1.10.18.1 2020/03/30 18:31:03 martin Exp $ .\" .\" Copyright (c) 2011-2015 The NetBSD Foundation, Inc. .\" All rights reserved. .\" .\" This code is derived from software contributed to The NetBSD Foundation .\" by Thor Lancelot Simon and Taylor R. Campbell. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" .Dd March 24, 2020 .Dt CPRNG 9 .Os .Sh NAME .Nm cprng , .Nm cprng_strong_create , .Nm cprng_strong_destroy , .Nm cprng_strong , .Nm cprng_strong32 , .Nm cprng_strong64 , .Nm cprng_fast , .Nm cprng_fast32 , .Nm cprng_fast64 , .Nd cryptographic pseudorandom number generators .Sh SYNOPSIS .In sys/cprng.h .Ft cprng_strong_t * .Fn cprng_strong_create "const char *name" "int ipl" "int flags" .Ft void .Fn cprng_strong_destroy "cprng_strong_t *cprng" .Ft size_t .Fn cprng_strong "cprng_strong_t *cprng" "void *buf" "size_t len" "int flags" .Ft uint32_t .Fn cprng_strong32 "void" .Ft uint64_t .Fn cprng_strong64 "void" .Ft size_t .Fn cprng_fast "void *buf" "size_t len" .Ft uint32_t .Fn cprng_fast32 "void" .Ft uint64_t .Fn cprng_fast64 "void" .Bd -literal #define CPRNG_MAX_LEN 524288 .Ed .Sh DESCRIPTION The .Nm family of functions provide cryptographic pseudorandom number generators automatically seeded from the kernel entropy pool. All applications in the kernel requiring random data or random choices should use the .Nm cprng_strong family of functions, unless performance constraints demand otherwise. .Pp The .Nm cprng_fast family of functions may be used in applications that can tolerate exposure of past random data, such as initialization vectors or transaction ids that are sent over the internet anyway, if the applications require higher throughput or lower per-request latency than the .Nm cprng_strong family of functions provide. If in doubt, choose .Nm cprng_strong . .Pp A single instance of the fast generator serves the entire kernel. A well-known instance of the strong generator, .Dv kern_cprng , may be used by any in-kernel caller, but separately seeded instances of the strong generator can also be created by calling .Fn cprng_strong_create . .Pp The .Nm functions may be used at interrupt priority level .Dv IPL_VM or below, except for .Fn cprng_strong_create and .Fn cprng_strong_destroy which are allowed only at .Dv IPL_NONE ; see .Xr spl 9 . .Pp The .Nm functions replace the legacy .Xr arc4random 9 and .Xr rnd_extract_data 9 functions. .Sh FUNCTIONS .Bl -tag -width abcd .It Fn cprng_strong_create "name" "ipl" "flags" Create an instance of the cprng_strong generator. This generator currently implements the NIST SP 800-90A CTR_DRBG with AES-128 as the block transform. .Pp The .Fa name argument is used to .Dq personalize the CTR_DRBG according to the standard, so that its initial state will depend both on seed material from the entropy pool and also on the personalization string (name). .Pp The .Fa ipl argument specifies the interrupt priority level for the mutex which will serialize access to the new instance of the generator (see .Xr spl 9 ) , and must be no higher than .Dv IPL_VM . .Pp The .Fa flags argument controls the behavior of the generator: .Bl -tag -width CPRNG_REKEY_ANY .It Dv CPRNG_INIT_ANY Suppress a warning message to the console if, during .Fn cprng_strong_create , only partial entropy for the generator is available from the entropy pool. .It Dv CPRNG_REKEY_ANY Suppress a warning message to the console if, during .Fn cprng_strong after the generator has been exhausted and must be reseeded, only partial entropy for the generator is available from the entropy pool. .It Dv CPRNG_USE_CV Make .Fn cprng_strong sleep if the generator has not been seeded with full entropy until full entropy is available. Otherwise, .Fn cprng_strong will never sleep when passed this generator. .It Dv CPRNG_HARD Limit the number of bits of output from the generator before reseeding to the number of bits in its seed, so that it approximates the information-theoretic entropy of its seed. Otherwise, the generator may provide many more bits of output than it was seeded with. .El .Pp Creation will succeed even if full entropy for the generator is not available. In this case, the first request to read from the generator may cause reseeding. .Pp .Fn cprng_strong_create may sleep to allocate memory. .It Fn cprng_strong_destroy "cprng" Destroy .Fa cprng . .Pp .Fn cprng_strong_destroy may sleep. .It Fn cprng_strong "cprng" "buf" "len" "flags" Fill memory location .Fa buf with up to .Fa len bytes from the generator .Fa cprng , and return the number of bytes. .Fa len must be at most .Dv CPRNG_MAX_LEN . .Pp If .Fa cprng was created with the .Dv CPRNG_USE_CV flag and has been exhausted, then .Fn cprng_strong may sleep until full entropy can be obtained from the entropy pool to reseed it. However, if .Fa flags includes the .Dv FNONBLOCK flag, then .Fn cprng_strong will immediately return zero in this case instead. .Pp If .Fa cprng was created with the .Dv CPRNG_HARD flag, then .Fn cprng_strong will return at most as many bytes as are left from its seed size since the last reseeding. .Pp If .Fa cprng was created with neither the .Dv CPRNG_USE_CV flag nor the .Dv CPRNG_HARD flag, then .Fn cprng_strong is guaranteed to return as many bytes as requested, up to .Dv CPRNG_MAX_LEN , without sleeping. .It Fn cprng_strong32 Generate 32 bits using the .Dv kern_cprng strong generator. .Pp .Fn cprng_strong32 does not sleep. .It Fn cprng_strong64 Generate 64 bits using the .Dv kern_cprng strong generator. .Pp .Fn cprng_strong64 does not sleep. .It Fn cprng_fast "buf" "len" Fill memory location .Fa buf with .Fa len bytes from the fast generator. .Pp .Fn cprng_fast does not sleep. .It Fn cprng_fast32 Generate 32 bits using the fast generator. .Pp .Fn cprng_fast32 does not sleep. .It Fn cprng_fast64 Generate 64 bits using the fast generator. .Pp .Fn cprng_fast64 does not sleep. .El .Sh SECURITY MODEL The .Nm family of functions provide the following security properties: .Bl -bullet -offset abcd .It An attacker who has seen some outputs of any of the .Nm functions cannot predict past or future unseen outputs. .It An attacker who has compromised kernel memory cannot predict past outputs of the .Nm cprng_strong functions. However, such an attacker may be able to predict past outputs of the .Nm cprng_fast functions. .El .Pp The second property is sometimes called .Dq backtracking resistance , .Dq forward secrecy , or .Dq key erasure in the cryptography literature. The .Nm cprng_strong functions provide backtracking resistance; the .Nm cprng_fast functions do not. .Sh CODE REFERENCES The .Nm cprng_strong functions are implemented in .Pa sys/kern/subr_cprng.c , and use the NIST SP 800-90A CTR_DRBG implementation in .Pa sys/crypto/nist_ctr_drbg . The .Nm cprng_fast functions are implemented in .Pa sys/crypto/cprng_fast/cprng_fast.c , and use the ChaCha8 stream cipher. .Sh SEE ALSO .Xr condvar 9 , .Xr rnd 9 , .Xr spl 9 .Rs .%A Elaine Barker .%A John Kelsey .%T Recommendation for Random Number Generation Using Deterministic Random Bit Generators (Revised) .%I National Institute of Standards and Technology .%D 2011 .%O NIST Special Publication 800-90A, Rev 1 .Re .Rs .%A Daniel J. Bernstein .%T ChaCha, a variant of Salsa20 .%D 2008-01-28 .%O Document ID: 4027b5256e17b9796842e6d0f68b0b5e .%U http://cr.yp.to/papers.html#chacha .Re .Sh HISTORY The cprng family of functions first appeared in .Nx 6.0 .