rng_noisesrc.h

Functions

	Name
int	wc_NoiseSrc_Init(wc_NoiseSrc * src) Validates a generic SP800-90B noise source and runs its startup test.
void	wc_NoiseSrc_Free(wc_NoiseSrc * src) Wipes the work buffer and health-test state of a noise source.
int	wc_NoiseSrc_GenerateSeed(wc_NoiseSrc * src, byte * output, word32 sz) Produces conditioned seed material from a noise source.
int	wc_NoiseSrc_GetRaw(wc_NoiseSrc * src, byte * output, word32 len, int srcIdx) Reads raw, unconditioned octets from one source of a noise source.
int	wc_NoiseSrc_SelfTest(wc_NoiseSrc * src) Liveness check on the raw noise of every source.

Functions Documentation

function wc_NoiseSrc_Init

int wc_NoiseSrc_Init(
    wc_NoiseSrc * src
)

Validates a generic SP800-90B noise source and runs its startup test.

Parameters:

src Caller-owned noise source instance.

See:

Return:

0 On success.
BAD_FUNC_ARG src is NULL, a required member is NULL, numSrc is not 1..WC_NOISE_SRC_MAX, hmin is over 100, a cutoff is below 2, aptWindow is over 512 or below aptCutoff, or startupOctets is below aptWindow.
BUFFER_E workSz is smaller than numSrc * rawPerSrc.
ENTROPY_RT_E or ENTROPY_APT_E A startup test failed; that source's state is reset and the next call retries it.
Other negative values as returned by the sample callback.

Built with WOLFSSL_NOISE_SRC (–enable-noisesrc). For parts with a raw physical noise source but no TRNG: the caller supplies a callback returning one unconditioned octet, and this layer adds the SP800-90B 4.3 startup test, the 4.4.1 Repetition Count and 4.4.2 Adaptive Proportion (sliding window) continuous tests, entropy-budget oversampling and a SHA3-256 conditioner.

Fill the configuration members of the caller-owned wc_NoiseSrc, then call this. The first call validates the configuration and derives rawPerSrc; every call runs the startup test for each source whose health-test state is empty, which after a test failure is the source that failed. The other wc_NoiseSrc_* calls invoke it first. A configuration member left zero selects a default:

Member	Default
hmin	WC_NOISE_HMIN_DEF (10, i.e. 0.1 bits per raw bit)
margin	WC_NOISE_MARGIN_DEF (1)
rctCutoff	WC_NOISE_RCT_CUTOFF_DEF (31)
aptWindow	WC_NOISE_APT_WINDOW_DEF (512, also the maximum)
aptCutoff	WC_NOISE_APT_CUTOFF_DEF (325)
startupOctets	WC_NOISE_STARTUP_DEF (1536)

With the defaults each source gathers 320 raw octets per 32-octet output chunk. Cutoffs must match the assumed hmin, or they either never trip or trip constantly.

Example

static byte work[2 * WC_NOISE_RAW_PER_SRC(50, 2)];
static wc_NoiseSrc src;

src.sampleCb      = my_sample;
src.tag           = "my-board-osc-entropy-v1";
src.work          = work;
src.workSz        = sizeof(work);
src.startupOctets = 1024;
src.numSrc        = 2;
src.hmin          = 50;
src.margin        = 2;
src.rctCutoff     = 9;
src.aptWindow     = 512;
src.aptCutoff     = 71;
ret = wc_NoiseSrc_Init(&src);

function wc_NoiseSrc_Free

void wc_NoiseSrc_Free(
    wc_NoiseSrc * src
)

Wipes the work buffer and health-test state of a noise source.

Parameters:

src Noise source instance. NULL is ignored.

See: wc_NoiseSrc_Init

Configuration members are kept, so wc_NoiseSrc_Init() can be called again on the same instance.

Example

wc_NoiseSrc_Free(&src);

function wc_NoiseSrc_GenerateSeed

int wc_NoiseSrc_GenerateSeed(
    wc_NoiseSrc * src,
    byte * output,
    word32 sz
)

Produces conditioned seed material from a noise source.

Parameters:

src Noise source instance.
output Buffer to fill.
sz Octets to produce.

See:

Return:

0 On success.
BAD_FUNC_ARG src or output is NULL.
ENTROPY_RT_E or ENTROPY_APT_E A health test failed.
MEMORY_E Allocation failed (WOLFSSL_SMALL_STACK).
Other negative values from wc_NoiseSrc_Init(), the sample callback or SHA3-256.

Per 32-octet chunk, gathers rawPerSrc octets from every source, health-tests them, and hashes tag, a big-endian chunk counter and each source's octets in index order with SHA3-256. Only source 0 is credited with entropy; further sources are hashed in as defence in depth.

On any failure the whole output buffer is wiped. A health-test failure on any source resets that source's test state, so the next call reruns its startup test.

Example

byte seed[48];
ret = wc_NoiseSrc_GenerateSeed(&src, seed, sizeof(seed));

function wc_NoiseSrc_GetRaw

int wc_NoiseSrc_GetRaw(
    wc_NoiseSrc * src,
    byte * output,
    word32 len,
    int srcIdx
)

Reads raw, unconditioned octets from one source of a noise source.

Parameters:

src Noise source instance.
output Buffer to fill.
len Octets to read.
srcIdx Source index, 0 .. numSrc - 1.

See: wc_NoiseSrc_GenerateSeed

Return:

0 On success.
BAD_FUNC_ARG src or output is NULL, or srcIdx is out of range.
Other negative values from wc_NoiseSrc_Init() or the sample callback; output is wiped on a callback error.

For characterization and self-test only: no health tests run on these octets, so they are not fit for keying material, and they do not advance the continuous-test state.

Example

byte raw[4096];
ret = wc_NoiseSrc_GetRaw(&src, raw, sizeof(raw), 0);

function wc_NoiseSrc_SelfTest

int wc_NoiseSrc_SelfTest(
    wc_NoiseSrc * src
)

Liveness check on the raw noise of every source.

Parameters:

src Noise source instance.

See: wc_NoiseSrc_GenerateSeed

Return:

0 On success.
ENTROPY_RT_E A source failed the check.
BUFFER_E The work buffer is too small for two gathers.
Other negative values from wc_NoiseSrc_Init() or the sample callback.

Each source must produce two differing gathers, and a gather must not be one repeated octet. A source that fails has its health-test state reset, so the next call reruns its startup test.

Example

ret = wc_NoiseSrc_SelfTest(&src);

Source code


int wc_NoiseSrc_Init(wc_NoiseSrc* src);

void wc_NoiseSrc_Free(wc_NoiseSrc* src);

int wc_NoiseSrc_GenerateSeed(wc_NoiseSrc* src, byte* output, word32 sz);

int wc_NoiseSrc_GetRaw(wc_NoiseSrc* src, byte* output, word32 len,
    int srcIdx);

int wc_NoiseSrc_SelfTest(wc_NoiseSrc* src);

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