diff options
Diffstat (limited to 'static/netbsd/man9/cprng.9')
| -rw-r--r-- | static/netbsd/man9/cprng.9 | 264 |
1 files changed, 264 insertions, 0 deletions
diff --git a/static/netbsd/man9/cprng.9 b/static/netbsd/man9/cprng.9 new file mode 100644 index 00000000..b7decf41 --- /dev/null +++ b/static/netbsd/man9/cprng.9 @@ -0,0 +1,264 @@ +.\" $NetBSD: cprng.9,v 1.16 2022/05/17 15:00:05 riastradh 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 August 16, 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 in soft interrupt context, +except for +.Fn cprng_strong_create +and +.Fn cprng_strong_destroy +which are allowed only at +.Dv IPL_NONE +in thread context; 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 Hash_DRBG with +SHA-256 as the hash function. +.Pp +The +.Fa name +argument is used to +.Dq personalize +the Hash_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_SOFTSERIAL . +.Pp +The +.Fa flags +argument must be zero. +.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 . +.Fa flags +must be zero. +.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 Hash_DRBG implementation in +.Pa sys/crypto/nist_hash_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 . |