From f7bef277eac05853224d33e67465147833c49108 Mon Sep 17 00:00:00 2001 From: "Dr. Matthias St. Pierre" Date: Fri, 30 Mar 2018 01:07:00 +0200 Subject: [PATCH] Minor corrections for the RAND_DRBG API documentation - added some explaining text to a sentence that lost its context. - removed mention of per-ssl drbg - fix whitespace errors Reviewed-by: Rich Salz (Merged from https://github.com/openssl/openssl/pull/5804) --- doc/man3/RAND_DRBG_set_callbacks.pod | 2 +- doc/man7/RAND.pod | 4 ++-- doc/man7/RAND_DRBG.pod | 17 +++++++++-------- 3 files changed, 12 insertions(+), 11 deletions(-) diff --git a/doc/man3/RAND_DRBG_set_callbacks.pod b/doc/man3/RAND_DRBG_set_callbacks.pod index 3e9a98585e..a927d6a7da 100644 --- a/doc/man3/RAND_DRBG_set_callbacks.pod +++ b/doc/man3/RAND_DRBG_set_callbacks.pod @@ -79,7 +79,7 @@ See NOTES section for more details. The B() callback is called from the B to to clear and free the buffer allocated previously by get_entropy(). -The values B and B are the random buffer's address and length, +The values B and B are the random buffer's address and length, as returned by the get_entropy() callback. The B() and B() callbacks are used to obtain a nonce diff --git a/doc/man7/RAND.pod b/doc/man7/RAND.pod index 6ec7548972..578018feab 100644 --- a/doc/man7/RAND.pod +++ b/doc/man7/RAND.pod @@ -32,8 +32,8 @@ return value of L and don't take randomness for granted. For long-term secrets, you can use L instead. This method does not provide 'better' randomness, it uses the same type of CSPRNG. The intention behind using a dedicated CSPRNG exclusively for long-term secrets is -that none of its output should be visible to an attacker (e.g used as salt value), -in order to reveal as little information as possible about its internal state. +that none of its output should be visible to an attacker (e.g used as salt value), +in order to reveal as little information as possible about its internal state. In the rare case where the default implementation does not satisfy your special requirements, there are two options: diff --git a/doc/man7/RAND_DRBG.pod b/doc/man7/RAND_DRBG.pod index a4c58c1889..9f7f12470c 100644 --- a/doc/man7/RAND_DRBG.pod +++ b/doc/man7/RAND_DRBG.pod @@ -37,8 +37,7 @@ Typical examples for such special use cases are the following: =item * -You want to use your own private DRBG instances, similar to how it -is currently done in the ssl library. +You want to use your own private DRBG instances. Multiple DRBG instances which are accessed only by a single thread provide additional security (because their internal states are independent) and better scalability in multithreaded applications (because they don't need @@ -80,8 +79,8 @@ the thread-local and DRBG instance, respectively. =head2 The DRBG instance The DRBG is not used directly by the application, only for reseeding -the two other two DRBG instances. It reseeds itself by obtaining randomness -either from os entropy sources or by consuming randomness which was added +the two other two DRBG instances. It reseeds itself by obtaining randomness +either from os entropy sources or by consuming randomness which was added previously by L. =head2 The DRBG instance @@ -144,10 +143,12 @@ together and are being used. +------------------+ +------------------------------------+ - -The method L is a convenience method wrapping the -L function, which serves the actual request for -random data. +The usual way to obtain random bytes is to call RAND_bytes(...) or +RAND_priv_bytes(...). These calls are roughly equivalent to calling +RAND_DRBG_bytes(, ...) and RAND_DRBG_bytes(, ...), +respectively. The method L is a convenience method +wrapping the L function, which serves the actual +request for random data. =head1 RESEEDING -- 2.25.1