doc: improve randomness discussion

Inspired by comments from Jeffrey Walton in:
https://lists.gnu.org/r/bug-gnulib/2020-06/msg00002.html
* doc/glibc-functions/getentropy.texi (getentropy):
* doc/glibc-functions/getrandom.texi (getrandom):
Improve discussion of problems with "random" data,
and cite Ristenpart & Yilek.  Also, mention GRND_INSECURE.

diff --git a/ChangeLog b/ChangeLog
index 24485893a9f33a927e27f7ec01ffcfb12e6f564c..04bbcd752afcc3eac2969a221f1b55544ad4da6b 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,13 @@
+2020-06-01  Paul Eggert  <eggert@cs.ucla.edu>
+
+       doc: improve randomness discussion
+       Inspired by comments from Jeffrey Walton in:
+       https://lists.gnu.org/r/bug-gnulib/2020-06/msg00002.html
+       * doc/glibc-functions/getentropy.texi (getentropy):
+       * doc/glibc-functions/getrandom.texi (getrandom):
+       Improve discussion of problems with "random" data,
+       and cite Ristenpart & Yilek.  Also, mention GRND_INSECURE.
+
 2020-06-01  Bruno Haible  <bruno@clisp.org>
 
        doc: Fix Texinfo syntax error.

diff --git a/doc/glibc-functions/getentropy.texi b/doc/glibc-functions/getentropy.texi
index 998bcf46d68e65d4104e93aed2d35a333be616d3..c9884ad24f3e8cf24c522bc95be6b24b256b0f1c 100644 (file)
--- a/doc/glibc-functions/getentropy.texi
+++ b/doc/glibc-functions/getentropy.texi
@@ -32,8 +32,12 @@ Portability problems not fixed by Gnulib:
 @itemize
 @end itemize
 
-Note: This function does not provides high-quality random numbers, as needed
-by some crypto applications.  If you want such high-quality random numbers,
-use the function @code{getrandom} with the @code{GRND_RANDOM} flag or (better)
-use the @samp{crypto/gc-random} module and configure with
-@samp{--with-libgcrypt}.
+@noindent
+Although this function is intended to produce random data, the data's
+security properties may not be appropriate for your application.
+For example, identical ``random'' data streams might be produced by
+rebooted virtual machines.  If this is of concern you may need to use
+additional techniques such as hedging.@footnote{Ristenpart T, Yilek
+S@. @url{http://pages.cs.wisc.edu/~rist/papers/sslhedge.pdf, When good
+randomness goes bad: virtual machine vulnerabilities and hedging
+deployed cryptography}. NDSS 2010.}

diff --git a/doc/glibc-functions/getrandom.texi b/doc/glibc-functions/getrandom.texi
index 07d05a745ec95c395575c76ce22b9757835e23aa..f3a20a09d0345d70a4dc9490f4957b7ad779803c 100644 (file)
--- a/doc/glibc-functions/getrandom.texi
+++ b/doc/glibc-functions/getrandom.texi
@@ -30,12 +30,22 @@ Solaris 11.4.
 Portability problems not fixed by Gnulib:
 @itemize
 @item
-This function cannot produce truly random numbers, even when the
-@code{GRND_RANDOM} flag is given, on some platforms:
-GNU/Hurd, Mac OS X, GNU/kFreeBSD, FreeBSD 12.0, OpenBSD 6.5, Minix 3.3, AIX 7.1, Haiku, mingw, MSVC 14.
+The @code{GRND_INSECURE} flag is missing on some platforms:
+glibc 2.31, macOS 10.15, GNU/kFreeBSD, FreeBSD 12.0, OpenBSD 6.5,
+Minix 3.3, Haiku.
+
+@item
+The @code{GRND_RANDOM} flag has different effects on different platforms.
+Some platforms ignore the flag, or yield data that can fail to be
+random in some cases.
 @end itemize
 
-Note: This function does not provides high-quality random numbers, as needed
-by some crypto applications, even when the @code{GRND_RANDOM} flag is given.
-If you want such high-quality random numbers, use the @samp{crypto/gc-random}
-module and configure with @samp{--with-libgcrypt}.
+@noindent
+Although this function is intended to produce random data, the data's
+security properties may not be appropriate for your application.
+For example, identical ``random'' data streams might be produced by
+rebooted virtual machines.  If this is of concern you may need to use
+additional techniques such as hedging.@footnote{Ristenpart T, Yilek
+S@. @url{http://pages.cs.wisc.edu/~rist/papers/sslhedge.pdf, When good
+randomness goes bad: virtual machine vulnerabilities and hedging
+deployed cryptography}. NDSS 2010.}