DRBG: clarify difference between entropy counts and buffer lengths

Unlike the NIST DRBG standard, entropy counts are in bits and
buffer lengths are in bytes. This has lead to some confusion and
errors in the past, see my comment on PR 3789.

To clarify the destinction between entropy counts and buffer lengths,
a 'len' suffix has been added to all member names of RAND_DRBG which
represent buffer lengths:

-   {min,max}_{entropy,adin,nonce,pers}
+   {min,max}_{entropy,adin,nonce,pers}len

This change makes naming also more consistent, as can be seen in the
diffs, for example:

-    else if (adinlen > drbg->max_adin) {
+    else if (adinlen > drbg->max_adinlen) {

Also replaced all 'ent's by 'entropy's, following a suggestion of Paul Dale.

Reviewed-by: Paul Dale <paul.dale@oracle.com>
Reviewed-by: Rich Salz <rsalz@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/4266)

3 files changed, 56 insertions, 40 deletions

diff --git a/crypto/rand/drbg_lib.c b/crypto/rand/drbg_lib.c
index 6aced40fd4..0560e3baa7 100644
--- a/crypto/rand/drbg_lib.c
+++ b/crypto/rand/drbg_lib.c
@@ -125,9 +125,9 @@ int RAND_DRBG_instantiate(RAND_DRBG *drbg,
                           const unsigned char *pers, size_t perslen)
 {
     unsigned char *nonce = NULL, *entropy = NULL;
-    size_t noncelen = 0, entlen = 0;
+    size_t noncelen = 0, entropylen = 0;
 
-    if (perslen > drbg->max_pers) {
+    if (perslen > drbg->max_perslen) {
         RANDerr(RAND_F_RAND_DRBG_INSTANTIATE,
                 RAND_R_PERSONALISATION_STRING_TOO_LONG);
         goto end;
@@ -141,23 +141,23 @@ int RAND_DRBG_instantiate(RAND_DRBG *drbg,
 
     drbg->state = DRBG_ERROR;
     if (drbg->get_entropy != NULL)
-        entlen = drbg->get_entropy(drbg, &entropy, drbg->strength,
-                                   drbg->min_entropy, drbg->max_entropy);
-    if (entlen < drbg->min_entropy || entlen > drbg->max_entropy) {
+        entropylen = drbg->get_entropy(drbg, &entropy, drbg->strength,
+                                   drbg->min_entropylen, drbg->max_entropylen);
+    if (entropylen < drbg->min_entropylen || entropylen > drbg->max_entropylen) {
         RANDerr(RAND_F_RAND_DRBG_INSTANTIATE, RAND_R_ERROR_RETRIEVING_ENTROPY);
         goto end;
     }
 
-    if (drbg->max_nonce > 0 && drbg->get_nonce != NULL) {
+    if (drbg->max_noncelen > 0 && drbg->get_nonce != NULL) {
         noncelen = drbg->get_nonce(drbg, &nonce, drbg->strength / 2,
-                                   drbg->min_nonce, drbg->max_nonce);
-        if (noncelen < drbg->min_nonce || noncelen > drbg->max_nonce) {
+                                   drbg->min_noncelen, drbg->max_noncelen);
+        if (noncelen < drbg->min_noncelen || noncelen > drbg->max_noncelen) {
             RANDerr(RAND_F_RAND_DRBG_INSTANTIATE, RAND_R_ERROR_RETRIEVING_NONCE);
             goto end;
         }
     }
 
-    if (!ctr_instantiate(drbg, entropy, entlen,
+    if (!ctr_instantiate(drbg, entropy, entropylen,
                          nonce, noncelen, pers, perslen)) {
         RANDerr(RAND_F_RAND_DRBG_INSTANTIATE, RAND_R_ERROR_INSTANTIATING_DRBG);
         goto end;
@@ -195,7 +195,7 @@ int RAND_DRBG_reseed(RAND_DRBG *drbg,
                      const unsigned char *adin, size_t adinlen)
 {
     unsigned char *entropy = NULL;
-    size_t entlen = 0;
+    size_t entropylen = 0;
 
     if (drbg->state == DRBG_ERROR) {
         RANDerr(RAND_F_RAND_DRBG_RESEED, RAND_R_IN_ERROR_STATE);
@@ -208,21 +208,21 @@ int RAND_DRBG_reseed(RAND_DRBG *drbg,
 
     if (adin == NULL)
         adinlen = 0;
-    else if (adinlen > drbg->max_adin) {
+    else if (adinlen > drbg->max_adinlen) {
         RANDerr(RAND_F_RAND_DRBG_RESEED, RAND_R_ADDITIONAL_INPUT_TOO_LONG);
         return 0;
     }
 
     drbg->state = DRBG_ERROR;
     if (drbg->get_entropy != NULL)
-        entlen = drbg->get_entropy(drbg, &entropy, drbg->strength,
-                                   drbg->min_entropy, drbg->max_entropy);
-    if (entlen < drbg->min_entropy || entlen > drbg->max_entropy) {
+        entropylen = drbg->get_entropy(drbg, &entropy, drbg->strength,
+                                   drbg->min_entropylen, drbg->max_entropylen);
+    if (entropylen < drbg->min_entropylen || entropylen > drbg->max_entropylen) {
         RANDerr(RAND_F_RAND_DRBG_RESEED, RAND_R_ERROR_RETRIEVING_ENTROPY);
         goto end;
     }
 
-    if (!ctr_reseed(drbg, entropy, entlen, adin, adinlen))
+    if (!ctr_reseed(drbg, entropy, entropylen, adin, adinlen))
         goto end;
     drbg->state = DRBG_READY;
     drbg->reseed_counter = 1;
@@ -256,7 +256,7 @@ int RAND_DRBG_generate(RAND_DRBG *drbg, unsigned char *out, size_t outlen,
         RANDerr(RAND_F_RAND_DRBG_GENERATE, RAND_R_REQUEST_TOO_LARGE_FOR_DRBG);
         return 0;
     }
-    if (adinlen > drbg->max_adin) {
+    if (adinlen > drbg->max_adinlen) {
         RANDerr(RAND_F_RAND_DRBG_GENERATE, RAND_R_ADDITIONAL_INPUT_TOO_LONG);
         return 0;
     }
diff --git a/crypto/rand/drbg_rand.c b/crypto/rand/drbg_rand.c
index 934679e315..83f1ad876f 100644
--- a/crypto/rand/drbg_rand.c
+++ b/crypto/rand/drbg_rand.c
@@ -237,29 +237,29 @@ static void ctr_update(RAND_DRBG *drbg,
 }
 
 int ctr_instantiate(RAND_DRBG *drbg,
-                    const unsigned char *ent, size_t entlen,
+                    const unsigned char *entropy, size_t entropylen,
                     const unsigned char *nonce, size_t noncelen,
                     const unsigned char *pers, size_t perslen)
 {
     RAND_DRBG_CTR *ctr = &drbg->ctr;
 
-    if (ent == NULL)
+    if (entropy == NULL)
         return 0;
 
     memset(ctr->K, 0, sizeof(ctr->K));
     memset(ctr->V, 0, sizeof(ctr->V));
     AES_set_encrypt_key(ctr->K, drbg->strength, &ctr->ks);
-    ctr_update(drbg, ent, entlen, pers, perslen, nonce, noncelen);
+    ctr_update(drbg, entropy, entropylen, pers, perslen, nonce, noncelen);
     return 1;
 }
 
 int ctr_reseed(RAND_DRBG *drbg,
-               const unsigned char *ent, size_t entlen,
+               const unsigned char *entropy, size_t entropylen,
                const unsigned char *adin, size_t adinlen)
 {
-    if (ent == NULL)
+    if (entropy == NULL)
         return 0;
-    ctr_update(drbg, ent, entlen, adin, adinlen, NULL, 0);
+    ctr_update(drbg, entropy, entropylen, adin, adinlen, NULL, 0);
     return 1;
 }
 
@@ -340,20 +340,20 @@ int ctr_init(RAND_DRBG *drbg)
         /* Set key schedule for df_key */
         AES_set_encrypt_key(df_key, drbg->strength, &ctr->df_ks);
 
-        drbg->min_entropy = ctr->keylen;
-        drbg->max_entropy = DRBG_MAX_LENGTH;
-        drbg->min_nonce = drbg->min_entropy / 2;
-        drbg->max_nonce = DRBG_MAX_LENGTH;
-        drbg->max_pers = DRBG_MAX_LENGTH;
-        drbg->max_adin = DRBG_MAX_LENGTH;
+        drbg->min_entropylen = ctr->keylen;
+        drbg->max_entropylen = DRBG_MAX_LENGTH;
+        drbg->min_noncelen = drbg->min_entropylen / 2;
+        drbg->max_noncelen = DRBG_MAX_LENGTH;
+        drbg->max_perslen = DRBG_MAX_LENGTH;
+        drbg->max_adinlen = DRBG_MAX_LENGTH;
     } else {
-        drbg->min_entropy = drbg->seedlen;
-        drbg->max_entropy = drbg->seedlen;
+        drbg->min_entropylen = drbg->seedlen;
+        drbg->max_entropylen = drbg->seedlen;
         /* Nonce not used */
-        drbg->min_nonce = 0;
-        drbg->max_nonce = 0;
-        drbg->max_pers = drbg->seedlen;
-        drbg->max_adin = drbg->seedlen;
+        drbg->min_noncelen = 0;
+        drbg->max_noncelen = 0;
+        drbg->max_perslen = drbg->seedlen;
+        drbg->max_adinlen = drbg->seedlen;
     }
 
     drbg->max_request = 1 << 16;
diff --git a/crypto/rand/rand_lcl.h b/crypto/rand/rand_lcl.h
index e60f619d61..0d85934533 100644
--- a/crypto/rand/rand_lcl.h
+++ b/crypto/rand/rand_lcl.h
@@ -103,12 +103,28 @@ struct rand_drbg_st {
     int size;
     unsigned char *randomness;
 
-    /* These parameters are setup by the per-type "init" function. */
+    /* 
+     * The following parameters are setup by the per-type "init" function.
+     *
+     * Currently the only type is CTR_DRBG, its init function is ctr_init().
+     *
+     * The parameters are closely related to the ones described in 
+     * section '10.2.1 CTR_DRBG' of [NIST SP 800-90Ar1], with one
+     * crucial difference: In the NIST standard, all counts are given
+     * in bits, whereas in OpenSSL entropy counts are given in bits 
+     * and buffer lengths are given in bytes.
+     * 
+     * Since this difference has lead to some confusion in the past,
+     * (see [GitHub Issue #2443], formerly [rt.openssl.org #4055])
+     * the 'len' suffix has been added to all buffer sizes for 
+     * clarification.
+     */
+    
     int strength;
     size_t max_request;
-    size_t min_entropy, max_entropy;
-    size_t min_nonce, max_nonce;
-    size_t max_pers, max_adin;
+    size_t min_entropylen, max_entropylen;
+    size_t min_noncelen, max_noncelen;
+    size_t max_perslen, max_adinlen;
     unsigned int reseed_counter;
     unsigned int reseed_interval;
     size_t seedlen;
@@ -153,11 +169,11 @@ size_t drbg_entropy_from_system(RAND_DRBG *drbg,
 int ctr_init(RAND_DRBG *drbg);
 int ctr_uninstantiate(RAND_DRBG *drbg);
 int ctr_instantiate(RAND_DRBG *drbg,
-                    const unsigned char *ent, size_t entlen,
+                    const unsigned char *entropy, size_t entropylen,
                     const unsigned char *nonce, size_t noncelen,
                     const unsigned char *pers, size_t perslen);
 int ctr_reseed(RAND_DRBG *drbg,
-               const unsigned char *ent, size_t entlen,
+               const unsigned char *entropy, size_t entropylen,
                const unsigned char *adin, size_t adinlen);
 int ctr_generate(RAND_DRBG *drbg,
                  unsigned char *out, size_t outlen,