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.

2 files changed, 26 insertions, 12 deletions

diff --git a/doc/glibc-functions/getentropy.texi b/doc/glibc-functions/getentropy.texi
index 998bcf46d6..c9884ad24f 100644
--- 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 07d05a745e..f3a20a09d0 100644
--- 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.}