Module Name: src
Committed By: riastradh
Date: Fri Jun 30 21:44:22 UTC 2023
Modified Files:
src/lib/libc/gen: getentropy.3
src/lib/libc/sys: getrandom.2
Log Message:
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
To generate a diff of this commit:
cvs rdiff -u -r1.4 -r1.5 src/lib/libc/gen/getentropy.3
cvs rdiff -u -r1.1 -r1.2 src/lib/libc/sys/getrandom.2
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/lib/libc/gen/getentropy.3
diff -u src/lib/libc/gen/getentropy.3:1.4 src/lib/libc/gen/getentropy.3:1.5
--- src/lib/libc/gen/getentropy.3:1.4 Tue May 31 13:42:59 2022
+++ src/lib/libc/gen/getentropy.3 Fri Jun 30 21:44:22 2023
@@ -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 .
Index: src/lib/libc/sys/getrandom.2
diff -u src/lib/libc/sys/getrandom.2:1.1 src/lib/libc/sys/getrandom.2:1.2
--- src/lib/libc/sys/getrandom.2:1.1 Fri Aug 14 00:53:16 2020
+++ src/lib/libc/sys/getrandom.2 Fri Jun 30 21:44:22 2023
@@ -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.
-.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.
+Never blocks.
+On success, guaranteed to generate the smaller of
+.Fa buflen
+or 256 bytes.
.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.
+Will probably block.
+On success, may generate as little as a single byte of data.
+.Pp
+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);
.Ed
-.Pp
-Other idioms for illustration:
-.Bl -bullet
-.It
-Wait for entropy once, and then generate many keys without waiting:
-.Bd -literal
- struct { uint8_t key[32]; } user[100];
-
- if (getrandom(NULL, 0, 0) == -1)
- err(EXIT_FAILURE, "getrandom");
- for (i = 0; i < 100; i++)
- if (getrandom(user[i].key, sizeof user[i].key,
- GRND_INSECURE) == -1)
- err(EXIT_FAILURE, "getrandom");
-.Ed
-.It
-Twiddle thumbs while waiting for entropy:
-.Bd -literal
- uint8_t secretkey[32];
-
- while (getrandom(secretkey, sizeof secretkey, GRND_NONBLOCK)
- == -1) {
- if (errno != EAGAIN)
- err(EXIT_FAILURE, "getrandom");
- twiddle_thumbs();
- }
- crypto_secretbox_xsalsa20poly1305(..., secretkey);
-.Ed
-.El
-.Pp
-(No examples of
-.Dv GRND_RANDOM
-because it is not useful.)
.Sh ERRORS
.Bl -tag -width Er
.It Bq Er EAGAIN
The
.Dv GRND_NONBLOCK
-flag was specified, and the system entropy pool does not have full
-entropy.
+flag was specified, and
+.Nm
+would have blocked waiting for entropy.
.It Bq Er EINTR
The
.Dv GRND_NONBLOCK
flag was
.Em not
-specified, the system entropy pool does not have full entropy, and the
-process was interrupted by a signal while waiting.
+specified,
+.Nm
+blocked waiting for entropy, and the process was interrupted by a
+signal.
.It Bq Er EINVAL
.Fa flags
contains an unrecognized flag or a nonsensical combination of flags.
@@ -252,20 +189,39 @@ contains an unrecognized flag or a nonse
.Fa buf
points outside the allocated address space.
.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 rnd 4
+.Xr arc4random 3 ,
+.Xr getentropy 3 ,
+.Xr rnd 4 ,
+.Xr entropy 7
+.Sh STANDARDS
+The
+.Nm
+function is a nonstandard Linux extension and will probably never be
+standardized.
.Sh HISTORY
The
.Nm
system call first appeared in Linux 3.17, and was added to
.Nx 10.0 .
-.Sh AUTHORS
-The
-.Nx
-implementation of
-.Nm
-and this man page were written by
-.An Taylor R Campbell Aq Mt riastr...@netbsd.org .
.Sh BUGS
There is no way to multiplex waiting for
.Fn getrandom
@@ -273,11 +229,16 @@ with other I/O in
.Xr select 2 ,
.Xr poll 2 ,
or
-.Xr kqueue 2 .
+.Xr kqueue 2 ,
+or to atomically unmask a set of signals while
+.Nm
+blocks.
Instead, you can wait for a read from
.Pa /dev/random ;
see
.Xr rnd 4 .
.Pp
-.Dv GRND_RANDOM
-is a little silly.
+The
+.Nm
+interface is unnecessarily complicated for no real value to
+applications, because of hysterical raisins.
