DRBG: make locking api truly private

In PR #5295 it was decided that the locking api should remain private
and used only inside libcrypto. However, the locking functions were added
back to `libcrypto.num` by `mkdef.pl`, because the function prototypes
were still listed in `internal/rand.h`. (This header contains functions
which are internal, but shared between libcrypto and libssl.)

This commit moves the prototypes to `rand_lcl.h` and changes the names
to lowercase, following the convention therein. It also corrects an
outdated documenting comment.

Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/5375)

4 files changed, 34 insertions, 28 deletions

diff --git a/crypto/rand/drbg_lib.c b/crypto/rand/drbg_lib.c
index c592a7b9d0..c43f571d64 100644
--- a/crypto/rand/drbg_lib.c
+++ b/crypto/rand/drbg_lib.c
@@ -94,17 +94,17 @@ static RAND_DRBG *drbg_private;
  * LOCKING
  *
  * The three shared DRBGs are intended to be used concurrently, so they
- * support locking by default. It is the callers responsibility to wrap
- * calls to functions like RAND_DRBG_generate() which modify the DRBGs
- * internal state with calls to RAND_DRBG_lock() and RAND_DRBG_unlock().
- * The functions RAND_bytes() and RAND_priv_bytes() take the locks
- * automatically, so using the RAND api is thread safe as before.
- *
- * All other DRBG instances don't have locking enabled by default, because
- * they are intendended to be used by a single thread. If it is desired,
- * locking can be enabled using RAND_DRBG_enable_locking(). However, instead
- * of accessing a single DRBG instance concurrently from different threads,
- * it is recommended to instantiate a separate DRBG instance per thread.
+ * support locking. The RAND methods take the locks automatically, so using
+ * the RAND api (in particular RAND_bytes() and RAND_priv_bytes()) is
+ * thread-safe. Note however that accessing the shared DRBGs directly via
+ * the RAND_DRBG interface is *not* thread-safe.
+ *
+ * All other DRBG instances don't support locking, because they are
+ * intendended to be used by a single thread. Instead of accessing a single
+ * DRBG instance concurrently from different threads, it is recommended to
+ * instantiate a separate DRBG instance per thread. Using the same shared
+ * DRBG (preferrably the public DRBG) as parent of DRBG instances on
+ * different threads is safe.
  */
 
 
@@ -708,7 +708,7 @@ int RAND_DRBG_set_reseed_time_interval(RAND_DRBG *drbg, time_t interval)
  *
  * Returns 1 on success, 0 on failure.
  */
