Skip to content

Entropy Source - wolfEntropy (MemUse)

More...

Functions

Name
int wc_Entropy_GetRawEntropy(unsigned char * raw, int cnt)
Gets raw entropy without DRBG processing.
int wc_Entropy_Get(int bits, unsigned char * entropy, word32 len)
Gets processed entropy with specified bits.
int wc_Entropy_OnDemandTest(void )
Tests entropy source on demand.
const char * wc_Entropy_GetVersion(void )
Tells you which version of wolfEntropy you are running.

Detailed Description

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 (Random Number Generation) does it for you.

Functions Documentation

function wc_Entropy_GetRawEntropy

int wc_Entropy_GetRawEntropy(
    unsigned char * raw,
    int cnt
)

Gets raw entropy without DRBG processing.

Parameters:

  • raw Buffer for entropy
  • cnt Bytes to retrieve

See:

Return:

  • 0 On success
  • BAD_FUNC_ARG If raw is NULL
  • RNG_FAILURE_E Failed

Example

byte raw[32];
int ret = wc_Entropy_GetRawEntropy(raw, sizeof(raw));

function wc_Entropy_Get

int wc_Entropy_Get(
    int bits,
    unsigned char * entropy,
    word32 len
)

Gets processed entropy with specified bits.

Parameters:

  • bits Entropy bits required
  • entropy Buffer for entropy
  • len Buffer size

See:

Return:

  • 0 On success
  • BAD_FUNC_ARG If entropy is NULL
  • RNG_FAILURE_E Failed

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).

Example

byte entropy[32];
int ret = wc_Entropy_Get(256, entropy, sizeof(entropy));

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.

// 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();
}

function wc_Entropy_OnDemandTest

int wc_Entropy_OnDemandTest(
    void 
)

Tests entropy source on demand.

See:

Return:

  • 0 On success
  • RNG_FAILURE_E Test failed

Example

int ret = wc_Entropy_OnDemandTest();

function wc_Entropy_GetVersion

const char * wc_Entropy_GetVersion(
    void 
)

Tells you which version of wolfEntropy you are running.

See:

Return: "wolfEntropy vX.Y.Zt" Version string. Never NULL.

Handy for logs and reports. The string belongs to wolfSSL: read it, do not change or free it.

Example

printf("entropy source: %s\n", wc_Entropy_GetVersion());

Updated on 2026-09-17 at 01:17:40 +0000