diff mbox series

arc4random.3: New page documenting the arc4random(3) family of functions

Message ID 20230101162627.28031-1-alx@kernel.org
State New
Headers show
Series arc4random.3: New page documenting the arc4random(3) family of functions | expand

Commit Message

Alejandro Colomar Jan. 1, 2023, 4:26 p.m. UTC 
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

Alejandro Colomar Jan. 1, 2023, 4:27 p.m. UTC | #1 
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)
Tom Schwindl Jan. 1, 2023, 4:39 p.m. UTC | #2 
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
Alejandro Colomar Jan. 1, 2023, 4:41 p.m. UTC | #3 
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
Jakub Wilk March 17, 2023, 9:31 p.m. UTC | #4 
* 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”.
Alejandro Colomar March 17, 2023, 9:44 p.m. UTC | #5 
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”.
>
Alejandro Colomar March 17, 2023, 9:54 p.m. UTC | #6 
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”.
>>
>
diff mbox series

Patch

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)