[v6,10/10] manual: Add documentation for arc4random functions
Checks
Context |
Check |
Description |
dj/TryBot-apply_patch |
success
|
Patch applied to master at the time it was sent
|
dj/TryBot-32bit |
success
|
Build for i686
|
Commit Message
---
manual/math.texi | 49 ++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 49 insertions(+)
Comments
* Adhemerval Zanella via Libc-alpha:
> +@node High Quality Random
> +@subsection High Quality Random Number Functions
> +
> +This section describes the random number functions provided as a GNU
> +extension, based on OpenBSD interfaces.
> +
> +@Theglibc{} uses kernel entropy obtained either through @code{getrandom}
> +or by reading @file{/dev/urandom} to seed and periodically re-seed the
> +internal state. A per-thread data pool is used, which allows fast output
> +generation.
> +
> +Although these functions provide higher random quality than ISO, BSD, and
> +SVID functions, these still use a Pseudo-Random generator and should not
> +be used in cryptographic contexts.
> +
> +The internal state is cleared and reseed with kernel entropy on @code{fork}
> +and @code{_Fork} (it is not cleared for either direct @code{clone} syscall
> +or through glibc wrapper).
“or when using @theglibc{} @code{syscall} funcition”?
> +The prototypes for these functions are in @file{stdlib.h}.
> +@pindex stdlib.h
> +
> +@deftypefun int32_t arc4random (void)
> +@standards{GNU, stdlib.h}
Should be BSD, I think. Likewise below.
> +@safety{@mtsafe{}@asunsafe{@asucorrupt{}}@acsafe{}}
> +This function returns a single 32-bit value in the range of 0 to 2^32−1,
> +which is twice the range of @code{rand} and @code{random}.
> +@end deftypefun
Can we use @math for the exponent? And please say that the range is
inclusive.
> +@deftypefun uint32_t arc4random_uniform (uint32_t @var{upper_bound})
> +@standards{GNU, stdlib.h}
> +@safety{@mtsafe{}@asunsafe{@asucorrupt{}}@acsafe{}}
> +This function returns a single 32-bit value, uniformly distributed but
> +less than the @var{upper_bound}. It avoids the @w{modulo bias} when the
> +upper bound is not a power of two.
> +
> +The algorithm obtains the exact sampling of a discrete uniform variable
> +using an optimal number of random bits for any range @var{upper_bounds},
> +allowing to consume as less as possible data from the per-thread entropy
> +pool.
I think this overspecifies the implementation. And we obtain randomness
in blocks of 8 bits, IIRC, so it's not optimal in our implementation.
Thanks,
Florian
> On 28 Jun 2022, at 09:09, Florian Weimer <fweimer@redhat.com> wrote:
>
> * Adhemerval Zanella via Libc-alpha:
>
>> +@node High Quality Random
>> +@subsection High Quality Random Number Functions
>> +
>> +This section describes the random number functions provided as a GNU
>> +extension, based on OpenBSD interfaces.
>> +
>> +@Theglibc{} uses kernel entropy obtained either through @code{getrandom}
>> +or by reading @file{/dev/urandom} to seed and periodically re-seed the
>> +internal state. A per-thread data pool is used, which allows fast output
>> +generation.
>> +
>> +Although these functions provide higher random quality than ISO, BSD, and
>> +SVID functions, these still use a Pseudo-Random generator and should not
>> +be used in cryptographic contexts.
>> +
>> +The internal state is cleared and reseed with kernel entropy on @code{fork}
>> +and @code{_Fork} (it is not cleared for either direct @code{clone} syscall
>> +or through glibc wrapper).
>
> “or when using @theglibc{} @code{syscall} funcition”?
Ack, I also removed the sentence from parentheses.
>
>> +The prototypes for these functions are in @file{stdlib.h}.
>> +@pindex stdlib.h
>> +
>> +@deftypefun int32_t arc4random (void)
>> +@standards{GNU, stdlib.h}
>
> Should be BSD, I think. Likewise below.
Ack.
>
>> +@safety{@mtsafe{}@asunsafe{@asucorrupt{}}@acsafe{}}
>> +This function returns a single 32-bit value in the range of 0 to 2^32−1,
>> +which is twice the range of @code{rand} and @code{random}.
>> +@end deftypefun
>
> Can we use @math for the exponent? And please say that the range is
> inclusive.
I changed to use @code, which is what other rand functions use. I added
the inclusive remark as well.
>
>> +@deftypefun uint32_t arc4random_uniform (uint32_t @var{upper_bound})
>> +@standards{GNU, stdlib.h}
>> +@safety{@mtsafe{}@asunsafe{@asucorrupt{}}@acsafe{}}
>> +This function returns a single 32-bit value, uniformly distributed but
>> +less than the @var{upper_bound}. It avoids the @w{modulo bias} when the
>> +upper bound is not a power of two.
>> +
>> +The algorithm obtains the exact sampling of a discrete uniform variable
>> +using an optimal number of random bits for any range @var{upper_bounds},
>> +allowing to consume as less as possible data from the per-thread entropy
>> +pool.
>
> I think this overspecifies the implementation. And we obtain randomness
> in blocks of 8 bits, IIRC, so it's not optimal in our implementation.
Ok, I will remove the last paragraph.
@@ -1447,6 +1447,7 @@ systems.
* ISO Random:: @code{rand} and friends.
* BSD Random:: @code{random} and friends.
* SVID Random:: @code{drand48} and friends.
+* High Quality Random:: @code{arc4random} and friends.
@end menu
@node ISO Random
@@ -1985,6 +1986,54 @@ This function is a GNU extension and should not be used in portable
programs.
@end deftypefun
+@node High Quality Random
+@subsection High Quality Random Number Functions
+
+This section describes the random number functions provided as a GNU
+extension, based on OpenBSD interfaces.
+
+@Theglibc{} uses kernel entropy obtained either through @code{getrandom}
+or by reading @file{/dev/urandom} to seed and periodically re-seed the
+internal state. A per-thread data pool is used, which allows fast output
+generation.
+
+Although these functions provide higher random quality than ISO, BSD, and
+SVID functions, these still use a Pseudo-Random generator and should not
+be used in cryptographic contexts.
+
+The internal state is cleared and reseed with kernel entropy on @code{fork}
+and @code{_Fork} (it is not cleared for either direct @code{clone} syscall
+or through glibc wrapper).
+
+The prototypes for these functions are in @file{stdlib.h}.
+@pindex stdlib.h
+
+@deftypefun int32_t arc4random (void)
+@standards{GNU, stdlib.h}
+@safety{@mtsafe{}@asunsafe{@asucorrupt{}}@acsafe{}}
+This function returns a single 32-bit value in the range of 0 to 2^32−1,
+which is twice the range of @code{rand} and @code{random}.
+@end deftypefun
+
+@deftypefun void arc4random (void *@var{buffer}, size_t @var{length})
+@standards{GNU, stdlib.h}
+@safety{@mtsafe{}@asunsafe{@asucorrupt{}}@acsafe{}}
+This function fills the region @var{buffer} of @var{length} with random data.
+@end deftypefun
+
+@deftypefun uint32_t arc4random_uniform (uint32_t @var{upper_bound})
+@standards{GNU, stdlib.h}
+@safety{@mtsafe{}@asunsafe{@asucorrupt{}}@acsafe{}}
+This function returns a single 32-bit value, uniformly distributed but
+less than the @var{upper_bound}. It avoids the @w{modulo bias} when the
+upper bound is not a power of two.
+
+The algorithm obtains the exact sampling of a discrete uniform variable
+using an optimal number of random bits for any range @var{upper_bounds},
+allowing to consume as less as possible data from the per-thread entropy
+pool.
+@end deftypefun
+
@node FP Function Optimizations
@section Is Fast Code or Small Code preferred?
@cindex Optimization