Annotation of src/lib/libc/gen/arc4random.3, Revision 1.20
1.20 ! riastrad 1: .\" $NetBSD: arc4random.3,v 1.19 2014/11/17 18:41:29 riastradh Exp $
1.1 itojun 2: .\"
1.10 riastrad 3: .\" Copyright (c) 2014 The NetBSD Foundation, Inc.
1.1 itojun 4: .\" All rights reserved.
5: .\"
1.10 riastrad 6: .\" This code is derived from software contributed to The NetBSD Foundation
7: .\" by Taylor R. Campbell.
8: .\"
1.1 itojun 9: .\" Redistribution and use in source and binary forms, with or without
10: .\" modification, are permitted provided that the following conditions
11: .\" are met:
12: .\" 1. Redistributions of source code must retain the above copyright
13: .\" notice, this list of conditions and the following disclaimer.
14: .\" 2. Redistributions in binary form must reproduce the above copyright
15: .\" notice, this list of conditions and the following disclaimer in the
16: .\" documentation and/or other materials provided with the distribution.
17: .\"
1.10 riastrad 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
20: .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21: .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22: .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23: .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
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
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
28: .\" POSSIBILITY OF SUCH DAMAGE.
1.1 itojun 29: .\"
1.10 riastrad 30: .Dd November 16, 2014
1.1 itojun 31: .Dt ARC4RANDOM 3
32: .Os
33: .Sh NAME
34: .Nm arc4random ,
1.10 riastrad 35: .Nm arc4random_uniform ,
1.8 christos 36: .Nm arc4random_buf ,
1.1 itojun 37: .Nm arc4random_stir ,
38: .Nm arc4random_addrandom
1.10 riastrad 39: .Nd random number generator
1.5 itojun 40: .Sh LIBRARY
41: .Lb libc
1.1 itojun 42: .Sh SYNOPSIS
1.6 wiz 43: .In stdlib.h
1.7 perry 44: .Ft uint32_t
1.1 itojun 45: .Fn arc4random "void"
1.10 riastrad 46: .Ft uint32_t
47: .Fn arc4random_uniform "uint32_t bound"
1.1 itojun 48: .Ft void
1.10 riastrad 49: .Fn arc4random_buf "void *buf" "size_t len"
1.8 christos 50: .Ft void
1.1 itojun 51: .Fn arc4random_stir "void"
52: .Ft void
1.10 riastrad 53: .Fn arc4random_addrandom "unsigned char *buf" "int len"
1.1 itojun 54: .Sh DESCRIPTION
55: The
1.10 riastrad 56: .Nm
57: family of functions provides a cryptographic pseudorandom number
58: generator automatically seeded from the system entropy pool and safe to
59: use from multiple threads.
60: .Nm
1.12 riastrad 61: is designed to prevent an adversary from guessing outputs,
62: unlike
63: .Xr rand 3
64: and
65: .Xr random 3 ,
66: and is faster and more convenient than reading from
1.10 riastrad 67: .Pa /dev/urandom
68: directly.
69: .Pp
1.1 itojun 70: .Fn arc4random
1.10 riastrad 71: returns an integer in [0, 2^32) chosen independently with uniform
72: distribution.
73: .Pp
74: .Fn arc4random_uniform
75: returns an integer in [0,
76: .Fa bound )
77: chosen independently with uniform distribution.
78: .Pp
79: .Fn arc4random_buf
80: stores
81: .Fa len
82: bytes into the memory pointed to by
83: .Fa buf ,
84: each byte chosen independently from [0, 256) with uniform
85: distribution.
86: .Pp
87: .Fn arc4random_stir
88: draws entropy from the operating system and incorporates it into the
89: library's PRNG state to influence future outputs.
90: .Pp
91: .Fn arc4random_addrandom
92: incorporates
93: .Fa len
94: bytes, which must be nonnegative, from the buffer
95: .Fa buf ,
96: into the library's PRNG state to influence future outputs.
97: .Pp
98: It is not necessary for an application to call
99: .Fn arc4random_stir
100: or
101: .Fn arc4random_addrandom
102: before calling other
103: .Nm
104: functions.
105: The first call to any
106: .Nm
107: function will initialize the PRNG state unpredictably from the system
108: entropy pool.
109: .Sh SECURITY MODEL
110: The
111: .Nm
1.11 wiz 112: functions provide the following security properties against three
1.19 riastrad 113: different classes of attackers, assuming enough entropy is provided by
114: the operating system:
1.20 ! riastrad 115: .Bl -enum -offset abcd
1.10 riastrad 116: .It
117: An attacker who has seen some outputs of any of the
118: .Nm
119: functions cannot predict past or future unseen outputs.
120: .It
121: An attacker who has seen the library's PRNG state in memory cannot
122: predict past outputs.
123: .It
124: An attacker who has seen one process's PRNG state cannot predict past
125: or future outputs in other processes, particularly its parent or
126: siblings.
127: .El
1.19 riastrad 128: .Pp
129: One
130: .Sq output
131: means the result of any single request to an
132: .Nm
133: function, no matter how short it is.
1.20 ! riastrad 134: .Pp
! 135: The second property is sometimes called
! 136: .Sq forward secrecy ,
! 137: .Sq backtracking resistance ,
! 138: or
! 139: .Sq key erasure after each output .
1.10 riastrad 140: .Sh IMPLEMENTATION NOTES
1.1 itojun 141: The
1.10 riastrad 142: .Nm
143: functions are currently implemented using the ChaCha20 pseudorandom
144: function family.
145: For any 32-byte string
146: .Fa s ,
147: .Pf ChaCha20_ Fa s
148: is a function from 16-byte strings to 64-byte strings.
149: It is conjectured that if
150: .Fa s
151: is chosen with uniform distribution, then the distribution on
152: .Pf ChaCha20_ Fa s
153: is indistinguishable to a computationally bounded adversary from a
154: uniform distribution on all functions from 16-byte strings to 64-byte
155: strings.
1.1 itojun 156: .Pp
1.10 riastrad 157: The PRNG state is a 32-byte ChaCha20 key
158: .Fa s .
159: Each request to
160: an
161: .Nm
162: function
163: .Bl -bullet -offset abcd -compact
164: .It
165: computes the 64-byte quantity
166: .Fa x
167: =
168: .Pf ChaCha20_ Fa s Ns (0),
169: .It
170: splits
171: .Fa x
172: into two 32-byte quantities
173: .Fa s'
174: and
175: .Fa k ,
176: .It
177: replaces
178: .Fa s
179: by
180: .Fa s' ,
1.1 itojun 181: and
1.10 riastrad 182: .It
183: uses
184: .Fa k
185: as output.
186: .El
1.1 itojun 187: .Pp
1.10 riastrad 188: .Fn arc4random
189: yields the first four bytes of
190: .Fa k
191: as output directly.
1.9 wiz 192: .Fn arc4random_buf
1.10 riastrad 193: either yields up to 32 bytes of
194: .Fa k
195: as output directly, or, for longer
196: requests, uses
197: .Fa k
198: as a ChaCha20 key and yields the concatenation
199: .Pf ChaCha20_ Fa k Ns (0)
200: ||
201: .Pf ChaCha20_ Fa k Ns (1)
202: || ... as output.
1.8 christos 203: .Fn arc4random_uniform
1.10 riastrad 204: repeats
205: .Fn arc4random
206: until it obtains an integer in [2^32 %
207: .Fa bound ,
208: 2^32), and reduces that modulo
209: .Fa bound .
1.8 christos 210: .Pp
1.10 riastrad 211: The PRNG state is per-thread, unless memory allocation fails inside the
212: library, in which case some threads may share global PRNG state with a
213: mutex.
214: The global PRNG state is zeroed on fork in the parent via
215: .Xr pthread_atfork 3 ,
216: and the per-thread PRNG state is zeroed on fork in the child via
217: .Xr minherit 2
218: with
219: .Dv MAP_INHERIT_ZERO ,
220: so that the child cannot reuse or see the parent's PRNG state.
221: The PRNG state is reseeded automatically from the system entropy pool
222: on the first use of an
223: .Nm
224: function after zeroing.
1.1 itojun 225: .Pp
1.10 riastrad 226: The first use of an
227: .Nm
228: function may abort the process in the highly unlikely event that
229: library initialization necessary to implement the security model fails.
230: Additionally,
1.1 itojun 231: .Fn arc4random_stir
1.10 riastrad 232: and
233: .Fn arc4random_addrandom
234: may abort the process in the highly unlikely event that the operating
235: system fails to provide entropy.
1.1 itojun 236: .Sh SEE ALSO
237: .Xr rand 3 ,
1.10 riastrad 238: .Xr random 3 ,
1.16 riastrad 239: .Xr rnd 4 ,
1.10 riastrad 240: .Xr cprng 9
241: .Rs
242: .%A Daniel J. Bernstein
243: .%T ChaCha, a variant of Salsa20
244: .%D 2008-01-28
245: .%O Document ID: 4027b5256e17b9796842e6d0f68b0b5e
246: .%U http://cr.yp.to/papers.html#chacha
247: .Re
248: .Sh BUGS
249: There is no way to get deterministic, reproducible results out of
250: .Nm
251: for testing purposes.
252: .Pp
253: The name
254: .Sq arc4random
1.14 riastrad 255: was chosen for hysterical raisins -- it was originally implemented
256: using the RC4 stream cipher, which has been known since shortly after
257: it was published in 1994 to have observable biases in the output, and
258: is now known to be broken badly enough to admit practical attacks in
259: the real world.
260: .\" Bob Jenkins, sci.crypt post dated 1994-09-16, message-id
261: .\" <359qjg$55v$1@mhadg.production.compuserve.com>,
1.18 riastrad 262: .\" https://groups.google.com/d/msg/sci.crypt/JsO3xEATGFA/-wO4ttv7BCYJ
1.14 riastrad 263: .\"
264: .\" Andrew Roos, `A Class of Weak Keys in the RC4 Stream Cipher',
265: .\" sci.crypt posts dated 1995-09-22, message-ids
1.18 riastrad 266: .\" <43u1eh$1j3@hermes.is.co.za> and <44ebge$llf@hermes.is.co.za>.
1.14 riastrad 267: .\"
268: .\" Paul Crowley, `Small bias in RC4 experimentally verified', March
269: .\" 1998, http://www.ciphergoth.org/crypto/rc4/
270: Unfortunately, the library found widespread adoption and the name stuck
271: before anyone recognized that it was silly.
1.1 itojun 272: .Pp
1.10 riastrad 273: The signature of
274: .Fn arc4random_addrandom
275: is silly.
276: There is no reason to require casts or accept negative lengths:
277: it should take a
278: .Vt void *
279: buffer and a
280: .Vt size_t
281: length.
282: But it's too late to change that now.
283: .Pp
284: .Fn arc4random_uniform
1.15 riastrad 285: does not help to choose integers in [0,
1.17 wiz 286: .Fa n )
1.15 riastrad 287: uniformly at random when
288: .Fa n
289: > 2^32.
1.13 riastrad 290: .Pp
291: The security model of
292: .Nm
293: is stronger than many applications need, and stronger than other
294: operating systems provide.
295: For example, applications encrypting messages with random, but not
296: secret, initialization vectors need only prevent an adversary from
297: guessing future outputs, since past outputs will have been published
298: already.
299: .Pp
300: On the one hand,
301: .Nm
302: could be marginally faster if it were not necessary to prevent an
303: adversary who sees the state from predicting past outputs.
304: On the other hand, there are applications in the wild that use
305: .Nm
306: to generate key material, such as OpenSSH, so for the sake of
307: .Nx
308: users it would be imprudent to weaken the security model.
309: On the third hand, relying on the security model of
310: .Nm
311: in
312: .Nx
313: may lead you to an unpleasant surprise on another operating system
314: whose implementation of
315: .Nm
316: has a weaker security model.
317: .Pp
318: One may be tempted to create new APIs to accommodate different
319: security models and performance constraints without unpleasant
320: surprises on different operating systems.
321: This should not be done lightly, though, because there are already too
322: many different choices, and too many opportunities for programmers to
1.19 riastrad 323: reach for one and pick the wrong one.
CVSweb <webmaster@jp.NetBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to arc4random.3 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / src / lib / libc / gen