Module Name: src
Committed By: tls
Date: Mon Nov 28 20:19:28 UTC 2011
Modified Files:
src/distrib/sets/lists/comp: mi
src/share/man/man9: Makefile rnd.9
Added Files:
src/share/man/man9: cprng.9
Removed Files:
src/share/man/man9: arc4random.9
Log Message:
Add cprng(9) manual page, remove arc4random(9) manual page
To generate a diff of this commit:
cvs rdiff -u -r1.1713 -r1.1714 src/distrib/sets/lists/comp/mi
cvs rdiff -u -r1.359 -r1.360 src/share/man/man9/Makefile
cvs rdiff -u -r1.3 -r0 src/share/man/man9/arc4random.9
cvs rdiff -u -r0 -r1.1 src/share/man/man9/cprng.9
cvs rdiff -u -r1.17 -r1.18 src/share/man/man9/rnd.9
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/distrib/sets/lists/comp/mi
diff -u src/distrib/sets/lists/comp/mi:1.1713 src/distrib/sets/lists/comp/mi:1.1714
--- src/distrib/sets/lists/comp/mi:1.1713 Mon Nov 28 16:22:15 2011
+++ src/distrib/sets/lists/comp/mi Mon Nov 28 20:19:25 2011
@@ -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
Index: src/share/man/man9/Makefile
diff -u src/share/man/man9/Makefile:1.359 src/share/man/man9/Makefile:1.360
--- src/share/man/man9/Makefile:1.359 Tue Nov 15 00:50:55 2011
+++ src/share/man/man9/Makefile Mon Nov 28 20:19:28 2011
@@ -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_ht
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 \
Index: src/share/man/man9/rnd.9
diff -u src/share/man/man9/rnd.9:1.17 src/share/man/man9/rnd.9:1.18
--- src/share/man/man9/rnd.9:1.17 Tue Sep 16 23:29:49 2008
+++ src/share/man/man9/rnd.9 Mon Nov 28 20:19:28 2011
@@ -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/
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 .
Added files:
Index: src/share/man/man9/cprng.9
diff -u /dev/null src/share/man/man9/cprng.9:1.1
--- /dev/null Mon Nov 28 20:19:28 2011
+++ src/share/man/man9/cprng.9 Mon Nov 28 20:19:28 2011
@@ -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 .