-int RAND_DRBG_lock(RAND_DRBG *drbg)
+int rand_drbg_lock(RAND_DRBG *drbg)
 {
     if (drbg->lock != NULL)
         return CRYPTO_THREAD_write_lock(drbg->lock);
@@ -722,7 +722,7 @@ int RAND_DRBG_lock(RAND_DRBG *drbg)
  *
  * Returns 1 on success, 0 on failure.
  */
-int RAND_DRBG_unlock(RAND_DRBG *drbg)
+int rand_drbg_unlock(RAND_DRBG *drbg)
 {
     if (drbg->lock != NULL)
         return CRYPTO_THREAD_unlock(drbg->lock);
@@ -738,7 +738,7 @@ int RAND_DRBG_unlock(RAND_DRBG *drbg)
  *
  * Returns 1 on success, 0 on failure.
  */
-int RAND_DRBG_enable_locking(RAND_DRBG *drbg)
+int rand_drbg_enable_locking(RAND_DRBG *drbg)
 {
     if (drbg->state != DRBG_UNINITIALISED) {
         RANDerr(RAND_F_RAND_DRBG_ENABLE_LOCKING,
@@ -797,7 +797,7 @@ static RAND_DRBG *drbg_setup(RAND_DRBG *parent)
     if (drbg == NULL)
         return NULL;
 
-    if (RAND_DRBG_enable_locking(drbg) == 0)
+    if (rand_drbg_enable_locking(drbg) == 0)
         goto err;
 
     if (parent == NULL) {
@@ -869,9 +869,9 @@ static int drbg_bytes(unsigned char *out, int count)
     if (drbg == NULL)
         return 0;
 
-    RAND_DRBG_lock(drbg);
+    rand_drbg_lock(drbg);
     ret = RAND_DRBG_bytes(drbg, out, count);
-    RAND_DRBG_unlock(drbg);
+    rand_drbg_unlock(drbg);
 
     return ret;
 }
@@ -898,11 +898,11 @@ static int drbg_add(const void *buf, int num, double randomness)
         return 0;
     }
 
-    RAND_DRBG_lock(drbg);
+    rand_drbg_lock(drbg);
     ret = rand_drbg_restart(drbg, buf,
                             (size_t)(unsigned int)num,
                             (size_t)(8*randomness));
-    RAND_DRBG_unlock(drbg);
+    rand_drbg_unlock(drbg);
 
     return ret;
 }
@@ -922,9 +922,9 @@ static int drbg_status(void)
     if (drbg == NULL)
         return 0;
 
-    RAND_DRBG_lock(drbg);
+    rand_drbg_lock(drbg);
     ret = drbg->state == DRBG_READY ? 1 : 0;
-    RAND_DRBG_unlock(drbg);
+    rand_drbg_unlock(drbg);
     return ret;
 }
 
diff --git a/crypto/rand/rand_err.c b/crypto/rand/rand_err.c
index e8ec44ae12..e92c33f4da 100644
--- a/crypto/rand/rand_err.c
+++ b/crypto/rand/rand_err.c
@@ -20,7 +20,7 @@ static const ERR_STRING_DATA RAND_str_functs[] = {
     {ERR_PACK(ERR_LIB_RAND, RAND_F_GET_ENTROPY, 0), "get_entropy"},
     {ERR_PACK(ERR_LIB_RAND, RAND_F_RAND_BYTES, 0), "RAND_bytes"},
     {ERR_PACK(ERR_LIB_RAND, RAND_F_RAND_DRBG_ENABLE_LOCKING, 0),
-     "RAND_DRBG_enable_locking"},
+     "rand_drbg_enable_locking"},
     {ERR_PACK(ERR_LIB_RAND, RAND_F_RAND_DRBG_GENERATE, 0),
      "RAND_DRBG_generate"},
     {ERR_PACK(ERR_LIB_RAND, RAND_F_RAND_DRBG_INSTANTIATE, 0),
diff --git a/crypto/rand/rand_lcl.h b/crypto/rand/rand_lcl.h
index a63b28be4e..ceba8bba3f 100644
--- a/crypto/rand/rand_lcl.h
+++ b/crypto/rand/rand_lcl.h
@@ -222,6 +222,12 @@ size_t rand_drbg_get_additional_data(unsigned char **pout, size_t max_len);
 int rand_drbg_restart(RAND_DRBG *drbg,
                       const unsigned char *buffer, size_t len, size_t entropy);
 
+/* locking api */
+int rand_drbg_lock(RAND_DRBG *drbg);
+int rand_drbg_unlock(RAND_DRBG *drbg);
+int rand_drbg_enable_locking(RAND_DRBG *drbg);
+
+
 /* initializes the AES-CTR DRBG implementation */
 int drbg_ctr_init(RAND_DRBG *drbg);
 
diff --git a/crypto/rand/rand_lib.c b/crypto/rand/rand_lib.c
index 289acf3039..7b8b8fcb48 100644
--- a/crypto/rand/rand_lib.c
+++ b/crypto/rand/rand_lib.c
@@ -203,13 +203,13 @@ size_t rand_drbg_get_entropy(RAND_DRBG *drbg,
              * generating bits from it. (Note: taking the lock will be a no-op
              * if locking if drbg->parent->lock == NULL.)
              */
-            RAND_DRBG_lock(drbg->parent);
+            rand_drbg_lock(drbg->parent);
             if (RAND_DRBG_generate(drbg->parent,
                                    buffer, bytes_needed,
                                    0,
                                    (unsigned char *)drbg, sizeof(*drbg)) != 0)
                 bytes = bytes_needed;
-            RAND_DRBG_unlock(drbg->parent);
+            rand_drbg_unlock(drbg->parent);
 
             entropy_available = RAND_POOL_add_end(pool, bytes, 8 * bytes);
         }
@@ -405,9 +405,9 @@ int RAND_poll(void)
         if (drbg == NULL)
             return 0;
 
-        RAND_DRBG_lock(drbg);
+        rand_drbg_lock(drbg);
         ret = rand_drbg_restart(drbg, NULL, 0, 0);
-        RAND_DRBG_unlock(drbg);
+        rand_drbg_unlock(drbg);
 
         return ret;
 
@@ -797,9 +797,9 @@ int RAND_priv_bytes(unsigned char *buf, int num)
         return 0;
 
     /* We have to lock the DRBG before generating bits from it. */
-    RAND_DRBG_lock(drbg);
+    rand_drbg_lock(drbg);
     ret = RAND_DRBG_bytes(drbg, buf, num);
-    RAND_DRBG_unlock(drbg);
+    rand_drbg_unlock(drbg);
     return ret;
 }