[src/trunk]: src/lib/libc getrandom(2), getentropy(3): Rework man pages.

[riastradh <riastradh%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/282742ce0387
branches:  trunk
changeset: 377204:282742ce0387
user:      riastradh <riastradh%NetBSD.org@localhost>
date:      Fri Jun 30 21:44:22 2023 +0000

description:
getrandom(2), getentropy(3): Rework man pages.

Make supportable promises.  Omit needless verbiage.  Give caveats
with cross-references to entropy(7).  Emphasize that security is
necessarily relative to system configuration.

XXX pullup-10

diffstat:

 lib/libc/gen/getentropy.3 |   69 +++++++++----
 lib/libc/sys/getrandom.2  |  223 ++++++++++++++++++---------------------------
 2 files changed, 138 insertions(+), 154 deletions(-)

diffs (truncated from 426 to 300 lines):

diff -r add273f53d84 -r 282742ce0387 lib/libc/gen/getentropy.3
--- a/lib/libc/gen/getentropy.3 Fri Jun 30 21:44:09 2023 +0000
+++ b/lib/libc/gen/getentropy.3 Fri Jun 30 21:44:22 2023 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: getentropy.3,v 1.4 2022/05/31 13:42:59 riastradh Exp $ $
+.\"    $NetBSD: getentropy.3,v 1.5 2023/06/30 21:44:22 riastradh Exp $ $
 .\"
 .\" Copyright (c) 2020 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -27,12 +27,12 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd May 1, 2020
+.Dd February 28, 2023
 .Dt GETENTROPY 3
 .Os
 .Sh NAME
 .Nm getentropy
-.Nd fill a buffer with high quality random data
+.Nd generate uniform random seeds from system entropy for cryptography
 .Sh LIBRARY
 .Lb libc
 .Sh SYNOPSIS
@@ -40,29 +40,32 @@
 .Ft int
 .Fn getentropy "void *buf" "size_t buflen"
 .In limits.h
+.Pp
 .Li #define GETENTROPY_MAX     256
 .Sh DESCRIPTION
 .Pp
 The
-.Fn getentropy
-function fills a buffer with high quality random data, suitable for seeding
-cryptographically secure psuedorandom number generators.
+.Nm
+function fills
+.Fa buf
+with exactly
+.Fa buflen
+independent uniform random bytes derived from the system's entropy
+pool.
 .Pp
-.Fn getentropy
-is only intended for seeding random number generators and is not intended
-for use by regular code which simply needs secure random data.
-For this purpose, please use
+The output of
+.Nm
+is meant to be unpredictable to an adversary and fit for use in
+cryptography.
+See CAVEATS below.
+.Pp
+.Nm
+is meant for seeding random number generators, not for direct use by
+applications; most applications should use
 .Xr arc4random 3 .
 .Pp
-The maximum value for
-.Li buflen
-is 256 bytes.
-.Sh IMPLEMENTATION NOTES
-.Fn getentropy
-reads from the
-.Xr sysctl 7
-variable
-.Li kern.arandom .
+.Fa buflen
+must be at most 256.
 .Sh RETURN VALUES
 .Rv -std getentropy
 .Sh ERRORS
@@ -75,13 +78,33 @@ The
 argument points to an invalid memory address.
 .It Bq Er EINVAL
 More than 256 bytes were requested.
+.El
+.Sh CAVEATS
+Security can only be guaranteed relative to whatever unpredictable
+physical processes or secret seed material are available to the system;
+see
+.Xr entropy 7 .
+.Pp
+On systems which have no hardware random number generator and which
+have not had secret seed material loaded,
+.Nx
+makes a reasonable effort to incorporate samples from various physical
+processes available to it that might be unpredictable from random
+jitter in timing.
+.Pp
+However, the
+.Nm
+interface alone can make no security guarantees without a physical
+system configuration that includes random number generation hardware or
+secret seed material from such hardware on another machine.
 .Sh SEE ALSO
 .Xr arc4random 3 ,
-.Xr rnd 4
+.Xr rnd 4 ,
+.Xr entropy 7
 .Sh STANDARDS
 The
 .Fn getentropy
-function is non-standard.
+function is nonstandard.
 However, it is likely to be included in the next revision of POSIX.
 .Sh HISTORY
 The
@@ -90,5 +113,5 @@ function first appeared in
 .Ox 5.6 ,
 then in
 .Fx 12.0 ,
-and
-.Nx 10 .
+and in
+.Nx 10.0 .
diff -r add273f53d84 -r 282742ce0387 lib/libc/sys/getrandom.2
--- a/lib/libc/sys/getrandom.2  Fri Jun 30 21:44:09 2023 +0000
+++ b/lib/libc/sys/getrandom.2  Fri Jun 30 21:44:22 2023 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: getrandom.2,v 1.1 2020/08/14 00:53:16 riastradh Exp $
+.\"    $NetBSD: getrandom.2,v 1.2 2023/06/30 21:44:22 riastradh Exp $
 .\"
 .\" Copyright (c) 2020 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -27,12 +27,12 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd January 13, 2020
+.Dd March 17, 2022
 .Dt GETRANDOM 2
 .Os
 .Sh NAME
 .Nm getrandom
-.Nd random number generation from system entropy
+.Nd generate uniform random seeds from system entropy for cryptography
 .Sh LIBRARY
 .Lb libc
 .Sh SYNOPSIS
@@ -49,90 +49,56 @@ with up to
 independent uniform random bytes derived from the system's entropy
 pool.
 .Pp
-The function may block until the system has full entropy, meaning that
-the system has observed enough noise from physical processes that an
-adversary cannot predict what state it is in:
-.Bl -bullet -compact
-.It
-When the system has only partial entropy, the output of
-.Fn getrandom
-may be predictable.
-.It
-When the system has full entropy, the output is fit for use as
-cryptographic key material.
-.El
+The output of
+.Nm
+is meant to be unpredictable to an adversary and fit for use in
+cryptography.
+See CAVEATS below.
+.Pp
+.Nm
+is meant for seeding random number generators, not for direct use by
+applications; most applications should use
+.Xr arc4random 3 .
+.Pp
+.Nm
+is a nonstandard extension that was added before POSIX began to
+converge on
+.Xr getentropy 2 .
+Applications should avoid
+.Nm
+and use
+.Xr getentropy 2
+instead;
+.Nm
+may be removed from a later release.
+.Pp
+.Nm
+may block indefinitely unless the
+.Dv GRND_INSECURE
+or
+.Dv GRND_NONBLOCK
+flags are specified.
 .Pp
 The
 .Fa flags
 argument may be:
-.Bl -tag -offset abcd -width GRND_INSECURE
+.Bl -tag -offset indent -width GRND_INSECURE
 .It Li 0
-Block until the system entropy pool has full entropy; then generate
-arbitrarily much data.
-.Em Recommended .
-.Pp
-If interrupted by a signal, may fail with
-.Er EINTR
-or return a short read.
-If successful, guaranteed to return at least 256 bytes even if
-interrupted.
+May block.
+On success, guaranteed to generate the smaller of
+.Fa buflen
+or 256 bytes.
 .It Dv GRND_INSECURE
-Do not block; instead fill
-.Fa buf
-with output derived from whatever is in the system entropy pool so
-far.
-Equivalent to reading from
-.Pa /dev/urandom ;
-see
-.Xr rnd 4 .
-.Pp
-If interrupted by a signal, may fail with
-.Er EINTR
-or return a short read.
-If successful, guaranteed to return at least 256 bytes even if
-interrupted.
+Never blocks.
+On success, guaranteed to generate the smaller of
+.Fa buflen
+or 256 bytes.
+.It Dv GRND_RANDOM
+Will probably block.
+On success, may generate as little as a single byte of data.
 .Pp
-Despite the name, this is secure as long as you only do it
-.Em after
-at least one successful call without
-.Dv GRND_INSECURE ,
-such as
-.Li "getrandom(..., 0)"
-or
-.Li "getrandom(..., GRND_RANDOM)" ,
-or after reading at least one byte from
-.Pa /dev/random .
-.Pp
-.Sy WARNING :
-If you use
-.Dv GRND_INSECURE
-.Em before
-the system has full entropy. the output may enable an adversary to
-search the possible states of the entropy pool by brute force, and
-thereby reduce its entropy to zero.
-Thus, incautious use of
-.Dv GRND_INSECURE
-can ruin the security of the whole system.
-.Pp
-.Nx
-attempts to defend against this threat model by resetting the system's
-entropy estimate to zero in this event, requiring gathering full
-entropy again before
-.Pa /dev/random
-or
-.Fn getrandom
-without
-.Dv GRND_INSECURE
-will unblock, but other operating systems may not.
-.It Dv GRND_RANDOM
-Block until the system entropy pool has full entropy; then generate a
-small amount of data.
-Equivalent to reading from
-.Pa /dev/random ;
-see
-.Xr rnd 4 .
-This is provided mainly for source compatibility with Linux; there is
-essentially no reason to ever use it.
+This is provided for source compatibility with Linux; there is no
+reason to ever use it.
 .El
 .Pp
 The flag
@@ -174,7 +140,9 @@ Since
 .Li "getrandom(..., 0)"
 and
 .Li "getrandom(..., GRND_INSECURE)"
-are guaranteed to return at least 256 bytes if successful, it
+are guaranteed to generate
+.Fa buflen
+or 256 bytes, whichever is smaller, if successful, it
 is sufficient to use, e.g.,
 .Bd -literal -compact
        getrandom(buf, 32, 0) == -1
@@ -187,9 +155,8 @@ to detect failure.
 However, with
 .Dv GRND_RANDOM ,
 .Fn getrandom
-may return as little as a single byte if successful.
+may generate as little as a single byte if successful.
 .Sh EXAMPLES
-.Sy Recommended usage .
 Generate a key for cryptography:
 .Bd -literal
        uint8_t secretkey[32];
@@ -198,53 +165,23 @@ Generate a key for cryptography:
                err(EXIT_FAILURE, "getrandom");
        crypto_secretbox_xsalsa20poly1305(..., secretkey);