Use randomness not entropy

Reviewed-by: Ben Kaduk <kaduk@mit.edu>
(Merged from https://github.com/openssl/openssl/pull/3773)

16 files changed, 37 insertions, 42 deletions

diff --git a/apps/app_rand.c b/apps/app_rand.c
index 8a85cc9114..21445ac0f9 100644
--- a/apps/app_rand.c
+++ b/apps/app_rand.c
@@ -93,13 +93,14 @@ int app_RAND_write_file(const char *file)
 {
     char buffer[200];
 
-    if (egdsocket || !seeded)
+    if (egdsocket || !seeded) {
         /*
-         * If we did not manage to read the seed file, we should not write a
-         * low-entropy seed file back -- it would suppress a crucial warning
-         * the next time we want to use it.
+         * If we didn't manage to read the seed file, don't write a
+         * file out -- it would suppress a crucial warning the next
+         * time we want to use it.
          */
         return 0;
+    }
 
     if (file == NULL)
         file = RAND_file_name(buffer, sizeof buffer);
diff --git a/apps/speed.c b/apps/speed.c
index c2787a0ecc..bd32786014 100644
--- a/apps/speed.c
+++ b/apps/speed.c
@@ -249,7 +249,7 @@ static double ecdh_results[EC_NUM][1];
 
 #if !defined(OPENSSL_NO_DSA) || !defined(OPENSSL_NO_EC)
 static const char rnd_seed[] =
-    "string to make the random number generator think it has entropy";
+    "string to make the random number generator think it has randomness";
 #endif
 
 #ifdef SIGALRM
diff --git a/doc/man3/OPENSSL_instrument_bus.pod b/doc/man3/OPENSSL_instrument_bus.pod
index 1407261035..b031c4d88e 100644
--- a/doc/man3/OPENSSL_instrument_bus.pod
+++ b/doc/man3/OPENSSL_instrument_bus.pod
@@ -16,7 +16,7 @@ OPENSSL_instrument_bus, OPENSSL_instrument_bus2 - instrument references to memor
 It was empirically found that timings of references to primary memory
 are subject to irregular, apparently non-deterministic variations. The
 subroutines in question instrument these references for purposes of
-gathering entropy for random number generator. In order to make it
+gathering randomness for random number generator. In order to make it
 bus-bound a 'flush cache line' instruction is used between probes. In
 addition probes are added to B<vector> elements in atomic or
 interlocked manner, which should contribute additional noise on
diff --git a/doc/man3/RAND_add.pod b/doc/man3/RAND_add.pod
index 62ff79444a..c62d1407e7 100644
--- a/doc/man3/RAND_add.pod
+++ b/doc/man3/RAND_add.pod
@@ -3,7 +3,7 @@
 =head1 NAME
 
 RAND_add, RAND_seed, RAND_status, RAND_event, RAND_screen - add
-entropy to the PRNG
+randomness to the PRNG
 
 =head1 SYNOPSIS
 
@@ -11,7 +11,7 @@ entropy to the PRNG
 
  void RAND_seed(const void *buf, int num);
 
- void RAND_add(const void *buf, int num, double entropy);
+ void RAND_add(const void *buf, int num, double randomness);
 
  int  RAND_status(void);
 
@@ -27,10 +27,10 @@ if the data at B<buf> are unpredictable to an adversary, this
 increases the uncertainty about the state and makes the PRNG output
 less predictable. Suitable input comes from user interaction (random
 key presses, mouse movements) and certain hardware events. The
-B<entropy> argument is (the lower bound of) an estimate of how much
-randomness is contained in B<buf>, measured in bytes. Details about
-sources of randomness and how to estimate their entropy can be found
-in the literature, e.g. RFC 1750.
+B<randomness> argument is an estimate of how much randomness is contained in
+B<buf>, in bytes, and should be a number between zero and B<num>.
+Details about sources of randomness and how to estimate their randomness
+can be found in the literature; for example IETF RFC 4086.
 
 RAND_add() may be called with sensitive data such as user entered
 passwords. The seed values cannot be recovered from the PRNG output.
@@ -42,7 +42,7 @@ application is responsible for seeding the PRNG by calling RAND_add(),
 L<RAND_egd(3)>
 or L<RAND_load_file(3)>.
 
-RAND_seed() is equivalent to RAND_add() when B<num == entropy>.
+RAND_seed() is equivalent to RAND_add() with B<randomness> set to B<num>.
 
 RAND_event() and RAND_screen() are deprecated and should not be called.
 
diff --git a/doc/man3/RAND_bytes.pod b/doc/man3/RAND_bytes.pod
index 58aa962572..9c2f9e19a6 100644
--- a/doc/man3/RAND_bytes.pod
+++ b/doc/man3/RAND_bytes.pod
@@ -24,9 +24,6 @@ enough randomness to ensure an unpredictable byte sequence.
 
 RAND_pseudo_bytes() has been deprecated; use RAND_bytes() instead.
 
-The contents of B<buf> is mixed into the entropy pool before retrieving
-the new pseudo-random bytes unless disabled at compile time (see FAQ).
-
 =head1 RETURN VALUES
 
 RAND_bytes() returns 1 on success, -1 if not supported by the current
diff --git a/doc/man3/RAND_egd.pod b/doc/man3/RAND_egd.pod
index 1dc1321eae..956362dff2 100644
--- a/doc/man3/RAND_egd.pod
+++ b/doc/man3/RAND_egd.pod
@@ -15,18 +15,18 @@ RAND_egd, RAND_egd_bytes, RAND_query_egd_bytes - query entropy gathering daemon
 
 =head1 DESCRIPTION
 
-RAND_egd() queries the entropy gathering daemon EGD on socket B<path>.
+RAND_egd() queries the Entropy Gathering Daemon (EGD) on socket B<path>.
 It queries 255 bytes and uses L<RAND_add(3)> to seed the
 OpenSSL built-in PRNG. RAND_egd(path) is a wrapper for
 RAND_egd_bytes(path, 255);
 
-RAND_egd_bytes() queries the entropy gathering daemon EGD on socket B<path>.
+RAND_egd_bytes() queries EGD on socket B<path>.
 It queries B<bytes> bytes and uses L<RAND_add(3)> to seed the
 OpenSSL built-in PRNG.
 This function is more flexible than RAND_egd().
 When only one secret key must
 be generated, it is not necessary to request the full amount 255 bytes from
-the EGD socket. This can be advantageous, since the amount of entropy
+the EGD socket. This can be advantageous, since the amount of randomness
 that can be retrieved from EGD over time is limited.
 
 RAND_query_egd_bytes() performs the actual query of the EGD daemon on socket
@@ -36,28 +36,28 @@ OpenSSL built-in PRNG using L<RAND_add(3)>.
 
 =head1 NOTES
 
-On systems without /dev/*random devices providing entropy from the kernel,
-the EGD entropy gathering daemon can be used to collect entropy. It provides
-a socket interface through which entropy can be gathered in chunks up to
+On systems without /dev/*random devices providing randomness from the kernel,
+EGD provides
+a socket interface through which randomness can be gathered in chunks up to
 255 bytes. Several chunks can be queried during one connection.
 
 EGD is available from http://www.lothar.com/tech/crypto/ (C<perl
 Makefile.PL; make; make install> to install). It is run as B<egd>
 I<path>, where I<path> is an absolute path designating a socket. When
 RAND_egd() is called with that path as an argument, it tries to read
-random bytes that EGD has collected. RAND_egd() retrieves entropy from the
+random bytes that EGD has collected. RAND_egd() retrieves randomness from the
 daemon using the daemon's "non-blocking read" command which shall
 be answered immediately by the daemon without waiting for additional
-entropy to be collected. The write and read socket operations in the
+randomness to be collected. The write and read socket operations in the
 communication are blocking.
 
 Alternatively, the EGD-interface compatible daemon PRNGD can be used. It is
 available from
 http://prngd.sourceforge.net/ .
 PRNGD does employ an internal PRNG itself and can therefore never run
-out of entropy.
+out of randomness.
 
-OpenSSL automatically queries EGD when entropy is requested via RAND_bytes()
+OpenSSL automatically queries EGD when randomness is requested via RAND_bytes()
 or the status is checked via RAND_status() for the first time, if the socket
 is located at /var/run/egd-pool, /dev/egd-pool or /etc/egd-pool.
 
diff --git a/doc/man3/RAND_set_rand_method.pod b/doc/man3/RAND_set_rand_method.pod
index 7ebb72c1b3..12075d252a 100644
--- a/doc/man3/RAND_set_rand_method.pod
+++ b/doc/man3/RAND_set_rand_method.pod
@@ -40,7 +40,7 @@ API is being used, so this function is no longer recommended.
      void (*seed)(const void *buf, int num);
      int (*bytes)(unsigned char *buf, int num);
      void (*cleanup)(void);
-     void (*add)(const void *buf, int num, int entropy);
+     void (*add)(const void *buf, int num, int randomness);
      int (*pseudorand)(unsigned char *buf, int num);
      int (*status)(void);
  } RAND_METHOD;
diff --git a/e_os.h b/e_os.h
index d331044ead..7138c7a181 100644
--- a/e_os.h
+++ b/e_os.h
@@ -75,7 +75,7 @@ extern "C" {
 
 # ifndef DEVRANDOM
 /*
- * set this to a comma-separated list of 'random' device files to try out. My
+ * set this to a comma-separated list of 'random' device files to try out. By
  * default, we will try to read at least one of these files
  */
 #  define DEVRANDOM "/dev/urandom","/dev/random","/dev/srandom"
@@ -84,7 +84,7 @@ extern "C" {
 /*
  * set this to a comma-separated list of 'egd' sockets to try out. These
  * sockets will be tried in the order listed in case accessing the device
- * files listed in DEVRANDOM did not return enough entropy.
+ * files listed in DEVRANDOM did not return enough randomness.
  */
 #  define DEVRANDOM_EGD "/var/run/egd-pool","/dev/egd-pool","/etc/egd-pool","/etc/entropy"
 # endif
diff --git a/include/openssl/rand.h b/include/openssl/rand.h
index 157d1ef916..5cda71b792 100644
--- a/include/openssl/rand.h
+++ b/include/openssl/rand.h
@@ -19,14 +19,11 @@
 extern "C" {
 #endif
 
-/* Already defined in ossl_typ.h */
-/* typedef struct rand_meth_st RAND_METHOD; */
-
 struct rand_meth_st {
     int (*seed) (const void *buf, int num);
     int (*bytes) (unsigned char *buf, int num);
     void (*cleanup) (void);
-    int (*add) (const void *buf, int num, double entropy);
+    int (*add) (const void *buf, int num, double randomness);
     int (*pseudorand) (unsigned char *buf, int num);
     int (*status) (void);
 };
@@ -50,7 +47,7 @@ void RAND_seed(const void *buf, int num);
 #if defined(__ANDROID__) && defined(__NDK_FPABI__)
 __NDK_FPABI__	/* __attribute__((pcs("aapcs"))) on ARM */
 #endif
-void RAND_add(const void *buf, int num, double entropy);
+void RAND_add(const void *buf, int num, double randomness);
 int RAND_load_file(const char *file, long max_bytes);
 int RAND_write_file(const char *file);
 const char *RAND_file_name(char *file, size_t num);
diff --git a/test/dhtest.c b/test/dhtest.c
index 618b84e773..303f40fd53 100644
--- a/test/dhtest.c
+++ b/test/dhtest.c
@@ -31,7 +31,7 @@ int main(int argc, char *argv[])
 static int cb(int p, int n, BN_GENCB *arg);
 
 static const char rnd_seed[] =
-    "string to make the random number generator think it has entropy";
+    "string to make the random number generator think it has randomness";
 
 static int dh_test(void)
 {
diff --git a/test/dsatest.c b/test/dsatest.c
index 579e57c382..9c5afa3c46 100644
--- a/test/dsatest.c
+++ b/test/dsatest.c
@@ -64,7 +64,7 @@ static unsigned char out_g[] = {
 static const unsigned char str1[] = "12345678901234567890";
 
 static const char rnd_seed[] =
-    "string to make the random number generator think it has entropy";
+    "string to make the random number generator think it has randomness";
 
 static int dsa_test(void)
 {
diff --git a/test/ecdsatest.c b/test/ecdsatest.c
index 841934e51c..8a245b5d74 100644
--- a/test/ecdsatest.c
+++ b/test/ecdsatest.c
@@ -28,8 +28,8 @@
 # include <openssl/rand.h>
 # include "testutil.h"
 
-static const char rnd_seed[] = "string to make the random number generator "
-    "think it has entropy";
+static const char rnd_seed[] =
+    "string to make the random number generator think it has randomness";
 
 
 /* functions to change the RAND_METHOD */
diff --git a/test/ectest.c b/test/ectest.c
index 84e0997169..351fefd994 100644
--- a/test/ectest.c
+++ b/test/ectest.c
@@ -1427,7 +1427,7 @@ static int parameter_test(void)
 }
 
 static const char rnd_seed[] =
-    "string to make the random number generator think it has entropy";
+    "string to make the random number generator think it has randomness";
 #endif
 
 int test_main(int argc, char *argv[])
diff --git a/test/recipes/25-test_req.t b/test/recipes/25-test_req.t
index bcc10257d4..82b9bf8aec 100644
--- a/test/recipes/25-test_req.t
+++ b/test/recipes/25-test_req.t
@@ -20,7 +20,7 @@ plan tests => 4;
 require_ok(srctop_file('test','recipes','tconversion.pl'));
 
 open RND, ">>", ".rnd";
-print RND "string to make the random number generator think it has entropy";
+print RND "string to make the random number generator think it has randomness";
 close RND;
 subtest "generating certificate requests" => sub {
     my @req_new;
diff --git a/test/recipes/80-test_ssl_old.t b/test/recipes/80-test_ssl_old.t
index 501009384a..ea7623125c 100644
--- a/test/recipes/80-test_ssl_old.t
+++ b/test/recipes/80-test_ssl_old.t
@@ -101,7 +101,7 @@ testssl("keyU.ss", $Ucert, $CAcert);
 # subtest functions
 sub testss {
     open RND, ">>", ".rnd";
-    print RND "string to make the random number generator think it has entropy";
+    print RND "string to make the random number generator think it has randomness";
     close RND;
 
     my @req_dsa = ("-newkey",
diff --git a/test/ssltest_old.c b/test/ssltest_old.c
index 01cf4f1134..acadb669d2 100644
--- a/test/ssltest_old.c
+++ b/test/ssltest_old.c
@@ -614,7 +614,7 @@ static char *cipher = NULL;
 static int verbose = 0;
 static int debug = 0;
 static const char rnd_seed[] =
-    "string to make the random number generator think it has entropy";
+    "string to make the random number generator think it has randomness";
 
 int doit_localhost(SSL *s_ssl, SSL *c_ssl, int family,
                    long bytes, clock_t *s_time, clock_t *c_time);