Message ID | 20220518191424.3630729-11-adhemerval.zanella@linaro.org |
---|---|
State | New |
Headers | show |
Series | Add arc4random support | expand |
* 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.
diff --git a/manual/math.texi b/manual/math.texi index 477a18b6d1..7d47aaf386 100644 --- a/manual/math.texi +++ b/manual/math.texi @@ -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