* [PATCH] arc4random.3: New page documenting the arc4random(3) family of functions
@ 2023-01-01 16:26 Alejandro Colomar
2023-01-01 16:27 ` Alejandro Colomar
2023-01-01 16:39 ` Tom Schwindl
0 siblings, 2 replies; 7+ messages in thread
From: Alejandro Colomar @ 2023-01-01 16:26 UTC (permalink / raw)
To: linux-man; +Cc: Alejandro Colomar, libc-alpha, Jason A. Donenfeld
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.
+.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)
--
2.39.0
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [PATCH] arc4random.3: New page documenting the arc4random(3) family of functions
2023-01-01 16:26 [PATCH] arc4random.3: New page documenting the arc4random(3) family of functions Alejandro Colomar
@ 2023-01-01 16:27 ` Alejandro Colomar
2023-03-17 21:31 ` Jakub Wilk
2023-01-01 16:39 ` Tom Schwindl
1 sibling, 1 reply; 7+ messages in thread
From: Alejandro Colomar @ 2023-01-01 16:27 UTC (permalink / raw)
To: linux-man; +Cc: Alejandro Colomar, libc-alpha, Jason A. Donenfeld
[-- Attachment #1.1: Type: text/plain, Size: 2975 bytes --]
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)
[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [PATCH] arc4random.3: New page documenting the arc4random(3) family of functions
2023-01-01 16:26 [PATCH] arc4random.3: New page documenting the arc4random(3) family of functions Alejandro Colomar
2023-01-01 16:27 ` Alejandro Colomar
@ 2023-01-01 16:39 ` Tom Schwindl
2023-01-01 16:41 ` Alejandro Colomar
1 sibling, 1 reply; 7+ messages in thread
From: Tom Schwindl @ 2023-01-01 16:39 UTC (permalink / raw)
To: Alejandro Colomar, linux-man
Cc: Alejandro Colomar, libc-alpha, Jason A. Donenfeld
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
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [PATCH] arc4random.3: New page documenting the arc4random(3) family of functions
2023-01-01 16:39 ` Tom Schwindl
@ 2023-01-01 16:41 ` Alejandro Colomar
0 siblings, 0 replies; 7+ messages in thread
From: Alejandro Colomar @ 2023-01-01 16:41 UTC (permalink / raw)
To: Tom Schwindl, linux-man; +Cc: Alejandro Colomar, libc-alpha, Jason A. Donenfeld
[-- Attachment #1.1: Type: text/plain, Size: 408 bytes --]
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/>
[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [PATCH] arc4random.3: New page documenting the arc4random(3) family of functions
2023-01-01 16:27 ` Alejandro Colomar
@ 2023-03-17 21:31 ` Jakub Wilk
2023-03-17 21:44 ` Alejandro Colomar
0 siblings, 1 reply; 7+ messages in thread
From: Jakub Wilk @ 2023-03-17 21:31 UTC (permalink / raw)
To: Alejandro Colomar
Cc: linux-man, Alejandro Colomar, libc-alpha, Jason A. Donenfeld
* 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”.
--
Jakub Wilk
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [PATCH] arc4random.3: New page documenting the arc4random(3) family of functions
2023-03-17 21:31 ` Jakub Wilk
@ 2023-03-17 21:44 ` Alejandro Colomar
2023-03-17 21:54 ` Alejandro Colomar
0 siblings, 1 reply; 7+ messages in thread
From: Alejandro Colomar @ 2023-03-17 21:44 UTC (permalink / raw)
To: Jakub Wilk
Cc: linux-man, Alejandro Colomar, libc-alpha, Jason A. Donenfeld,
Ingo Schwarze
[-- Attachment #1.1: Type: text/plain, Size: 2720 bytes --]
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”.
>
--
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5
[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [PATCH] arc4random.3: New page documenting the arc4random(3) family of functions
2023-03-17 21:44 ` Alejandro Colomar
@ 2023-03-17 21:54 ` Alejandro Colomar
0 siblings, 0 replies; 7+ messages in thread
From: Alejandro Colomar @ 2023-03-17 21:54 UTC (permalink / raw)
To: Jakub Wilk
Cc: linux-man, Alejandro Colomar, libc-alpha, Jason A. Donenfeld,
Ingo Schwarze
[-- Attachment #1.1: Type: text/plain, Size: 3024 bytes --]
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”.
>>
>
--
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5
[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2023-03-17 21:54 UTC | newest]
Thread overview: 7+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2023-01-01 16:26 [PATCH] arc4random.3: New page documenting the arc4random(3) family of functions Alejandro Colomar
2023-01-01 16:27 ` Alejandro Colomar
2023-03-17 21:31 ` Jakub Wilk
2023-03-17 21:44 ` Alejandro Colomar
2023-03-17 21:54 ` Alejandro Colomar
2023-01-01 16:39 ` Tom Schwindl
2023-01-01 16:41 ` Alejandro Colomar
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).