268 lines
7.6 KiB
Groff
268 lines
7.6 KiB
Groff
.\" $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 .
|