.\"	$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 .