From 4c6da577a11bc6857a4dba3a9ce2f6894af1e604 Mon Sep 17 00:00:00 2001 From: Guillem Jover Date: Wed, 29 Mar 2023 02:28:52 +0200 Subject: [PATCH] man: Switch arc4random(3bsd) man page from OpenBSD to NetBSD This gets rid of the last BSD-4-clause licensed file in the project. The man page will probably need to be adapted to the current implementation, but that can be done piecemeal afterwards. Closes: #7 --- COPYING | 38 +---- man/arc4random.3bsd | 382 ++++++++++++++++++++++++++++++++------------ 2 files changed, 286 insertions(+), 134 deletions(-) diff --git a/COPYING b/COPYING index 4384bd2..a3b2cd9 100644 --- a/COPYING +++ b/COPYING @@ -6,37 +6,6 @@ Copyright: Copyright © 2004-2006, 2008-2022 Guillem Jover License: BSD-3-clause -Files: - man/arc4random.3bsd -Copyright: - Copyright 1997 Niels Provos - All rights reserved. -License: BSD-4-clause-Niels-Provos - 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. - Files: include/bsd/err.h include/bsd/stdlib.h @@ -202,6 +171,7 @@ License: BSD-5-clause-Peter-Wemm Files: include/bsd/stringlist.h + man/arc4random.3bsd man/fmtcheck.3bsd man/humanize_number.3bsd man/stringlist.3bsd @@ -216,6 +186,12 @@ Copyright: Copyright © 2013 John-Mark Gurney All rights reserved. . + Copyright © 2014 The NetBSD Foundation, Inc. + All rights reserved. + . + Some code was derived from software contributed to The NetBSD Foundation + by Taylor R. Campbell. + . Some code was contributed to The NetBSD Foundation by Allen Briggs. . Some code was contributed to The NetBSD Foundation by Luke Mewburn. diff --git a/man/arc4random.3bsd b/man/arc4random.3bsd index f1dc254..9b11aa9 100644 --- a/man/arc4random.3bsd +++ b/man/arc4random.3bsd @@ -1,8 +1,11 @@ -.\" $OpenBSD: arc4random.3,v 1.37 2019/09/29 16:30:35 jmc Exp $ +.\" $NetBSD: arc4random.3,v 1.21 2016/07/15 21:19:19 wiz Exp $ .\" -.\" Copyright 1997 Niels Provos +.\" Copyright (c) 2014 The NetBSD Foundation, Inc. .\" All rights reserved. .\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Taylor R. Campbell. +.\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: @@ -11,32 +14,26 @@ .\" 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. +.\" 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. .\" -.\" Manual page, using -mandoc macros -.\" -.Dd $Mdocdate: September 29 2019 $ +.Dd November 16, 2014 .Dt arc4random 3bsd .Os .Sh NAME .Nm arc4random , -.Nm arc4random_buf , .Nm arc4random_uniform , +.Nm arc4random_buf , .Nm arc4random_stir , .Nm arc4random_addrandom .Nd random number generator @@ -51,102 +48,281 @@ for include usage.) .Ft uint32_t .Fn arc4random "void" -.Ft void -.Fn arc4random_buf "void *buf" "size_t nbytes" .Ft uint32_t -.Fn arc4random_uniform "uint32_t upper_bound" +.Fn arc4random_uniform "uint32_t bound" +.Ft void +.Fn arc4random_buf "void *buf" "size_t len" .Ft void .Fn arc4random_stir "void" .Ft void -.Fn arc4random_addrandom "unsigned char *dat" "int datlen" +.Fn arc4random_addrandom "unsigned char *buf" "int len" .Sh DESCRIPTION -This family of functions provides higher quality data than those -described in -.Xr rand 3 , +The +.Nm +family of functions provides a cryptographic pseudorandom number +generator automatically seeded from the system entropy pool and safe to +use from multiple threads. +.Nm +is designed to prevent an adversary from guessing outputs, +unlike +.Xr rand 3 +and .Xr random 3 , -and -.Xr rand48 3 . +and is faster and more convenient than reading from +.Pa /dev/urandom +directly. .Pp -Use of these functions is encouraged for almost all random number -consumption because the other interfaces are deficient in either -quality, portability, standardization, or availability. -These functions can be called in almost all coding environments, -including -.Xr pthreads 3 -and -.Xr chroot 2 . -.Pp -High quality 32-bit pseudo-random numbers are generated very quickly. -On each call, a cryptographic pseudo-random number generator is used -to generate a new result. -One data pool is used for all consumers in a process, so that consumption -under program flow can act as additional stirring. -The subsystem is re-seeded from the kernel random number subsystem using -.Xr getentropy 2 -on a regular basis, and also upon -.Xr fork 2 . -.Pp -The .Fn arc4random -function returns a single 32-bit value. -.Pp -The -.Fn arc4random_buf -function fills the region -.Fa buf -of length -.Fa nbytes -with random data. +returns an integer in [0, 2^32) chosen independently with uniform +distribution. .Pp .Fn arc4random_uniform -will return a single 32-bit value, uniformly distributed but less than -.Fa upper_bound . -This is recommended over constructions like -.Dq Li arc4random() % upper_bound -as it avoids "modulo bias" when the upper bound is not a power of two. -In the worst case, this function may consume multiple iterations -to ensure uniformity; see the source code to understand the problem -and solution. +returns an integer in [0, +.Fa bound ) +chosen independently with uniform distribution. .Pp +.Fn arc4random_buf +stores +.Fa len +bytes into the memory pointed to by +.Fa buf , +each byte chosen independently from [0, 256) with uniform +distribution. +.Pp +.Fn arc4random_stir +draws entropy from the operating system and incorporates it into the +library's PRNG state to influence future outputs. +.Pp +.Fn arc4random_addrandom +incorporates +.Fa len +bytes, which must be nonnegative, from the buffer +.Fa buf , +into the library's PRNG state to influence future outputs. +.Pp +It is not necessary for an application to call +.Fn arc4random_stir +or +.Fn arc4random_addrandom +before calling other +.Nm +functions. +The first call to any +.Nm +function will initialize the PRNG state unpredictably from the system +entropy pool. +.Sh SECURITY MODEL The -.Fn arc4random_stir -function reads data from -.Xr getentropy 2 -and uses it to re-seed the subsystem via -.Fn arc4random_addrandom . +.Nm +functions provide the following security properties against three +different classes of attackers, assuming enough entropy is provided by +the operating system: +.Bl -enum -offset abcd +.It +An attacker who has seen some outputs of any of the +.Nm +functions cannot predict past or future unseen outputs. +.It +An attacker who has seen the library's PRNG state in memory cannot +predict past outputs. +.It +An attacker who has seen one process's PRNG state cannot predict past +or future outputs in other processes, particularly its parent or +siblings. +.El +.Pp +One +.Sq output +means the result of any single request to an +.Nm +function, no matter how short it is. +.Pp +The second property is sometimes called +.Sq forward secrecy , +.Sq backtracking resistance , +or +.Sq key erasure after each output . +.Sh IMPLEMENTATION NOTES +The +.Nm +functions are currently implemented using the ChaCha20 pseudorandom +function family. +For any 32-byte string +.Fa s , +.Pf ChaCha20_ Fa s +is a function from 16-byte strings to 64-byte strings. +It is conjectured that if +.Fa s +is chosen with uniform distribution, then the distribution on +.Pf ChaCha20_ Fa s +is indistinguishable to a computationally bounded adversary from a +uniform distribution on all functions from 16-byte strings to 64-byte +strings. +.Pp +The PRNG state is a 32-byte ChaCha20 key +.Fa s . +Each request to +an +.Nm +function +.Bl -bullet -offset abcd -compact +.It +computes the 64-byte quantity +.Fa x += +.Pf ChaCha20_ Fa s Ns Pq 0 , +.It +splits +.Fa x +into two 32-byte quantities +.Fa s' +and +.Fa k , +.It +replaces +.Fa s +by +.Fa s' , +and +.It +uses +.Fa k +as output. +.El .Pp -There is no need to call -.Fn arc4random_stir -before using .Fn arc4random -functions family, since -they automatically initialize themselves. -.Sh RETURN VALUES -These functions are always successful, and no return value is -reserved to indicate an error. +yields the first four bytes of +.Fa k +as output directly. +.Fn arc4random_buf +either yields up to 32 bytes of +.Fa k +as output directly, or, for longer +requests, uses +.Fa k +as a ChaCha20 key and yields the concatenation +.Pf ChaCha20_ Fa k Ns Pq 0 +|| +.Pf ChaCha20_ Fa k Ns Pq 1 +|| ... as output. +.Fn arc4random_uniform +repeats +.Fn arc4random +until it obtains an integer in [2^32 % +.Fa bound , +2^32), and reduces that modulo +.Fa bound . +.Pp +The PRNG state is per-thread, unless memory allocation fails inside the +library, in which case some threads may share global PRNG state with a +mutex. +The global PRNG state is zeroed on fork in the parent via +.Xr pthread_atfork 3 , +and the per-thread PRNG state is zeroed on fork in the child via +.Xr minherit 2 +with +.Dv MAP_INHERIT_ZERO , +so that the child cannot reuse or see the parent's PRNG state. +The PRNG state is reseeded automatically from the system entropy pool +on the first use of an +.Nm +function after zeroing. +.Pp +The first use of an +.Nm +function may abort the process in the highly unlikely event that +library initialization necessary to implement the security model fails. +Additionally, +.Fn arc4random_stir +and +.Fn arc4random_addrandom +may abort the process in the highly unlikely event that the operating +system fails to provide entropy. .Sh SEE ALSO .Xr rand 3 , -.Xr rand48 3 , -.Xr random 3 -.Sh HISTORY -These functions first appeared in -.Ox 2.1 , -.Fx 3.0 , -.Nx 1.6 , -and -.Dx 1.0 . -The functions -.Fn arc4random , -.Fn arc4random_buf -and -.Fn arc4random_uniform -appeared in glibc 2.36. +.Xr random 3 , +.Xr rnd 4 , +.Xr cprng 9 +.Rs +.%A Daniel J. Bernstein +.%T ChaCha, a variant of Salsa20 +.%D 2008-01-28 +.%O Document ID: 4027b5256e17b9796842e6d0f68b0b5e +.%U http://cr.yp.to/papers.html#chacha +.Re +.Sh BUGS +There is no way to get deterministic, reproducible results out of +.Nm +for testing purposes. .Pp -The original version of this random number generator used the -RC4 (also known as ARC4) algorithm. -In -.Ox 5.5 -it was replaced with the ChaCha20 cipher, and it may be replaced -again in the future as cryptographic techniques advance. -A good mnemonic is -.Dq A Replacement Call for Random . +The name +.Sq arc4random +was chosen for hysterical raisins -- it was originally implemented +using the RC4 stream cipher, which has been known since shortly after +it was published in 1994 to have observable biases in the output, and +is now known to be broken badly enough to admit practical attacks in +the real world. +.\" Bob Jenkins, sci.crypt post dated 1994-09-16, message-id +.\" <359qjg$55v$1@mhadg.production.compuserve.com>, +.\" https://groups.google.com/d/msg/sci.crypt/JsO3xEATGFA/-wO4ttv7BCYJ +.\" +.\" Andrew Roos, `A Class of Weak Keys in the RC4 Stream Cipher', +.\" sci.crypt posts dated 1995-09-22, message-ids +.\" <43u1eh$1j3@hermes.is.co.za> and <44ebge$llf@hermes.is.co.za>. +.\" +.\" Paul Crowley, `Small bias in RC4 experimentally verified', March +.\" 1998, http://www.ciphergoth.org/crypto/rc4/ +Unfortunately, the library found widespread adoption and the name stuck +before anyone recognized that it was silly. +.Pp +The signature of +.Fn arc4random_addrandom +is silly. +There is no reason to require casts or accept negative lengths: +it should take a +.Vt void * +buffer and a +.Vt size_t +length. +But it's too late to change that now. +.Pp +.Fn arc4random_uniform +does not help to choose integers in [0, +.Fa n ) +uniformly at random when +.Fa n +> 2^32. +.Pp +The security model of +.Nm +is stronger than many applications need, and stronger than other +operating systems provide. +For example, applications encrypting messages with random, but not +secret, initialization vectors need only prevent an adversary from +guessing future outputs, since past outputs will have been published +already. +.Pp +On the one hand, +.Nm +could be marginally faster if it were not necessary to prevent an +adversary who sees the state from predicting past outputs. +On the other hand, there are applications in the wild that use +.Nm +to generate key material, such as OpenSSH, so for the sake of +.Nx +users it would be imprudent to weaken the security model. +On the third hand, relying on the security model of +.Nm +in +.Nx +may lead you to an unpleasant surprise on another operating system +whose implementation of +.Nm +has a weaker security model. +.Pp +One may be tempted to create new APIs to accommodate different +security models and performance constraints without unpleasant +surprises on different operating systems. +This should not be done lightly, though, because there are already too +many different choices, and too many opportunities for programmers to +reach for one and pick the wrong one.