Add a version API for wolfEntropy and update dox

doc/README_DOXYGEN

@@ -128,6 +128,7 @@ are as follows but new group can be made:
     \ingroup SHA
     \ingroup SRP
     \ingroup wolfCrypt
+    \ingroup wolfEntropy
     \ingroup openSSL
     \ingroup CertManager
     \ingroup TLS

doc/dox_comments/header_files/doxygen_groups.h

@@ -335,6 +335,22 @@
     \defgroup Math Math API
     \defgroup Memory Memory Handling
     \defgroup Random Random Number Generation
+    Makes the unguessable numbers used for keys and other secrets.  It
+    takes a little true randomness from an entropy source and stretches
+    it into as much output as you ask for.
+
+    When that source is wolfEntropy, see \ref wolfEntropy.
+
+    \defgroup wolfEntropy Entropy Source - wolfEntropy (MemUse)
+    Randomness has to start somewhere.  wolfEntropy gets it by timing
+    memory reads: each one takes a slightly different, unpredictable
+    amount of time, and those tiny differences are the raw material.
+    It watches its own output and returns an error rather than hand
+    back randomness that looks broken.
+
+    Turn it on with --enable-wolfEntropy.  Most code never calls these
+    functions; the random number generator (\ref Random) does it for
+    you.
     \defgroup Signature Signature API
     \defgroup openSSL OpenSSL API
     \defgroup wolfCrypt wolfCrypt Init and Cleanup

doc/dox_comments/header_files/random.h

@@ -525,98 +525,6 @@ int wc_RNG_HealthTest_ex(int reseed, const byte* nonce, word32 nonceSz,
                         const byte* seedB, word32 seedBSz, byte* output,
                         word32 outputSz, void* heap, int devId);
 
