Skip to content

wolfentropy.h

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.

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.
  • ENTROPY_RT_E or ENTROPY_APT_E on failure.
  • BAD_MUTEX_E when unable to lock mutex.
  • Negative when creating the counter thread fails.

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

Source code


int wc_Entropy_GetRawEntropy(unsigned char* raw, int cnt);

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

int wc_Entropy_OnDemandTest(void);

const char* wc_Entropy_GetVersion(void);

Updated on 2026-11-13 at 01:20:07 +0000