328 lines
8.5 KiB
Groff
328 lines
8.5 KiB
Groff
.\" $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 .
|