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