Re: [PATCH] arc4random.3: New page documenting the arc4random(3) family of functions

[Alejandro Colomar <alx.manpages@gmail.com>]

[-- 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 --]