lib:util: Add better documentation for generate_secret_buffer()

Signed-off-by: Andreas Schneider <asn@samba.org>
Reviewed-by: Andrew Bartlett <abartlet@samba.org>

diff --git a/lib/util/genrand.c b/lib/util/genrand.c
index 76c2cb81962f21b8f0d7fb075760c3fd77b44c1c..a5809aa2bc952e7a80908b4d140350d0febd4844 100644 (file)
--- a/lib/util/genrand.c
+++ b/lib/util/genrand.c
@@ -25,19 +25,26 @@
 #include <gnutls/gnutls.h>
 #include <gnutls/crypto.h>
 
+/*
+ * Details about the GnuTLS CSPRNG:
+ *
+ * https://nikmav.blogspot.com/2017/03/improving-by-simplifying-gnutls-prng.html
+ */
+
 _PUBLIC_ void generate_random_buffer(uint8_t *out, int len)
 {
        /* Thread and fork safe random number generator for temporary keys. */
        gnutls_rnd(GNUTLS_RND_RANDOM, out, len);
 }
 
-/*
- * Keep generate_secret_buffer in case we ever want to do something
- * different
- */
 _PUBLIC_ void generate_secret_buffer(uint8_t *out, int len)
 {
-       /* Thread and fork safe 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
+        * from the OS random device with the previous key.
+        */
        gnutls_rnd(GNUTLS_RND_KEY, out, len);
 }
 

diff --git a/lib/util/genrand.h b/lib/util/genrand.h
index 5af2310059647391d3e78ed59894b4ece89065ae..abb8ce2c10a23a2fff2fc013a49c430705fd2afb 100644 (file)
--- a/lib/util/genrand.h
+++ b/lib/util/genrand.h
@@ -25,7 +25,11 @@
 void generate_random_buffer(uint8_t *out, int len);
 
 /**
- * Thread and fork safe random number generator for long term keys.
+ * @brief Generate random values for key buffers (e.g. session 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_secret_buffer(uint8_t *out, int len);