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