From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-oa1-x2a.google.com (mail-oa1-x2a.google.com [IPv6:2001:4860:4864:20::2a]) by sourceware.org (Postfix) with ESMTPS id 2C819385829E for ; Tue, 28 Jun 2022 19:15:48 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 2C819385829E Received: by mail-oa1-x2a.google.com with SMTP id 586e51a60fabf-f2a4c51c45so18331840fac.9 for ; Tue, 28 Jun 2022 12:15:48 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:mime-version:subject:from:in-reply-to:date:cc :content-transfer-encoding:message-id:references:to; bh=Q1kQ5qas/tZ8hb4x2HvnSxupQrXeOioRrsIpygdcNvI=; b=nkIMZ9b0HFBy56D9luqlsfqBMbfiP+YxDfoVmuFO+HwiMudyTjqalzIRNWHuGM+Q0S 9Pp2xf/5A/UnSyBK70AimIsfsdMV0J9OEAfTRb4Jrs9PJGwYmGI8DRDXdNsjDeOGM8Z2 piq52iDMVd4gJstQmNAlQgZ4IsMcQcaEKxg4OLhU/fUuL9jM/AcBX1fIhe7CVdfgb+lI p0lxKefbI32xlQRd2afDqkB8ehIBXhxK4CBY3CVSRxxh32N84wGxTZyrYpXc/AMaLNFK bU1OPBKNqUd+UUMfR5pOcjeezVKXWiP/qQw5UxQBRjQXf+h++ekvnVkvJXLfUc/FUOh1 /6+A== X-Gm-Message-State: AJIora/z/yovGi2cT0gofHQR4XBbdgksdNaBi4am1bFXiXWFB2typ++2 J0QHdaaJSUccNaHC8aZhY692dW4ME0ySd+uP X-Google-Smtp-Source: AGRyM1tIH6QCnVoEyIi7qF4bI0/mMkQF+koR0o2sTQ+0qeYyOZyp4QOZX1eXCV75XeGiCw5Xa2jIAQ== X-Received: by 2002:a05:6870:148c:b0:101:d150:6ca1 with SMTP id k12-20020a056870148c00b00101d1506ca1mr649508oab.177.1656443747428; Tue, 28 Jun 2022 12:15:47 -0700 (PDT) Received: from smtpclient.apple ([2804:431:c7ca:6d95:25db:29b6:be9b:9202]) by smtp.gmail.com with ESMTPSA id z89-20020a9d24e2000000b0060beefeb3c4sm8194626ota.64.2022.06.28.12.15.45 (version=TLS1_2 cipher=ECDHE-ECDSA-AES128-GCM-SHA256 bits=128/128); Tue, 28 Jun 2022 12:15:47 -0700 (PDT) Content-Type: text/plain; charset=utf-8 Mime-Version: 1.0 (Mac OS X Mail 16.0 \(3696.100.31\)) Subject: Re: [PATCH v6 10/10] manual: Add documentation for arc4random functions From: Adhemerval Zanella In-Reply-To: <87czetf0qj.fsf@oldenburg.str.redhat.com> Date: Tue, 28 Jun 2022 16:15:42 -0300 Cc: Adhemerval Zanella via Libc-alpha Content-Transfer-Encoding: quoted-printable Message-Id: References: <20220518191424.3630729-1-adhemerval.zanella@linaro.org> <20220518191424.3630729-11-adhemerval.zanella@linaro.org> <87czetf0qj.fsf@oldenburg.str.redhat.com> To: Florian Weimer X-Mailer: Apple Mail (2.3696.100.31) X-Spam-Status: No, score=-6.4 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, 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: Tue, 28 Jun 2022 19:15:49 -0000 > On 28 Jun 2022, at 09:09, Florian Weimer wrote: >=20 > * Adhemerval Zanella via Libc-alpha: >=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 through glibc wrapper). >=20 > =E2=80=9Cor when using @theglibc{} @code{syscall} funcition=E2=80=9D? Ack, I also removed the sentence from parentheses. >=20 >> +The prototypes for these functions are in @file{stdlib.h}. >> +@pindex stdlib.h >> + >> +@deftypefun int32_t arc4random (void) >> +@standards{GNU, stdlib.h} >=20 > Should be BSD, I think. Likewise below. Ack. >=20 >> +@safety{@mtsafe{}@asunsafe{@asucorrupt{}}@acsafe{}} >> +This function returns a single 32-bit value in the range of 0 to = 2^32=E2=88=921, >> +which is twice the range of @code{rand} and @code{random}. >> +@end deftypefun >=20 > 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. >=20 >> +@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. >=20 > 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.=20=