From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-oa1-x36.google.com (mail-oa1-x36.google.com [IPv6:2001:4860:4864:20::36]) by sourceware.org (Postfix) with ESMTPS id C751A384D1BB for ; Wed, 29 Jun 2022 21:55:23 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org C751A384D1BB Received: by mail-oa1-x36.google.com with SMTP id 586e51a60fabf-101e1a33fe3so23233056fac.11 for ; Wed, 29 Jun 2022 14:55:23 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:content-transfer-encoding:mime-version :subject:date:references:to:in-reply-to:message-id; bh=vomRFWy8bDYk/gLxEurADX6fWztr5PB4RYr0I9yysIo=; b=mjw0MJiszYqsbZmnatCm9e6Gi1R0bRyj15BGsnYb+6xx9XQ8mdbOYm+KHPF4rb/gpv jfTYldEUPQifQsL64gN1Uf5lEY64BeDnEFxkAJqWUtLbPXDHN45FJA3J7QS26g6QdYE4 BZPIXaJYUF0lP+Ua8sYl9iLdDLD/mGJbDT9GnvYPd80A805tFEmctHb3ERuS+oLK2sKr kLMWEV1/G6FZ6gDXrEIDtAKtssRQMbDLvGjVk8CA2MoNvNLoswjGZvdthQ46+rvlLmBp 514qWukml4or0bam1GOaMqoeXdfSQDGuXTMMGyOOPwmQr+ctF6WmY2gxvIA3BoDyJWXk jIHA== X-Gm-Message-State: AJIora+InP5lpv8hgX812Br5fFjSpEaGlmv07Xz6YPAoCV3qhMhqlbzq lL5eEdJjeM0uEIn6H1wUnZDqswXDnr04dzkK X-Google-Smtp-Source: AGRyM1tewdH6sU4KjdRd0BhDL7Lgi0vq8u/NEvxUmv9mhOJbIDD5l9w81RBVMBkJwL4KfbF8AR3g/Q== X-Received: by 2002:a05:6870:5a0:b0:101:229:eb16 with SMTP id m32-20020a05687005a000b001010229eb16mr3188592oap.268.1656539723005; Wed, 29 Jun 2022 14:55:23 -0700 (PDT) Received: from smtpclient.apple ([2804:431:c7cb:fef6:c4a4:5cf:6a9a:8440]) by smtp.gmail.com with ESMTPSA id r66-20020acada45000000b0032f7605d1a3sm9218947oig.31.2022.06.29.14.55.22 (version=TLS1_2 cipher=ECDHE-ECDSA-AES128-GCM-SHA256 bits=128/128); Wed, 29 Jun 2022 14:55:22 -0700 (PDT) From: Adhemerval Zanella Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Mime-Version: 1.0 (Mac OS X Mail 16.0 \(3696.100.31\)) Subject: Re: [PATCH v8 9/9] manual: Add documentation for arc4random functions Date: Wed, 29 Jun 2022 18:55:20 -0300 References: <20220629213428.3065430-1-adhemerval.zanella@linaro.org> <20220629213428.3065430-10-adhemerval.zanella@linaro.org> To: libc-alpha@sourceware.org, Florian Weimer In-Reply-To: <20220629213428.3065430-10-adhemerval.zanella@linaro.org> Message-Id: <074A07BA-BA80-48BD-B6E9-9662A124474F@linaro.org> X-Mailer: Apple Mail (2.3696.100.31) X-Spam-Status: No, score=-12.4 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, RCVD_IN_DNSWL_NONE, SPF_HELO_NONE, SPF_PASS, TXREP, T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: libc-alpha@sourceware.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Libc-alpha mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 29 Jun 2022 21:55:25 -0000 > On 29 Jun 2022, at 18:34, Adhemerval Zanella = wrote: >=20 > --- > manual/math.texi | 45 +++++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 45 insertions(+) >=20 > diff --git a/manual/math.texi b/manual/math.texi > index 477a18b6d1..ab96726e57 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 >=20 > @node ISO Random > @@ -1985,6 +1986,50 @@ This function is a GNU extension and should not = be used in portable > programs. > @end deftypefun >=20 > +@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 when using @theglibc{} @code{syscall} function. > + > +The prototypes for these functions are in @file{stdlib.h}. > +@pindex stdlib.h > + > +@deftypefun int32_t arc4random (void) > +@standards{BSD, stdlib.h} > +@safety{@mtsafe{}@asunsafe{@asucorrupt{}}@acsafe{}} > +This function returns a single 32-bit value in the range of @code{0} = to > +@code{2^32=E2=88=921} (inclusive), which is twice the range of = @code{rand} and > +@code{random}. > +@end deftypefun > + > +@deftypefun void arc4random (void *@var{buffer}, size_t @var{length}) And this should be arc4random_buf, I have fixed it locally. > +@standards{BSD, 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{BSD, 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. > +@end deftypefun > + > @node FP Function Optimizations > @section Is Fast Code or Small Code preferred? > @cindex Optimization > --=20 > 2.34.1 >=20