-/*!
-    \ingroup Random
-    \brief Gets raw entropy without DRBG processing.
-
-    \return 0 On success
-    \return BAD_FUNC_ARG If raw is NULL
-    \return RNG_FAILURE_E Failed
-
-    \param raw Buffer for entropy
-    \param cnt Bytes to retrieve
-
-    _Example_
-    \code
-    byte raw[32];
-    int ret = wc_Entropy_GetRawEntropy(raw, sizeof(raw));
-    \endcode
-
-    \sa wc_Entropy_Get
-*/
-int wc_Entropy_GetRawEntropy(unsigned char* raw, int cnt);
-
-/*!
-    \ingroup Random
-    \brief Gets processed entropy with specified bits.
-
-    \return 0 On success
-    \return BAD_FUNC_ARG If entropy is NULL
-    \return RNG_FAILURE_E Failed
-
-    \param bits Entropy bits required
-    \param entropy Buffer for entropy
-    \param len Buffer size
-
-    _Example_
-    \code
-    byte entropy[32];
-    int ret = wc_Entropy_Get(256, entropy, sizeof(entropy));
-    \endcode
-
-    \sa wc_Entropy_GetRawEntropy
-
-    \par Supplying your own counter
-    The entropy source samples a high resolution counter for timing jitter.
-    CUSTOM_ENTROPY_TIMEHIRES overrides which counter it uses.  It is a build
-    time macro, not a runtime callback: define it to the name of a function
-    returning word64.  Requires HAVE_ENTROPY_MEMUSE (--enable-wolfEntropy).
-
-    Without it, wolfentropy.c picks a counter in this order: a per platform
-    hardware counter if it has one for the target, otherwise a counter thread
-    when ENTROPY_MEMUSE_THREAD is set, otherwise the build fails.  A custom
-    counter is checked before all of those and always wins, so on a platform
-    with no hardware counter it means the counter thread is not used at all,
-    and setting ENTROPY_MEMUSE_THREAD as well changes nothing.
-
-    The counter needs resolution, not accuracy.  It only has to advance
-    quickly, and need not be monotonic or related to wall clock time.
-
-    \code
-    // Replacing a hardware counter, on a platform that already has one.
-    // Build with -DCUSTOM_ENTROPY_TIMEHIRES=my_cycle_counter
-    word64 my_cycle_counter(void)
-    {
-        return (word64)board_read_cycle_count();
-    }
-
-    // Avoiding the counter thread, on a platform that has no hardware
-    // counter and would otherwise spin one up.
-    // Build with -DCUSTOM_ENTROPY_TIMEHIRES=my_tick
-    word64 my_tick(void)
-    {
-        return (word64)my_rtos_tick_count();
-    }
-    \endcode
-*/
-int wc_Entropy_Get(int bits, unsigned char* entropy, word32 len);
-
-/*!
-    \ingroup Random
-    \brief Tests entropy source on demand.
-
-    \return 0 On success
-    \return RNG_FAILURE_E Test failed
-
-    _Example_
-    \code
-    int ret = wc_Entropy_OnDemandTest();
-    \endcode
-
-    \sa wc_Entropy_Get
-*/
-int wc_Entropy_OnDemandTest(void);
-
 /*!
     \ingroup Random
 

doc/dox_comments/header_files/wolfentropy.h

@@ -0,0 +1,114 @@
+/*!
+    \ingroup wolfEntropy
+    \brief Gets raw entropy without DRBG processing.
+
+    \return 0 On success
+    \return BAD_FUNC_ARG If raw is NULL
+    \return RNG_FAILURE_E Failed
+
+    \param raw Buffer for entropy
+    \param cnt Bytes to retrieve
+
+    _Example_
+    \code
+    byte raw[32];
+    int ret = wc_Entropy_GetRawEntropy(raw, sizeof(raw));
+    \endcode
+
+    \sa wc_Entropy_Get
+    \sa wc_Entropy_GetVersion
+*/
+int wc_Entropy_GetRawEntropy(unsigned char* raw, int cnt);
+
+/*!
+    \ingroup wolfEntropy
+    \brief Gets processed entropy with specified bits.
+
+    \return 0 On success
+    \return BAD_FUNC_ARG If entropy is NULL
+    \return RNG_FAILURE_E Failed
+
+    \param bits Entropy bits required
+    \param entropy Buffer for entropy
+    \param len Buffer size
+
+    _Example_
+    \code
+    byte entropy[32];
+    int ret = wc_Entropy_Get(256, entropy, sizeof(entropy));
+    \endcode
+
+    \sa wc_Entropy_GetRawEntropy
+    \sa wc_Entropy_GetVersion
+
+    \par Supplying your own counter
+    The entropy source samples a high resolution counter for timing jitter.
+    CUSTOM_ENTROPY_TIMEHIRES overrides which counter it uses.  It is a build
+    time macro, not a runtime callback: define it to the name of a function
+    returning word64.  Requires HAVE_ENTROPY_MEMUSE (--enable-wolfEntropy).
+
+    Without it, wolfentropy.c picks a counter in this order: a per platform
+    hardware counter if it has one for the target, otherwise a counter thread
+    when ENTROPY_MEMUSE_THREAD is set, otherwise the build fails.  A custom
+    counter is checked before all of those and always wins, so on a platform
+    with no hardware counter it means the counter thread is not used at all,
+    and setting ENTROPY_MEMUSE_THREAD as well changes nothing.
+
+    The counter needs resolution, not accuracy.  It only has to advance
+    quickly, and need not be monotonic or related to wall clock time.
+
+    \code
+    // Replacing a hardware counter, on a platform that already has one.
+    // Build with -DCUSTOM_ENTROPY_TIMEHIRES=my_cycle_counter
+    word64 my_cycle_counter(void)
+    {
+        return (word64)board_read_cycle_count();
+    }
+
+    // Avoiding the counter thread, on a platform that has no hardware
+    // counter and would otherwise spin one up.
+    // Build with -DCUSTOM_ENTROPY_TIMEHIRES=my_tick
+    word64 my_tick(void)
+    {
+        return (word64)my_rtos_tick_count();
+    }
+    \endcode
+*/
+int wc_Entropy_Get(int bits, unsigned char* entropy, word32 len);
+
+/*!
+    \ingroup wolfEntropy
+    \brief Tests entropy source on demand.
+
+    \return 0 On success
+    \return RNG_FAILURE_E Test failed
+
+    _Example_
+    \code
+    int ret = wc_Entropy_OnDemandTest();
+    \endcode
+
+    \sa wc_Entropy_Get
+    \sa wc_Entropy_GetVersion
+*/
+int wc_Entropy_OnDemandTest(void);
+
+/*!
+    \ingroup wolfEntropy
+    \brief Tells you which version of wolfEntropy you are running.
+
+    Handy for logs and reports.  The string belongs to wolfSSL: read
+    it, do not change or free it.
+
+    \return "wolfEntropy vX.Y.Zt" Version string.  Never NULL.
+
+    _Example_
+    \code
+    printf("entropy source: %s\n", wc_Entropy_GetVersion());
+    \endcode
+
+    \sa wc_Entropy_Get
+    \sa wc_Entropy_GetRawEntropy
+    \sa wc_Entropy_OnDemandTest
+*/
+const char* wc_Entropy_GetVersion(void);

wolfcrypt/src/wolfentropy.c

@@ -1064,5 +1064,10 @@ static void Entropy_HealthTest_Reset(void)
     Entropy_HealthTest_Proportion_Reset();
 }
 
+const char* wc_Entropy_GetVersion(void)
+{
+    return "wolfEntropy v7.0.0m";
+}
+
 #endif /* HAVE_ENTROPY_MEMUSE */
 

wolfssl/wolfcrypt/wolfentropy.h

@@ -19,6 +19,10 @@
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1335, USA
  */
 
+/*!
+    \file wolfssl/wolfcrypt/wolfentropy.h
+*/
+
 #ifndef WOLFENTROPY_H
 #define WOLFENTROPY_H
 
@@ -64,6 +68,8 @@ WOLFSSL_API int wc_Entropy_OnDemandTest(void);
 WOLFSSL_LOCAL int Entropy_Init(void);
 WOLFSSL_LOCAL void Entropy_Final(void);
 
+WOLFSSL_API const char* wc_Entropy_GetVersion(void);
+
 #ifdef __cplusplus
     } /* extern "C" */
 #endif