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