.\"	$NetBSD: cprng.9,v 1.9 2014/03/18 18:20:40 riastradh Exp $
.\"
.\" Copyright (c) 2011-2013 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 July 18, 2013
.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 uint32_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.
They replace the
.Xr arc4random 9
and
.Xr rnd_extract_data 9
functions for this purpose.
The
.Nx
kernel no longer supports direct reading from the kernel entropy pool; all
access is mediated by the
.Nm
functions.
.Pp
The
.Dq strong
family of functions use cryptographically strong pseudorandom number
generators suitable for keying crypto systems and similar purposes.
Calls to
.Xr rnd_extract_data 9
should be replaced by calls to
.Fn cprng_strong .
.Pp
The
.Dq fast
family of functions use cryptographically weaker pseudorandom number
generators suitable for initialization vectors, nonces in certain
protocols, and other similar purposes, using a faster but less secure
stream-cipher-based generator.
Calls to
.Xr arc4random 9
should be replaced by calls to
.Fn cprng_fast32 ,
and calls to
.Xr arc4randbytes 9
should be replaced by calls to
.Fn cprng_fast .
.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 .
.Sh FUNCTIONS
.Bl -tag -width abcd
.It Fn cprng_strong_create "name" "ipl" "flags"
Create an instance of the cprng_strong generator.
This generator implements the NIST SP 800-90 CTR_DRBG with AES128 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 CODE REFERENCES
The cprng API is implemented by
.Pa sys/kern/subr_cprng.c
and
.Pa sys/sys/cprng.h .
The
.Dq strong
generator uses the CTR_DRBG implementation in
.Pa sys/crypto/nist_ctr_drbg .
The
.Dq fast
generator uses the arc4random implementation in
.Pa sys/lib/libkern/arc4random.c .
.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
.Sh HISTORY
The cprng family of functions first appeared in
.Nx 6.0 .