NetBSD/share/man/man9/cprng.9

.\"	$NetBSD: cprng.9,v 1.5 2011/12/17 21:24:40 wiz Exp $
.\"
.\" Copyright (c) 2011 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Thor Lancelot Simon.
.\"
.\" 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 December 17, 2011
.Dt CPRNG 9
.Os
.Sh NAME
.Nm cprng ,
.Nm cprng_strong_create ,
.Nm cprng_strong ,
.Nm cprng_strong32 ,
.Nm cprng_strong64 ,
.Nm cprng_strong_getflags ,
.Nm cprng_strong_setflags ,
.Nm cprng_strong_ready ,
.Nm cprng_strong_destroy ,
.Nm cprng_fast ,
.Nm cprng_fast32 ,
.Nm cprng_fast64 ,
.Nd cryptographic pseudo-random number generators
.Sh SYNOPSIS
.In sys/cprng.h
.Ft cprng_strong_t
.Fn cprng_strong_create "const char *const name" "int ipl" "int flags"
.Ft void
.Fn cprng_strong_destroy "cprng_strong_t *cprng"
.Ft size_t
.Fn cprng_strong "cprng_strong_t *const cprng" "void *buf" "size_t len" "int blocking"
.Ft size_t
.Fn cprng_fast "void *buf" "size_t len"
.Ft uint32_t
.Fn cprng_strong32 "void"
.Ft uint64_t
.Fn cprng_strong64 "void"
.Ft uint32_t
.Fn cprng_fast32 "void"
.Ft uint32_t
.Fn cprng_fast64 "void"
.Ft int
.Fn cprng_strong_getflags "cprng_strong_t *const cprng"
.Ft void
.Fn cprng_strong_setflags "cprng_strong_t *const cprng" "int flags"
.Bd -literal
#define CPRNG_MAX_LEN   524288

typedef struct _cprng_strong {
        kmutex_t	mtx;
        kcondvar_t	cv;
	struct selinfo	selq;
        NIST_CTR_DRBG	drbg;
        int		flags;
        char		name[16];
        int		reseed_pending;
        rndsink_t	reseed;
} cprng_strong_t;
.Ed
.Sh DESCRIPTION
The
.Nm
family of functions supply randomness to callers within the
.Nx
kernel.
They replace the
.Xr arc4random 9
and
.Xr rnd_extract_data 9
functions for this purpose.
The
.Nm
functions provide stream generators automatically keyed (and if
necessary rekeyed) from the kernel entropy pool.
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 supply cryptographically strong random numbers
suitable for keying crypto systems and similar purposes.
Calls to
.Xr rnd_extract_data 9
should be replaced with calls to
.Nm cprng_strong .
.Pp
The
.Dq fast
family of functions supply less strong random numbers, suitable for
initialization vectors, nonces in certain protocols, and other
similar purposes, using a faster but less secure stream-cipher generator.
stream-cipher generator.
Calls to
.Xr arc4random 9
should be replaced with calls to
.Nm cprng_fast32 ,
and calls to
.Xr arc4randbytes 9
should be replaced with calls to
.Nm cprng_fast .
.Pp
A single instance of the
.Nm cprng_fast
generator serves the entire kernel.
A single, well-known instance of the
.Nm cprng_strong
generator,
.Dv kern_cprng ,
may be used by any in-kernel caller, but
new separately-keyed instances of the
.Nm cprng_strong
generator can also be created by calling
.Nm cprng_strong_create .
.Sh FUNCTIONS
.Bl -tag -width abcd
.It Fn cprng_strong_create "name" "ipl" "flags"
.Pp
Create an instance of the cprng_strong generator.
This generator
implements the NIST SP 800-90 CTR_DRBG with AES128 as the block transform.
The
.Fa name
argument is used to "personalize" the CTR_DRBG according to the standard,
so that its initial state will depend both on keying material from the
entropy pool and also on the personalization string (name).
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 ) .
The
.Fa flags
argument controls the behavior of the generator:
.Bl -tag -width CPRNG_REKEY_ANY
.It Dv CPRNG_INIT_ANY
Perform initial keying of the generator from the entropy pool even if
the current estimate of entropy in the pool is less than the required
number of key bits for the generator.
.It Dv CPRNG_REKEY_ANY
When rekeying of the generator is required, key the generator from the
entropy pool even if the current estimate of entropy in the pool is less
than the required number of key bits for the generator.
.It Dv CPRNG_USE_CV
Perform a
.Xr cv_broadcast 9
operation on the "cv" member of the returned cprng_strong_t each time
the generator is successfully rekeyed.
.Em If this flag is set, the generator will sleep when rekeying is needed,
.Em and will therefore always return the requested number of bytes.
.El
.Pp
Creation will succeed even if key material for the generator is not
available.
In this case, the first request to read from the generator
may cause rekeying.
.It Fn cprng_strong_destroy "cprng"
.Pp
Destroy an instance of the cprng_strong generator.
.It Fn cprng_strong "cprng" "buf" "len" "blocking"
.Pp
Fill memory location
.Fa buf
with
.Fa len
bytes from the generator
.Fa cprng .
The
.Fa blocking
argument controls the blocking/non-blocking behavior of the
generator: if it is set to
.Dv FNONBLOCK ,
the generator may return less than
.Fa len
bytes if it requires rekeying.
If the
.Dv CPRNG_USE_CV
flag is set on the generator, the caller can wait on
.Dv cprng->cv
for notification that the generator can again supply bytes.
A maximum of
.Dv CPRNG_MAX_LEN
bytes may be requested at once; this is a restriction of the
CTR_DRBG specification.
.It Fn cprng_strong32 "cprng"
.Pp
Generate 32 bits using cprng_strong generator
.Fa cprng .
.It Fn cprng_strong64 "cprng"
.Pp
Generate 64 bits using cprng_strong generator
.Fa cprng .
.It Fn cprng_strong_getflags "cprng"
.Pp
Get the flags currently in use by generator
.Fa cprng .
.It Fn cprng_strong_setflags "cprng" "flags"
Set the flags on generator
.Fa cprng
to
.Fa flags .
.It Fn cprng_fast "buf" "len"
Fill memory location
.Fa buf
with
.Fa len
bytes from the fast generator.
.It Fn cprng_fast32
Generate 32 bits using the fast generator.
.It Fn cprng_fast64
Generate 64 bits using the fast generator.
.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
.Pp
.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 .