mirror of
https://gitlab.freedesktop.org/libbsd/libbsd.git
synced 2025-05-10 10:26:48 +02:00
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
This commit is contained in:
Guillem Jover
parent
830dd88a98
commit
4c6da577a1
38
COPYING
38
COPYING
@ -6,37 +6,6 @@ Copyright:
|
||||
Copyright © 2004-2006, 2008-2022 Guillem Jover <guillem@hadrons.org>
|
||||
License: BSD-3-clause
|
||||
|
||||
Files:
|
||||
man/arc4random.3bsd
|
||||
Copyright:
|
||||
Copyright 1997 Niels Provos <provos@physnet.uni-hamburg.de>
|
||||
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 <jmg@FreeBSD.org>
|
||||
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.
|
||||
|
||||
@ -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 <provos@physnet.uni-hamburg.de>
|
||||
.\" 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.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user