Wed Mar 18 08:03:27 2015 UTC ()
Pull up following revision(s) (requested by riastradh in ticket #605):
	share/man/man9/cprng.9: revision 1.10
Clarify advice about when to use what parts of cprng(9).
Add security model to specify the difference between cprng_strong and
cprng_fast.
Fix code references.  cprng_fast now uses ChaCha8, not RC4.
XXX Would have been nice if they had been called cprng and cprng_weak
to reduce confusion about which one to use, or even random and
weakrandom.  Too late for that now, though.


(snj)
diff -r1.9 -r1.9.4.1 src/share/man/man9/cprng.9
cvs diff -r1.9 -r1.9.4.1 src/share/man/man9/cprng.9 (expand / switch to unified diff)

--- src/share/man/man9/cprng.9 2014/03/18 18:20:40 1.9
+++ src/share/man/man9/cprng.9 2015/03/18 08:03:27 1.9.4.1
@@ -1,43 +1,43 @@ @@ -1,43 +1,43 @@
1.\" $NetBSD: cprng.9,v 1.9 2014/03/18 18:20:40 riastradh Exp $ 1.\" $NetBSD: cprng.9,v 1.9.4.1 2015/03/18 08:03:27 snj Exp $
2.\" 2.\"
3.\" Copyright (c) 2011-2013 The NetBSD Foundation, Inc. 3.\" Copyright (c) 2011-2015 The NetBSD Foundation, Inc.
4.\" All rights reserved. 4.\" All rights reserved.
5.\" 5.\"
6.\" This code is derived from software contributed to The NetBSD Foundation 6.\" This code is derived from software contributed to The NetBSD Foundation
7.\" by Thor Lancelot Simon and Taylor R. Campbell. 7.\" by Thor Lancelot Simon and Taylor R. Campbell.
8.\" 8.\"
9.\" Redistribution and use in source and binary forms, with or without 9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions 10.\" modification, are permitted provided that the following conditions
11.\" are met: 11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright 12.\" 1. Redistributions of source code must retain the above copyright
13.\" notice, this list of conditions and the following disclaimer. 13.\" notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\" notice, this list of conditions and the following disclaimer in the 15.\" notice, this list of conditions and the following disclaimer in the
16.\" documentation and/or other materials provided with the distribution. 16.\" documentation and/or other materials provided with the distribution.
17.\" 17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28.\" POSSIBILITY OF SUCH DAMAGE. 28.\" POSSIBILITY OF SUCH DAMAGE.
29.\" 29.\"
30.Dd July 18, 2013 30.Dd February 19, 2015
31.Dt CPRNG 9 31.Dt CPRNG 9
32.Os 32.Os
33.Sh NAME 33.Sh NAME
34.Nm cprng , 34.Nm cprng ,
35.Nm cprng_strong_create , 35.Nm cprng_strong_create ,
36.Nm cprng_strong_destroy , 36.Nm cprng_strong_destroy ,
37.Nm cprng_strong , 37.Nm cprng_strong ,
38.Nm cprng_strong32 , 38.Nm cprng_strong32 ,
39.Nm cprng_strong64 , 39.Nm cprng_strong64 ,
40.Nm cprng_fast , 40.Nm cprng_fast ,
41.Nm cprng_fast32 , 41.Nm cprng_fast32 ,
42.Nm cprng_fast64 , 42.Nm cprng_fast64 ,
43.Nd cryptographic pseudorandom number generators 43.Nd cryptographic pseudorandom number generators
@@ -57,74 +57,77 @@ @@ -57,74 +57,77 @@
57.Fn cprng_fast "void *buf" "size_t len" 57.Fn cprng_fast "void *buf" "size_t len"
58.Ft uint32_t 58.Ft uint32_t
59.Fn cprng_fast32 "void" 59.Fn cprng_fast32 "void"
60.Ft uint32_t 60.Ft uint32_t
61.Fn cprng_fast64 "void" 61.Fn cprng_fast64 "void"
62.Bd -literal 62.Bd -literal
63#define CPRNG_MAX_LEN 524288 63#define CPRNG_MAX_LEN 524288
64.Ed 64.Ed
65.Sh DESCRIPTION 65.Sh DESCRIPTION
66The 66The
67.Nm 67.Nm
68family of functions provide cryptographic pseudorandom number 68family of functions provide cryptographic pseudorandom number
69generators automatically seeded from the kernel entropy pool. 69generators automatically seeded from the kernel entropy pool.
70They replace the 70All applications in the kernel requiring random data or random choices
71.Xr arc4random 9 71should use the
72and 72.Nm cprng_strong
73.Xr rnd_extract_data 9 73family of functions, unless performance constraints demand otherwise.
74functions for this purpose. 
75The 
76.Nx 
77kernel no longer supports direct reading from the kernel entropy pool; all 
78access is mediated by the 
79.Nm 
80functions. 
81.Pp 74.Pp
82The 75The
83.Dq strong 76.Nm cprng_fast
84family of functions use cryptographically strong pseudorandom number 77family of functions may be used in applications that can tolerate
85generators suitable for keying crypto systems and similar purposes. 78exposure of past random data, such as initialization vectors or
86Calls to 79transaction ids that are sent over the internet anyway, if the
87.Xr rnd_extract_data 9 80applications require higher throughput or lower per-request latency
88should be replaced by calls to 81than the
89.Fn cprng_strong . 82.Nm cprng_strong
90.Pp 83family of functions provide.
91The 84If in doubt, choose
92.Dq fast 85.Nm cprng_strong .
93family of functions use cryptographically weaker pseudorandom number 
94generators suitable for initialization vectors, nonces in certain 
95protocols, and other similar purposes, using a faster but less secure 
96stream-cipher-based generator. 
97Calls to 
98.Xr arc4random 9 
99should be replaced by calls to 
100.Fn cprng_fast32 , 
101and calls to 
102.Xr arc4randbytes 9 
103should be replaced by calls to 
104.Fn cprng_fast . 
105.Pp 86.Pp
106A single instance of the fast generator serves the entire kernel. 87A single instance of the fast generator serves the entire kernel.
107A well-known instance of the strong generator, 88A well-known instance of the strong generator,
108.Dv kern_cprng , 89.Dv kern_cprng ,
109may be used by any in-kernel caller, but separately seeded instances of 90may be used by any in-kernel caller, but separately seeded instances of
110the strong generator can also be created by calling 91the strong generator can also be created by calling
111.Fn cprng_strong_create . 92.Fn cprng_strong_create .
 93.Pp
 94The
 95.Nm
 96functions may be used at interrupt priority level
 97.Dv IPL_VM
 98or below,
 99except for
 100.Fn cprng_strong_create
 101and
 102.Fn cprng_strong_destroy
 103which are allowed only at
 104.Dv IPL_NONE ;
 105see
 106.Xr spl 9 .
 107.Pp
 108The
 109.Nm
 110functions replace the legacy
 111.Xr arc4random 9
 112and
 113.Xr rnd_extract_data 9
 114functions.
112.Sh FUNCTIONS 115.Sh FUNCTIONS
113.Bl -tag -width abcd 116.Bl -tag -width abcd
114.It Fn cprng_strong_create "name" "ipl" "flags" 117.It Fn cprng_strong_create "name" "ipl" "flags"
115Create an instance of the cprng_strong generator. 118Create an instance of the cprng_strong generator.
116This generator implements the NIST SP 800-90 CTR_DRBG with AES128 as 119This generator currently implements the NIST SP 800-90A CTR_DRBG with
117the block transform. 120AES-128 as the block transform.
118.Pp 121.Pp
119The 122The
120.Fa name 123.Fa name
121argument is used to 124argument is used to
122.Dq personalize 125.Dq personalize
123the CTR_DRBG according to the standard, so that its initial state will 126the CTR_DRBG according to the standard, so that its initial state will
124depend both on seed material from the entropy pool and also on the 127depend both on seed material from the entropy pool and also on the
125personalization string (name). 128personalization string (name).
126.Pp 129.Pp
127The 130The
128.Fa ipl 131.Fa ipl
129argument specifies the interrupt priority level for the mutex which 132argument specifies the interrupt priority level for the mutex which
130will serialize access to the new instance of the generator (see 133will serialize access to the new instance of the generator (see
@@ -247,41 +250,78 @@ bytes from the fast generator. @@ -247,41 +250,78 @@ bytes from the fast generator.
247.Fn cprng_fast 250.Fn cprng_fast
248does not sleep. 251does not sleep.
249.It Fn cprng_fast32 252.It Fn cprng_fast32
250Generate 32 bits using the fast generator. 253Generate 32 bits using the fast generator.
251.Pp 254.Pp
252.Fn cprng_fast32 255.Fn cprng_fast32
253does not sleep. 256does not sleep.
254.It Fn cprng_fast64 257.It Fn cprng_fast64
255Generate 64 bits using the fast generator. 258Generate 64 bits using the fast generator.
256.Pp 259.Pp
257.Fn cprng_fast64 260.Fn cprng_fast64
258does not sleep. 261does not sleep.
259.El 262.El
 263.Sh SECURITY MODEL
 264The
 265.Nm
 266family of functions provide the following security properties:
 267.Bl -bullet -offset abcd
 268.It
 269An attacker who has seen some outputs of any of the
 270.Nm
 271functions cannot predict past or future unseen outputs.
 272.It
 273An attacker who has compromised kernel memory cannot predict past
 274outputs of the
 275.Nm cprng_strong
 276functions.
 277However, such an attacker may be able to predict past outputs of the
 278.Nm cprng_fast
 279functions.
 280.El
 281.Pp
 282The second property is sometimes called
 283.Dq backtracking resistance ,
 284.Dq forward secrecy ,
 285or
 286.Dq key erasure
 287in the cryptography literature.
 288The
 289.Nm cprng_strong
 290functions provide backtracking resistance;
 291the
 292.Nm cprng_fast
 293functions do not.
260.Sh CODE REFERENCES 294.Sh CODE REFERENCES
261The cprng API is implemented by 
262.Pa sys/kern/subr_cprng.c 
263and 
264.Pa sys/sys/cprng.h . 
265The 295The
266.Dq strong 296.Nm cprng_strong
267generator uses the CTR_DRBG implementation in 297functions are implemented in
 298.Pa sys/kern/subr_cprng.c ,
 299and use the NIST SP 800-90A CTR_DRBG implementation in
268.Pa sys/crypto/nist_ctr_drbg . 300.Pa sys/crypto/nist_ctr_drbg .
269The 301The
270.Dq fast 302.Nm cprng_fast
271generator uses the arc4random implementation in 303functions are implemented in
272.Pa sys/lib/libkern/arc4random.c . 304.Pa sys/crypto/cprng_fast/cprng_fast.c ,
 305and use the ChaCha8 stream cipher.
273.Sh SEE ALSO 306.Sh SEE ALSO
274.Xr condvar 9 , 307.Xr condvar 9 ,
275.Xr rnd 9 , 308.Xr rnd 9 ,
276.Xr spl 9 309.Xr spl 9
277.Rs 310.Rs
278.%A Elaine Barker 311.%A Elaine Barker
279.%A John Kelsey 312.%A John Kelsey
280.%T Recommendation for Random Number Generation Using Deterministic Random Bit Generators (Revised) 313.%T Recommendation for Random Number Generation Using Deterministic Random Bit Generators (Revised)
281.%I National Institute of Standards and Technology 314.%I National Institute of Standards and Technology
282.%D 2011 315.%D 2011
283.%O NIST Special Publication 800-90A, Rev 1 316.%O NIST Special Publication 800-90A, Rev 1
284.Re 317.Re
 318.Rs
 319.%A Daniel J. Bernstein
 320.%T ChaCha, a variant of Salsa20
 321.%D 2008-01-28
 322.%O Document ID: 4027b5256e17b9796842e6d0f68b0b5e
 323.%U http://cr.yp.to/papers.html#chacha
 324.Re
285.Sh HISTORY 325.Sh HISTORY
286The cprng family of functions first appeared in 326The cprng family of functions first appeared in
287.Nx 6.0 . 327.Nx 6.0 .