From e617424098c0163a776f0d07e1787526c62bfe5f Mon Sep 17 00:00:00 2001 From: kaleb-himes Date: Thu, 10 Sep 2026 11:48:34 -0600 Subject: [PATCH] Add a version API for wolfEntropy and update dox --- doc/README_DOXYGEN | 1 + .../header_files/doxygen_groups.h | 16 +++ doc/dox_comments/header_files/random.h | 92 -------------- doc/dox_comments/header_files/wolfentropy.h | 114 ++++++++++++++++++ wolfcrypt/src/wolfentropy.c | 5 + wolfssl/wolfcrypt/wolfentropy.h | 6 + 6 files changed, 142 insertions(+), 92 deletions(-) create mode 100644 doc/dox_comments/header_files/wolfentropy.h diff --git a/doc/README_DOXYGEN b/doc/README_DOXYGEN index 5415d941c00..b71f1926c86 100644 --- a/doc/README_DOXYGEN +++ b/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 diff --git a/doc/dox_comments/header_files/doxygen_groups.h b/doc/dox_comments/header_files/doxygen_groups.h index 4db1423b303..35385763593 100644 --- a/doc/dox_comments/header_files/doxygen_groups.h +++ b/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 diff --git a/doc/dox_comments/header_files/random.h b/doc/dox_comments/header_files/random.h index b07b2a2e6c3..b5cac51e509 100644 --- a/doc/dox_comments/header_files/random.h +++ b/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 diff --git a/doc/dox_comments/header_files/wolfentropy.h b/doc/dox_comments/header_files/wolfentropy.h new file mode 100644 index 00000000000..570ed01e318 --- /dev/null +++ b/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); diff --git a/wolfcrypt/src/wolfentropy.c b/wolfcrypt/src/wolfentropy.c index 569c3ab0a77..3932d652247 100644 --- a/wolfcrypt/src/wolfentropy.c +++ b/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 */ diff --git a/wolfssl/wolfcrypt/wolfentropy.h b/wolfssl/wolfcrypt/wolfentropy.h index fc2961b17d3..e1ea85aad87 100644 --- a/wolfssl/wolfcrypt/wolfentropy.h +++ b/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