From 88398d2a358fe41e33c61ac02f23ffaeacddcff0 Mon Sep 17 00:00:00 2001
From: "Dr. Matthias St. Pierre" <Matthias.St.Pierre@ncp-e.com>
Date: Mon, 2 Mar 2020 00:25:29 +0100
Subject: [PATCH] doc: document that 'openssl rand' is cryptographically secure

Reviewed-by: Paul Dale <paul.dale@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/11213)
---
 doc/man1/openssl-rand.pod.in | 14 +++++++++++---
 doc/man3/RAND_bytes.pod      | 24 ++++++++++++++++++------
 2 files changed, 29 insertions(+), 9 deletions(-)

diff --git a/doc/man1/openssl-rand.pod.in b/doc/man1/openssl-rand.pod.in
index 61c74df466..b8a01750c8 100644
--- a/doc/man1/openssl-rand.pod.in
+++ b/doc/man1/openssl-rand.pod.in
@@ -20,8 +20,14 @@ I<num>
 
 =head1 DESCRIPTION
 
-This command outputs I<num> pseudo-random bytes after seeding
-the random number generator once.
+This command generates I<num> random bytes using a cryptographically
+secure pseudo random number generator (CSPRNG).
+
+The random bytes are generated using the L<RAND_bytes(3)> function,
+which provides a security level of 256 bits, provided it managed to
+seed itself successfully from a trusted operating system entropy source.
+Otherwise, the command will fail with a non-zero error code.
+For more details, see L<RAND_bytes(3)>, L<RAND(7)>, and L<RAND_DRBG(7)>.
 
 =head1 OPTIONS
 
@@ -52,7 +58,9 @@ Show the output as a hex string.
 =head1 SEE ALSO
 
 L<openssl(1)>,
-L<RAND_bytes(3)>
+L<RAND_bytes(3)>,
+L<RAND(7)>,
+L<RAND_DRBG(7)>
 
 =head1 COPYRIGHT
 
diff --git a/doc/man3/RAND_bytes.pod b/doc/man3/RAND_bytes.pod
index 5da4692520..525b5694fe 100644
--- a/doc/man3/RAND_bytes.pod
+++ b/doc/man3/RAND_bytes.pod
@@ -23,8 +23,8 @@ L<openssl_user_macros(7)>:
 
 =head1 DESCRIPTION
 
-RAND_bytes() puts B<num> cryptographically strong pseudo-random bytes
-into B<buf>.
+RAND_bytes() generates B<num> random bytes using a cryptographically
+secure pseudo random generator (CSPRNG) and stores them in B<buf>.
 
 RAND_priv_bytes() has the same semantics as RAND_bytes().  It is intended to
 be used for generating values that should remain private. If using the
@@ -44,10 +44,22 @@ ignored.
 
 =head1 NOTES
 
-Always check the error return value of RAND_bytes() and
-RAND_priv_bytes() and do not take randomness for granted: an error occurs
-if the CSPRNG has not been seeded with enough randomness to ensure an
-unpredictable byte sequence.
+By default, the OpenSSL CSPRNG supports a security level of 256 bits, provided it
+was able to seed itself from a trusted entropy source.
+On all major platforms supported by OpenSSL (including the Unix-like platforms
+and Windows), OpenSSL is configured to automatically seed the CSPRNG on first use
+using the operating systems's random generator.
+
+If the entropy source fails or is not available, the CSPRNG will enter an
+error state and refuse to generate random bytes. For that reason, it is important
+to always check the error return value of RAND_bytes() and RAND_priv_bytes() and
+not take randomness for granted.
+
+On other platforms, there might not be a trusted entropy source available
+or OpenSSL might have been explicitly configured to use different entropy sources.
+If you are in doubt about the quality of the entropy source, don't hesitate to ask
+your operating system vendor or post a question on GitHub or the openssl-users
+mailing list.
 
 =head1 RETURN VALUES
 
-- 
2.25.1