Aren/NetBSD
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add cprng(9) manual page, remove arc4random(9) manual page

Browse Source
This commit is contained in:
tls 2011-11-28 20:19:25 +00:00
parent 8f2dc14263
commit 2a139c3401
5 changed files with 303 additions and 92 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
distrib/sets/lists/comp/mi
View File

@ -1,4 +1,4 @@
# $NetBSD: mi,v 1.1713 2011/11/28 16:22:15 tron Exp $
# $NetBSD: mi,v 1.1714 2011/11/28 20:19:25 tls Exp $
#
# Note: don't delete entries from here - mark them as "obsolete" instead.
#
@ -9779,6 +9779,17 @@
./usr/share/man/cat9/copyoutstr.0 comp-sys-catman .cat
./usr/share/man/cat9/copystr.0 comp-sys-catman .cat
./usr/share/man/cat9/coredump_write.0 comp-sys-catman .cat
./usr/share/man/cat9/cprng.0 comp-sys-catman .cat
./usr/share/man/cat9/cprng_strong.0 comp-sys-catman .cat
./usr/share/man/cat9/cprng_strong_create.0 comp-sys-catman .cat
./usr/share/man/cat9/cprng_strong_destroy.0 comp-sys-catman .cat
./usr/share/man/cat9/cprng_strong_getflags.0 comp-sys-catman .cat
./usr/share/man/cat9/cprng_strong_setflags.0 comp-sys-catman .cat
./usr/share/man/cat9/cprng_strong32.0 comp-sys-catman .cat
./usr/share/man/cat9/cprng_strong64.0 comp-sys-catman .cat
./usr/share/man/cat9/cprng_fast.0 comp-sys-catman .cat
./usr/share/man/cat9/cprng_fast32.0 comp-sys-catman .cat
./usr/share/man/cat9/cprng_fast64.0 comp-sys-catman .cat
./usr/share/man/cat9/cpu_configure.0 comp-sys-catman .cat
./usr/share/man/cat9/cpu_coredump.0 comp-sys-catman .cat
./usr/share/man/cat9/cpu_dump.0 comp-sys-catman .cat
@ -15906,6 +15917,17 @@
./usr/share/man/html9/copyoutstr.html comp-sys-htmlman html
./usr/share/man/html9/copystr.html comp-sys-htmlman html
./usr/share/man/html9/coredump_write.html comp-sys-htmlman html
./usr/share/man/html9/cprng.html comp-sys-htmlman html
./usr/share/man/html9/cprng_strong.html comp-sys-htmlman html
./usr/share/man/html9/cprng_strong_create.html comp-sys-htmlman html
./usr/share/man/html9/cprng_strong_destroy.html comp-sys-htmlman html
./usr/share/man/html9/cprng_strong_getflags.html comp-sys-htmlman html
./usr/share/man/html9/cprng_strong_setflags.html comp-sys-htmlman html
./usr/share/man/html9/cprng_strong32.html comp-sys-htmlman html
./usr/share/man/html9/cprng_strong64.html comp-sys-htmlman html
./usr/share/man/html9/cprng_fast.html comp-sys-htmlman html
./usr/share/man/html9/cprng_fast32.html comp-sys-htmlman html
./usr/share/man/html9/cprng_fast64.html comp-sys-htmlman html
./usr/share/man/html9/cpu_configure.html comp-sys-htmlman html
./usr/share/man/html9/cpu_coredump.html comp-sys-htmlman html
./usr/share/man/html9/cpu_dump.html comp-sys-htmlman html
@ -22152,6 +22174,17 @@
./usr/share/man/man9/copyoutstr.9 comp-sys-man .man
./usr/share/man/man9/copystr.9 comp-sys-man .man
./usr/share/man/man9/coredump_write.9 comp-sys-man .man
./usr/share/man/man9/cprng.9 comp-sys-man .man
./usr/share/man/man9/cprng_strong.9 comp-sys-man .man
./usr/share/man/man9/cprng_strong_create.9 comp-sys-man .man
./usr/share/man/man9/cprng_strong_destroy.9 comp-sys-man .man
./usr/share/man/man9/cprng_strong_getflags.9 comp-sys-man .man
./usr/share/man/man9/cprng_strong_setflags.9 comp-sys-man .man
./usr/share/man/man9/cprng_strong32.9 comp-sys-man .man
./usr/share/man/man9/cprng_strong64.9 comp-sys-man .man
./usr/share/man/man9/cprng_fast.9 comp-sys-man .man
./usr/share/man/man9/cprng_fast32.9 comp-sys-man .man
./usr/share/man/man9/cprng_fast64.9 comp-sys-man .man
./usr/share/man/man9/cpu_configure.9 comp-sys-man .man
./usr/share/man/man9/cpu_coredump.9 comp-sys-man .man
./usr/share/man/man9/cpu_dump.9 comp-sys-man .man

17
share/man/man9/Makefile
View File

