diff options
author | Rich Salz <rsalz@openssl.org> | 2017-06-26 12:02:57 -0400 |
---|---|---|
committer | Rich Salz <rsalz@openssl.org> | 2017-06-27 12:14:49 -0400 |
commit | f367ac2b2664df272aa1903c7650f0c64f539d28 (patch) | |
tree | 654388ca91eb1a89173546d83bc413322f706e8f /doc | |
parent | c91ec013654e97ca1754db26bd2da62c8bbf7b47 (diff) |
Use randomness not entropy
Reviewed-by: Ben Kaduk <kaduk@mit.edu>
(Merged from https://github.com/openssl/openssl/pull/3773)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/man3/OPENSSL_instrument_bus.pod | 2 | ||||
-rw-r--r-- | doc/man3/RAND_add.pod | 14 | ||||
-rw-r--r-- | doc/man3/RAND_bytes.pod | 3 | ||||
-rw-r--r-- | doc/man3/RAND_egd.pod | 20 | ||||
-rw-r--r-- | doc/man3/RAND_set_rand_method.pod | 2 |
5 files changed, 19 insertions, 22 deletions
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; |