From 5d53f417762503b9c73edcdb1364834f3b665e74 Mon Sep 17 00:00:00 2001
From: Andreas Schneider <asn@samba.org>
Date: Mon, 12 Aug 2019 16:10:20 +0200
Subject: [PATCH 075/187] lib:util: Fix documentation for random number
 functions

Signed-off-by: Andreas Schneider <asn@samba.org>
Reviewed-by: Alexander Bokovoy <ab@samba.org>
(cherry picked from commit 97c441d7c28feb29168e81ebbc5c55b09a845087)
---
 lib/util/genrand.c | 9 +++++++--
 lib/util/genrand.h | 8 ++++++--
 2 files changed, 13 insertions(+), 4 deletions(-)

diff --git a/lib/util/genrand.c b/lib/util/genrand.c
index a5809aa2bc9..18ffa0d95e6 100644
--- a/lib/util/genrand.c
+++ b/lib/util/genrand.c
@@ -33,13 +33,16 @@
 
 _PUBLIC_ void generate_random_buffer(uint8_t *out, int len)
 {
-	/* Thread and fork safe random number generator for temporary keys. */
+	/* Random number generator for temporary keys. */
 	gnutls_rnd(GNUTLS_RND_RANDOM, out, len);
 }
 
 _PUBLIC_ void generate_secret_buffer(uint8_t *out, int len)
 {
-	/* The key generator, will re-seed after a fixed amount of bytes is
+	/*
+	 * Random number generator for long term keys.
+	 *
+	 * The key generator, will re-seed after a fixed amount of bytes is
 	 * generated (typically less than the nonce), and will also re-seed
 	 * based on time, i.e., after few hours of operation without reaching
 	 * the limit for a re-seed. For its re-seed it mixes mixes data obtained
@@ -51,6 +54,8 @@ _PUBLIC_ void generate_secret_buffer(uint8_t *out, int len)
 _PUBLIC_ void generate_nonce_buffer(uint8_t *out, int len)
 {
 	/*
+	 * Random number generator for nonce and initialization vectors.
+	 *
 	 * The nonce generator will reseed after outputting a fixed amount of
 	 * bytes (typically few megabytes), or after few hours of operation
 	 * without reaching the limit has passed.
diff --git a/lib/util/genrand.h b/lib/util/genrand.h
index abb8ce2c10a..70f36312e58 100644
--- a/lib/util/genrand.h
+++ b/lib/util/genrand.h
@@ -20,12 +20,16 @@
 */
 
 /**
- * Thread and fork safe random number generator for temporary keys.
+ * @brief Generate random values for session and temporary keys.
+ *
+ * @param[in]  out  A pointer to the buffer to fill with random data.
+ *
+ * @param[in]  len  The size of the buffer to fill.
  */
 void generate_random_buffer(uint8_t *out, int len);
 
 /**
- * @brief Generate random values for key buffers (e.g. session keys)
+ * @brief Generate random values for long term keys and passwords.
  *
  * @param[in]  out  A pointer to the buffer to fill with random data.
  *
-- 
2.23.0