arc4random.3: New page documenting the arc4random(3) family of functions
Checks
Commit Message
arc4random(3)
arc4random_uniform(3)
arc4random_buf(3)
Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
man3/arc4random.3 | 104 ++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 104 insertions(+)
create mode 100644 man3/arc4random.3
Comments
arc4random(3) Library Functions Manual arc4random(3)
NAME
arc4random, arc4random_uniform, arc4random_buf - cryptographically‐se‐
cure pseudorandom number generator
LIBRARY
Standard C library (libc, ‐lc)
SYNOPSIS
#include <stdlib.h>
uint32_t arc4random(void);
uint32_t arc4random_uniform(uint32_t upper_bound);
void arc4random_buf(void buf[.n], size_t n);
DESCRIPTION
These functions give cryptographically‐secure random numbers.
arc4random() returns a uniformly‐distributed value.
arc4random_uniform() returns a uniformly‐distributed value less than
upper_bound (see CAVEATS).
arc4random_buf() fills the memory pointed to by buf, with n bytes of
random data.
The rand(3) and rand48(3) families of functions should only be used
where the quality of the random numbers is not a concern and there’s a
need for repeatability of the results. Unless you meet both of those
conditions, use the arc4random() functions.
RETURN VALUE
arc4random() returns a random number.
arc4random_uniform() returns a random number less than upper_bound for
valid input, or 0 when upper_bound is invalid.
ATTRIBUTES
For an explanation of the terms used in this section, see attrib‐
utes(7).
┌────────────────────────────────────────────┬───────────────┬─────────┐
│Interface │ Attribute │ Value │
├────────────────────────────────────────────┼───────────────┼─────────┤
│arc4random(), arc4random_uniform(), │ Thread safety │ MT‐Safe │
│arc4random_buf() │ │ │
└────────────────────────────────────────────┴───────────────┴─────────┘
STANDARDS
These nonstandard functions are present in several Unix systems.
CAVEATS
An upper_bound of 0 doesn’t make sense in a call to arc4random_uni‐
form(). Such a call will fail, and return 0. Be careful, since that
value is not less than upper_bound. In some cases, such as accessing
an array, using that value could result in Undefined Behavior.
SEE ALSO
getrandom(3), rand(3), rand48(3), random(7)
Linux man‐pages (unreleased) (date) arc4random(3)
On Sun Jan 1, 2023 at 5:26 PM CET, Alejandro Colomar wrote:
> arc4random(3)
> arc4random_uniform(3)
> arc4random_buf(3)
>
> Signed-off-by: Alejandro Colomar <alx@kernel.org>
> ---
> man3/arc4random.3 | 104 ++++++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 104 insertions(+)
> create mode 100644 man3/arc4random.3
>
> diff --git a/man3/arc4random.3 b/man3/arc4random.3
> new file mode 100644
> index 000000000..5fd292321
> --- /dev/null
> +++ b/man3/arc4random.3
> @@ -0,0 +1,104 @@
> +.\" Copyright (C) 2023 Alejandro Colomar <alx@kernel.org>
> +.\"
> +.\" SPDX-License-Identifier: Linux-man-pages-copyleft
> +.\"
> +.TH arc4random 3 (date) "Linux man-pages (unreleased)"
> +.SH NAME
> +arc4random, arc4random_uniform, arc4random_buf
> +\- cryptographically-secure pseudorandom number generator
> +.SH LIBRARY
> +Standard C library
> +.RI ( libc ", " -lc )
> +.SH SYNOPSIS
> +.nf
> +.B #include <stdlib.h>
> +.PP
> +.B uint32_t arc4random(void);
> +.BI "uint32_t arc4random_uniform(uint32_t " upper_bound );
> +.BI "void arc4random_buf(void " buf [. n "], size_t " n );
> +.fi
> +.SH DESCRIPTION
> +These functions give cryptographically-secure random numbers.
> +.PP
> +.BR arc4random ()
> +returns a uniformly-distributed value.
> +.PP
> +.BR arc4random_uniform ()
> +returns a uniformly-distributed value less than
> +.I upper_bound
> +(see CAVEATS).
> +.PP
> +.BR arc4random_buf ()
> +fills the memory pointed to by
> +.IR buf ,
> +with
> +.I n
> +bytes of random data.
> +.PP
> +The
> +.BR rand (3)
> +and
> +.BR rand48 (3)
> +families of functions should only be used where
> +the quality of the random numbers is not a concern
> +.I and
> +there's a need for repeatability of the results.
> +Unless you meet both of those conditions,
> +use the
> +.BR arc4random ()
> +functions.
> +.SH RETURN VALUE
> +.BR arc4random ()
> +returns a random number.
> +.PP
> +.BR arc4random_uniform ()
> +returns a random number less than
> +.I upper_bound
> +for valid input, or
> +.B 0
> +when
> +.I upper_bound
> +is invalid.
> +.SH ATTRIBUTES
> +For an explanation of the terms used in this section, see
> +.BR attributes (7).
> +.ad l
> +.nh
> +.TS
> +allbox;
> +lbx lb lb
> +l l l.
> +Interface Attribute Value
> +T{
> +.BR arc4random (),
> +.BR arc4random_uniform (),
> +.BR arc4random_buf ()
> +T} Thread safety MT-Safe
> +.TE
> +.hy
> +.ad
> +.sp 1
> +.SH STANDARDS
> +These nonstandard functions are present in several Unix systems.
I'm not a native speaker, but I think it should be s/in/on/.
--
Best Regards,
Tom Schwindl
Hi Tom,
On 1/1/23 17:39, Tom Schwindl wrote:
>> +.SH STANDARDS
>> +These nonstandard functions are present in several Unix systems.
>
> I'm not a native speaker, but I think it should be s/in/on/.
Thanks. I'm not either, and always have doubts about those, so I'll assume
you're right.
Cheers,
Alex
>
> --
> Best Regards,
> Tom Schwindl
--
<http://www.alejandro-colomar.es/>
* Alejandro Colomar <alx.manpages@gmail.com>, 2023-01-01 17:27:
>arc4random_uniform() returns a random number less than upper_bound for
>valid input, or 0 when upper_bound is invalid.
Is the "or 0 ..." thing part of the API? I could find anything like that
in glibc docs or BSD man pages.
>STANDARDS
> These nonstandard functions are present in several Unix systems.
That's not really helpful. Also, the VERSIONS section is missing ("every
new interface should include a VERSIONS section").
In contrast, the libbsd man page is much more informative:
>These functions first appeared in OpenBSD 2.1, FreeBSD 3.0, NetBSD
>1.6, and DragonFly 1.0. The functions arc4random(), arc4random_buf()
>and arc4random_uniform() appeared in glibc 2.36.
>
>The original version of this random number generator used the RC4 (also
>known as ARC4) algorithm. In OpenBSD 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 “A Replacement
>Call for Random”.
Hi Jakub,
On 3/17/23 22:31, Jakub Wilk wrote:
> * Alejandro Colomar <alx.manpages@gmail.com>, 2023-01-01 17:27:
>> arc4random_uniform() returns a random number less than upper_bound for
>> valid input, or 0 when upper_bound is invalid.
>
> Is the "or 0 ..." thing part of the API?
Yes, it is part of the (undocumented) API. At least, their authors
claim to have thought about it when designing it, and purposefully took
the decision of returning 0. They fail to acknowledge that it's a bug,
also fail to acknowledge that their documentation doesn't document this
behavior, and don't have any intention of changing the API because
"we don't know what can possibly fail; you'd have to audit all software
in the world to confirm that none depends on that detail".
I have serious doubts that any software can depend on that, because
mathematically it doesn't make any sense, so algorithms will likely
have to purposefully special-case arc4random_uniform(0), but can't know
for sure, because well, I haven't audited all software in the world.
I didn't find any case in OpenBSD's source code that depends on that,
however.
> I could find anything like that
> in glibc docs or BSD man pages.
<https://inbox.sourceware.org/libc-alpha/20230101162627.28031-1-alx@kernel.org/>
Their manual page is bogus, and the funny thing is that one of Theo's
arguments to reject a proposal to fix the bug in the API was that I
wouldn't be able to document it reasonably. Well, as you saw, it's the
current behavior that isn't well documented, and I had to special-case
it in BUGS.
>
>> STANDARDS
>> These nonstandard functions are present in several Unix systems.
>
> That's not really helpful. Also, the VERSIONS section is missing ("every
> new interface should include a VERSIONS section").
I thought of that this morning, while doing some reorganization of that
section globally. I'll add the version.
>
> In contrast, the libbsd man page is much more informative:
>
>> These functions first appeared in OpenBSD 2.1, FreeBSD 3.0, NetBSD
>> 1.6, and DragonFly 1.0. The functions arc4random(), arc4random_buf()
>> and arc4random_uniform() appeared in glibc 2.36.
Yup. :)
Thanks a lot for this thorough review!
Alex
>>
>> The original version of this random number generator used the RC4 (also
>> known as ARC4) algorithm. In OpenBSD 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 “A Replacement
>> Call for Random”.
>
On 3/17/23 22:44, Alejandro Colomar wrote:
> Hi Jakub,
>
> On 3/17/23 22:31, Jakub Wilk wrote:
>> * Alejandro Colomar <alx.manpages@gmail.com>, 2023-01-01 17:27:
>>> arc4random_uniform() returns a random number less than upper_bound for
>>> valid input, or 0 when upper_bound is invalid.
>>
>> Is the "or 0 ..." thing part of the API?
>
> Yes, it is part of the (undocumented) API. At least, their authors
> claim to have thought about it when designing it, and purposefully took
> the decision of returning 0. They fail to acknowledge that it's a bug,
> also fail to acknowledge that their documentation doesn't document this
> behavior, and don't have any intention of changing the API because
> "we don't know what can possibly fail; you'd have to audit all software
> in the world to confirm that none depends on that detail".
>
> I have serious doubts that any software can depend on that, because
> mathematically it doesn't make any sense, so algorithms will likely
> have to purposefully special-case arc4random_uniform(0), but can't know
> for sure, because well, I haven't audited all software in the world.
>
> I didn't find any case in OpenBSD's source code that depends on that,
> however.
>
>> I could find anything like that
>> in glibc docs or BSD man pages.
>
> <https://inbox.sourceware.org/libc-alpha/20230101162627.28031-1-alx@kernel.org/>
Sorry, I pasted the wrong link. I wanted to paste this one:
<https://inbox.sourceware.org/libc-alpha/20221231023653.41877-1-alx@kernel.org/T/>
>
> Their manual page is bogus, and the funny thing is that one of Theo's
> arguments to reject a proposal to fix the bug in the API was that I
> wouldn't be able to document it reasonably. Well, as you saw, it's the
> current behavior that isn't well documented, and I had to special-case
> it in BUGS.
>
>>
>>> STANDARDS
>>> These nonstandard functions are present in several Unix systems.
>>
>> That's not really helpful. Also, the VERSIONS section is missing ("every
>> new interface should include a VERSIONS section").
>
> I thought of that this morning, while doing some reorganization of that
> section globally. I'll add the version.
>
>>
>> In contrast, the libbsd man page is much more informative:
>>
>>> These functions first appeared in OpenBSD 2.1, FreeBSD 3.0, NetBSD
>>> 1.6, and DragonFly 1.0. The functions arc4random(), arc4random_buf()
>>> and arc4random_uniform() appeared in glibc 2.36.
>
> Yup. :)
>
> Thanks a lot for this thorough review!
>
> Alex
>
>>>
>>> The original version of this random number generator used the RC4 (also
>>> known as ARC4) algorithm. In OpenBSD 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 “A Replacement
>>> Call for Random”.
>>
>
new file mode 100644
@@ -0,0 +1,104 @@
+.\" Copyright (C) 2023 Alejandro Colomar <alx@kernel.org>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH arc4random 3 (date) "Linux man-pages (unreleased)"
+.SH NAME
+arc4random, arc4random_uniform, arc4random_buf
+\- cryptographically-secure pseudorandom number generator
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " -lc )
+.SH SYNOPSIS
+.nf
+.B #include <stdlib.h>
+.PP
+.B uint32_t arc4random(void);
+.BI "uint32_t arc4random_uniform(uint32_t " upper_bound );
+.BI "void arc4random_buf(void " buf [. n "], size_t " n );
+.fi
+.SH DESCRIPTION
+These functions give cryptographically-secure random numbers.
+.PP
+.BR arc4random ()
+returns a uniformly-distributed value.
+.PP
+.BR arc4random_uniform ()
+returns a uniformly-distributed value less than
+.I upper_bound
+(see CAVEATS).
+.PP
+.BR arc4random_buf ()
+fills the memory pointed to by
+.IR buf ,
+with
+.I n
+bytes of random data.
+.PP
+The
+.BR rand (3)
+and
+.BR rand48 (3)
+families of functions should only be used where
+the quality of the random numbers is not a concern
+.I and
+there's a need for repeatability of the results.
+Unless you meet both of those conditions,
+use the
+.BR arc4random ()
+functions.
+.SH RETURN VALUE
+.BR arc4random ()
+returns a random number.
+.PP
+.BR arc4random_uniform ()
+returns a random number less than
+.I upper_bound
+for valid input, or
+.B 0
+when
+.I upper_bound
+is invalid.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.ad l
+.nh
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface Attribute Value
+T{
+.BR arc4random (),
+.BR arc4random_uniform (),
+.BR arc4random_buf ()
+T} Thread safety MT-Safe
+.TE
+.hy
+.ad
+.sp 1
+.SH STANDARDS
+These nonstandard functions are present in several Unix systems.
+.SH CAVEATS
+An
+.I upper_bound
+of
+.B 0
+doesn't make sense in a call to
+.BR arc4random_uniform ().
+Such a call will fail, and return
+.BR 0 .
+Be careful,
+since that value is
+.I not
+less than
+.IR upper_bound .
+In some cases,
+such as accessing an array,
+using that value could result in Undefined Behavior.
+.SH SEE ALSO
+.BR getrandom (3),
+.BR rand (3),
+.BR rand48 (3),
+.BR random (7)