@ -1,9 +1,9 @@
# $NetBSD: Makefile,v 1.359 2011/11/15 00:50:55 jym Exp $
# $NetBSD: Makefile,v 1.360 2011/11/28 20:19:28 tls Exp $
# Makefile for section 9 (kernel function and variable) manual pages.
MAN= accept_filter.9 accf_data.9 accf_http.9 \
altq.9 arc4random.9 arp.9 audio.9 autoconf.9 \
altq.9 arp.9 audio.9 autoconf.9 \
bcdtobin.9 bcmp.9 bcopy.9 bintime_add.9 bluetooth.9 boothowto.9 bpf.9 \
buffercache.9 bufq.9 bus_dma.9 bus_space.9 byteorder.9 bzero.9 \
callback.9 callout.9 cardbus.9 cnmagic.9 condvar.9 config.9 \
@ -63,6 +63,19 @@ MAN= accept_filter.9 accf_data.9 accf_http.9 \
MAN+= boothowto.9
MLINKS+=boothowto.9 BOOT_FLAG.9
MAN+= cprng.9
MLINKS+=cprng.9 cprng_strong.9 \
cprng.9 cprng_strong_create.9 \
cprng.9 cprng_strong_destroy.9 \
cprng.9 cprng_strong_getflags.9 \
cprng.9 cprng_strong_setflags.9 \
cprng.9 cprng_strong32.9 \
cprng.9 cprng_strong64.9 \
cprng.9 cprng_fast.9 \
cprng.9 cprng_fast32.9 \
cprng.9 cprng_fast64.9 \
cprng.9 arc4random.9
MAN+= deviter.9
MLINKS+=deviter.9 deviter_first.9 \
deviter.9 deviter_init.9 \

87
share/man/man9/arc4random.9
View File

@ -1,87 +0,0 @@
.\" $NetBSD: arc4random.9,v 1.3 2005/12/26 19:48:12 perry Exp $
.\" $OpenBSD: arc4random.3,v 1.17 2000/12/21 14:07:41 aaron Exp $
.\"
.\" Copyright 1997 Niels Provos <provos@physnet.uni-hamburg.de>
.\" All rights reserved.
.\"
.\" 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.
.\" 3. All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\" This product includes software developed by Niels Provos.
.\" 4. The name of the author may not be used to endorse or promote products
.\" derived from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 AUTHOR 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.
.\"
.\" Manual page, using -mandoc macros
.\"
.Dd April 15, 1997
.Dt ARC4RANDOM 9
.Os
.Sh NAME
.Nm arc4random
.Nd arc4 random number generator
.Sh SYNOPSIS
.In sys/types.h
.In sys/systm.h
.Ft uint32_t
.Fn arc4random "void"
.Sh DESCRIPTION
The
.Fn arc4random
function provides a high quality 32-bit pseudo-random
number very quickly.
.Fn arc4random
seeds itself on a regular basis from the kernel strong random number
subsystem described in
.Xr rnd 4 .
On each call, an ARC4 generator is used to generate a new result.
The
.Fn arc4random
function uses the ARC4 cipher key stream generator,
which uses 8*8 8 bit S-Boxes.
The S-Boxes can be in about (2**1700) states.
.Pp
.Fn arc4random
fits into a middle ground not covered by other subsystems such as
the strong, slow, and resource expensive random
devices described in
.Xr rnd 4
versus the fast but poor quality interfaces such as
.Fn random .
.Sh SEE ALSO
.Xr arc4random 3 ,
.Xr rnd 4
.Sh HISTORY
An algorithm called
.Pa RC4
was designed by RSA Data Security, Inc.
It was considered a trade secret, but not trademarked.
Because it was a trade secret, it obviously could not be patented.
A clone of this was posted anonymously to USENET and confirmed to
be equivalent by several sources who had access to the original cipher.
Because of the trade secret situation, RSA Data Security, Inc. can do
nothing about the release of the ARC4 algorithm.
Since
.Pa RC4
used to be a trade secret, the cipher is now referred to as
.Pa ARC4 .
.Pp
These functions first appeared in
.Ox 2.1 .

251
share/man/man9/cprng.9 Normal file
View File

@ -0,0 +1,251 @@
.\" $NetBSD: cprng.9,v 1.1 2011/11/28 20:19:28 tls 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 November 28, 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_destroy ,
.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 *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"
.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;
NIST_CTR_DRBG drbg;
int flags;
char name[16];
int reseed_pending;
rndsink_t reseed;
} cprng_strong_t;
.Ed
.Pp
.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 cryptosystems 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
entrpy 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.
.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"
.Pp
Fill memory location
.Fa buf
with
.Fa len
bytes from the generator
.Fa cprng .
If less than
.Fa len
bytes are returned, the generator 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 spl 9 ,
.Xr rnd 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 .

5
share/man/man9/rnd.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: rnd.9,v 1.17 2008/09/16 23:29:49 jmcneill Exp $
.\" $NetBSD: rnd.9,v 1.18 2011/11/28 20:19:28 tls Exp $
.\"
.\" Copyright (c) 1997 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -173,7 +173,8 @@ These functions are declared in src/sys/sys/rnd.h and defined in
src/sys/dev/rnd.c.
.Sh SEE ALSO
.Xr rnd 4 ,
.Xr rndctl 8
.Xr rndctl 8 ,
.Xr cprng 9
.Sh HISTORY
The random device was introduced in
.Nx 1.3 .