Skip to content

random.h

Functions

Name
int wc_InitNetRandom(const char * configFile, wnr_hmac_key hmac_cb, int timeout)
Init global Whitewood netRandom context.
int wc_FreeNetRandom(void )
Free global Whitewood netRandom context.
int wc_InitRng(WC_RNG * rng)
Gets the seed (from OS) and key cipher for rng. rng_>drbg (deterministic random bit generator) allocated (should be deallocated with wc_FreeRng). This is a blocking operation.
int wc_RNG_GenerateBlock(WC_RNG * rng, byte * output, word32 sz)
Copies a sz bytes of pseudorandom data to output. Will reseed rng if needed (blocking).
int wc_RNG_GenerateByte(WC_RNG * rng, byte * b)
Calls wc_RNG_GenerateBlock to copy a byte of pseudorandom data to b. Will reseed rng if needed.
int wc_FreeRng(WC_RNG * rng)
Should be called when RNG no longer needed in order to securely free drgb. Zeros and XFREEs rng-drbg.
int wc_RNG_HealthTest(int reseed, const byte * seedA, word32 seedASz, const byte * seedB, word32 seedBSz, byte * output, word32 outputSz)
Creates and tests functionality of drbg.
int wc_GenerateSeed(OS_Seed * os, byte * output, word32 sz)
Generates seed from OS entropy source. Lower-level function used internally by wc_InitRng.
WC_RNG * wc_rng_new(byte * nonce, word32 nonceSz, void * heap)
Allocates and initializes new WC_RNG with optional nonce.
int wc_rng_new_ex(WC_RNG ** rng, byte * nonce, word32 nonceSz, void * heap, int devId)
Allocates and initializes WC_RNG with extended parameters.
void wc_rng_free(WC_RNG * rng)
Frees WC_RNG allocated with wc_rng_new.
int wc_InitRng_ex(WC_RNG * rng, void * heap, int devId)
Initializes WC_RNG with extended parameters.
int wc_InitRngNonce(WC_RNG * rng, const byte * nonce, word32 nonceSz)
Initializes WC_RNG with nonce.
int wc_InitRngNonce_ex(WC_RNG * rng, const byte * nonce, word32 nonceSz, void * heap, int devId)
Initializes WC_RNG with nonce and extended parameters.
int wc_SetSeed_Cb(wc_RngSeed_Cb cb)
Sets callback for custom seed generation.
int wc_RNG_DRBG_Reseed(WC_RNG * rng, const byte * seed, word32 seedSz)
Reseeds DRBG with new entropy.
int wc_RNG_TestSeed(const byte * seed, word32 seedSz)
Tests seed validity for DRBG.
int wc_RNG_HealthTest_ex(int reseed, const byte * nonce, word32 nonceSz, const byte * seedA, word32 seedASz, const byte * seedB, word32 seedBSz, byte * output, word32 outputSz, void * heap, int devId)
RNG health test with extended parameters.
int wc_RNG_HealthTest_SHA512(int reseed, const byte * seedA, word32 seedASz, const byte * seedB, word32 seedBSz, byte * output, word32 outputSz)
Runs the SHA_512 Hash_DRBG Known Answer Test (KAT) per SP 800-90A. Instantiates a SHA-512 DRBG with seedA, optionally reseeds with seedB, generates output, and compares against known test vectors. Available when WOLFSSL_DRBG_SHA512 is defined.
int wc_RNG_HealthTest_SHA512_ex(int reseed, const byte * nonce, word32 nonceSz, const byte * persoString, word32 persoStringSz, const byte * seedA, word32 seedASz, const byte * seedB, word32 seedBSz, const byte * additionalA, word32 additionalASz, const byte * additionalB, word32 additionalBSz, byte * output, word32 outputSz, void * heap, int devId)
Extended SHA-512 Hash_DRBG health test with nonce, personalization string, and additional input support. Suitable for full ACVP / CAVP test vector validation. Available when WOLFSSL_DRBG_SHA512 is defined.
int wc_Sha256Drbg_Disable(void )
Disables the SHA_256 Hash_DRBG at runtime. When disabled, newly initialized WC_RNG instances will not use the SHA_256 DRBG. If the SHA_512 DRBG is enabled (WOLFSSL_DRBG_SHA512), new RNG instances will use SHA-512 instead. Requires HAVE_HASHDRBG.
int wc_Sha256Drbg_Enable(void )
Re_enables the SHA_256 Hash_DRBG at runtime after a prior call to wc_Sha256Drbg_Disable(). Requires HAVE_HASHDRBG.
int wc_Sha256Drbg_IsDisabled(void )
Returns whether the SHA-256 Hash_DRBG is currently disabled. Requires HAVE_HASHDRBG.
int wc_Sha512Drbg_Disable(void )
Disables the SHA-512 Hash_DRBG at runtime. When disabled, newly initialized WC_RNG instances will not use the SHA-512 DRBG. If the SHA-256 DRBG is still enabled, new RNG instances will fall back to SHA-256. Available when WOLFSSL_DRBG_SHA512 is defined. Requires HAVE_HASHDRBG.
int wc_Sha512Drbg_Enable(void )
Re_enables the SHA_512 Hash_DRBG at runtime after a prior call to wc_Sha512Drbg_Disable(). Available when WOLFSSL_DRBG_SHA512 is defined. Requires HAVE_HASHDRBG.
int wc_Sha512Drbg_IsDisabled(void )
Returns whether the SHA-512 Hash_DRBG is currently disabled. Available when WOLFSSL_DRBG_SHA512 is defined. Requires HAVE_HASHDRBG.
int wc_InitRng_ex2(WC_RNG * rng, void * heap, int devId, word32 flags)
Initialize a WC_RNG with instantiation_time security attributes. Identical to wc_InitRng_ex(), with a flags argument fixing attributes at birth: WC_RNG_INIT_FLAG_LOCK_REQUIRED latches the sticky lock_required policy bit, so there is no reachable state in which the instance serves without its lock policy; WC_RNG_INIT_FLAG_LOCK_INITIALLY constructs into a held lease, to be released with wc_RNG_lock_put(); WC_RNG_INIT_FLAG_USE_FULL_MUTEX layers a blocking wolfSSL_Mutex outermost around the lock latch, for user_mode sharing of one instance among threads (requires WC_RNG_HAVE_LOCK_FULL_MUTEX).
int wc_InitRngNonce_ex2(WC_RNG * rng, const byte * nonce, word32 nonceSz, const byte * perso, word32 persoSz, void * heap, int devId, word32 flags)
Initialize a WC_RNG with a caller_supplied nonce and instantiation_time security attributes. The nonce semantics are those of wc_InitRngNonce_ex(); the flags semantics are those of wc_InitRng_ex2().
int wc_RNG_GetStatus(const WC_RNG * rng)
Read_only accessor for the RNG health status. Returns the instance's enum wc_RngHealthState value (WC_DRBG_NOT_INIT, WC_DRBG_OK, WC_DRBG_FAILED, WC_DRBG_CONT_FAILED).
int wc_RNG_DRBG_Present(const WC_RNG * rng)
Returns 1 if rng has an instantiated DRBG, else 0. An in_service WC_RNG can lack one: instantiation bypasses the DRBG when the CPU has RDRAND (HAVE_INTEL_RDRAND). DRBG_specific services (commanded reseed, banked next seeds, RBG chains) are unavailable on such instances.
int wc_RNG_DRBG_GetReseedCtr(const WC_RNG * rng, wc_drbg_reseed_ctr_t * reseedCtr)
Report the DRBG's current reseed counter – the number of generate operations since the last credited (re)seed, starting at 1.
int wc_RNG_DRBG_ScheduleReseed(WC_RNG * rng)
Mark rng due for reseed: the next generate operation reseeds from the module's built-in or registered seed source before producing output. This can only shorten the current seed's remaining lifetime, never extend it.
int wc_RNG_DRBG_Reseed_Now(WC_RNG * rng, const byte * nonce, word32 nonceSz)
Immediately reseed rng from the module's built-in or registered seed source, with an optional nonce as additional input. The credited reseed resets the reseed counter.
int wc_RNG_DRBG_Reseed_Nonce(WC_RNG * rng, const byte * seed, word32 seedSz, const byte * nonce, word32 nonceSz)
Reseed rng's DRBG with caller-supplied seed material and an optional nonce as additional input. The material is credited as entropy: the reseed counter resets.
int wc_RNG_DRBG_Stir(WC_RNG * rng, const byte * seed, word32 seedSz)
Similar to wc_RNG_DRBG_Reseed(), except the caller-supplied material is mixed through the reseed derivation function without being credited as entropy: the reseed counter is not reset, so only the module's own seed source ever extends the instance's seed lifetime.
int wc_RNG_DRBG_Stir_Nonce(WC_RNG * rng, const byte * seed, word32 seedSz, const byte * nonce, word32 nonceSz)
The nonce_bearing form of wc_RNG_DRBG_Stir().
int wc_InitRngRBGC(WC_RNG * child, WC_RNG * parent, word32 flags)
Instantiate child as an SP 800_90C RBG_chain member subordinate to parent, drawing its seed material from parent's generate function in place of the module's seed source. Every other aspect of instantiation is wc_InitRng_ex2()'s. The child is tagged with stratum (parent's stratum + 1), sticky for the instance's lifetime even across subsequent source reseeds; its claimable security strength is capped by parent's, and it has no prediction resistance. The caller must hold exclusive access to parent for the duration of the call; the spawn debits parent's reseed counter by one generate.
int wc_InitRngNonceRBGC(WC_RNG * child, WC_RNG * parent, const byte * nonce, word32 nonceSz, word32 flags)
The nonce_bearing form of wc_InitRngRBGC(): the nonce is used as additional instantiation input, as in wc_InitRngNonce_ex2().
int wc_InitRngRBGC_New(WC_RNG ** child, WC_RNG * parent, word32 flags)
The allocating form of wc_InitRngRBGC(): the child is allocated from parent's heap and returned through child. Release with wc_rng_free().
int wc_InitRngNonceRBGC_New(WC_RNG ** child, WC_RNG * parent, const byte * nonce, word32 nonceSz, word32 flags)
The allocating, nonce_bearing form of wc_InitRngRBGC().
int wc_RNG_DRBG_ReseedRBGC(WC_RNG * rng, WC_RNG * root, const byte * nonce, word32 nonceSz)
Reseed rng from root's generate output – the SP 800_90C chain reseed – with an optional nonce as additional input. The reseed is credited (the reseed counter resets) and rng acquires root's stratum plus one. The caller must hold exclusive access to both instances.
int wc_RNG_DRBG_StirRBGC(WC_RNG * rng, WC_RNG * root, const byte * nonce, word32 nonceSz)
The uncredited form of wc_RNG_DRBG_ReseedRBGC(): material from root is mixed in without resetting rng's reseed counter.
int wc_RNG_DRBG_GetRBGCStratum(const WC_RNG * rng)
Report rng's RBG_chain stratum: 0 for a root (never chain_seeded), n for a member seeded from a stratum_(n_1) parent. The stratum is sticky for the instance's lifetime, even across subsequent source reseeds.
int wc_RNG_DRBG_GetNextSeedRBGCStratum(const WC_RNG * rng)
Report the RBG-chain stratum of rng's banked next seed – race-free via the aperture protocol – for provenance-aware consumers.
int wc_RNG_DRBG_NextSeedGenerate(WC_RNG * rng, word32 n)
Bank up to n more bytes of next-seed material from the module's seed source, health-testing and publishing the bank when it completes. The fill is incremental and in-boundary; a scheduling daemon may call this without owning the instance – the single-writer fill and the atomic aperture hand-off make it safe alongside a concurrent consumer.
int wc_RNG_DRBG_NextSeedGenerate_RBGC(WC_RNG * rng, WC_RNG * root, word32 n)
The chain_sourced form of wc_RNG_DRBG_NextSeedGenerate(): the banked material is drawn from root's generate function, and the bank is tagged with root's stratum plus one for provenance-aware consumption.
int wc_RNG_DRBG_NextSeedCurrent(WC_RNG * rng, WC_ATOMIC_INT_ARG * n)
Report the raw next_seed aperture value: a non_negative banked byte count (filling), WC_DRBG_NEXT_SEED_READY, or WC_DRBG_NEXT_SEED_CONSUMING. The snapshot is racy by design; use it for scheduling and diagnostics, not for hand-off decisions.
int wc_RNG_DRBG_NextSeedNow(WC_RNG * rng)
Claim a ready next_seed bank and perform a source_free credited reseed with it – safe in atomic context. The bank empties (use_once) and the reseed counter resets. The caller must own the instance.
int wc_RNG_DRBG_NextSeedNow_Nonce(WC_RNG * rng, const byte * nonce, word32 nonceSz)
The nonce_bearing form of wc_RNG_DRBG_NextSeedNow(): the nonce is mixed in as uncredited additional input alongside the banked seed.
int wc_RNG_DRBG_NextStirStore(WC_RNG * rng, const byte * nonce, word32 nonceSz)
Bank caller_supplied material (up to WC_DRBG_NEXT_STIR_LEN bytes) in the uncredited accumulator beside the banked next seed. Writer_safe without a lease (read_copy_store); if the accumulator is already full, the material is absorbed by xor. Harvested entropy deposited here improves the instance without claiming credit.
int wc_RNG_DRBG_NextStirNow(WC_RNG * rng)
Stir the banked uncredited accumulator into the DRBG as an uncredited, source-free mix-in – safe in atomic context; the reseed counter is not reset. The caller must own the instance.
int wc_RNG_lock_get(WC_RNG * rng, WC_RNG_lock_arg_t extra_bits)
Acquire rng's exclusive-ownership lock latch, spinning on the CAS until acquired, and or the caller's extra bits into the lock word. On an instance without the lock-required policy the call is a successful no-op unless extra bits are supplied.
int wc_RNG_lock_get_conditional(WC_RNG * rng, WC_RNG_lock_arg_t expected_extra_bits, WC_RNG_lock_arg_t want_extra_bits)
The conditional form of wc_RNG_lock_get(): acquire only if the current extra bits equal expected_extra_bits, atomically replacing them with want_extra_bits on success. Non-blocking with respect to the condition: a mismatch fails immediately rather than spinning.
int wc_RNG_lock_put(WC_RNG * rng, WC_RNG_lock_arg_t extra_bits)
Release rng's lock latch, clearing the supplied extra bits atomically with the release.
int wc_RNG_lock_put_conditional(WC_RNG * rng, WC_RNG_lock_arg_t expected_extra_bits, WC_RNG_lock_arg_t want_extra_bits)
The conditional form of wc_RNG_lock_put(): release only if the current extra bits equal expected_extra_bits, atomically replacing them with want_extra_bits on success.
int wc_RNG_lock_read(WC_RNG * rng, WC_RNG_lock_arg_t * state)
Read rng's lock word: the held/required latch bits, the entropy-invalidated bit, and any caller extra bits. The snapshot is racy by design.
int wc_RNG_lock_set_extra(WC_RNG * rng, WC_RNG_lock_arg_t extra_bits)
Atomically set (or) the supplied caller extra bits in rng's lock word. The caller should hold the latch.
int wc_RNG_lock_add_extra(WC_RNG * rng, WC_RNG_lock_arg_t extra_bits)
Atomically add the supplied value to the caller extra-bits field of rng's lock word – for counters carried above WC_RNG_LOCK_EXTRA_SHIFT.
int wc_RNG_lock_clear_extra(WC_RNG * rng, WC_RNG_lock_arg_t extra_bits)
Atomically clear the supplied caller extra bits in rng's lock word.
int wc_RNG_invalidate_entropy(WC_RNG * rng)
Mark rng's seed material untrusted – for VM fork/resume and similar duplication events – opening a new invalidation epoch: banked and pooled pre_event material is purged and wiped first, then the entropy_invalidated bit is latched in the lock word. An invalidated instance refuses service (NEEDS_RECOVERY_E) until recovery_reseeded. Latch or condemn: on any error return the latch is down, and the instance is instead condemned (status DRBG_FAILED). A condemned bank instance is retired and recovered by the entropy daemon; a condemned leaf gets no daemon rescue – its owner sees RNG_FAILURE_E from subsequent operations and recovers it with wc_FreeRng() then wc_InitRng*().
int wc_RNG_register_free_hook(WC_RNG * rng, wc_RNG_free_hook_cb_t free_hook, void * arg)
Register a callback fired by wc_FreeRng() at teardown – for external registries (e.g. a kernel_module registry that must reach every live RNG on a VM duplication event) that need to drop their reference when the object dies.
int wc_RNG_Pool_Alloc(WC_RNG * rng, word32 size)
Attach a random pool to rng: a buffer of size bytes of pre_generated output, filled by wc_RNG_Pool_Collect() and drained atomic_context_safely by wc_RNG_Pool_Extract(). The pool is released with the instance.
int wc_RNG_Pool_Collect(WC_RNG * rng, word32 n)
Generate up to n bytes into rng's pool from rng itself. The collect/extract hand-off is arbitrated by an atomic aperture word, so a single collector is safe alongside concurrent extractors.
int wc_RNG_Pool_Collect2(WC_RNG * rng_dest, WC_RNG * rng_src, word32 n)
The two_instance form of wc_RNG_Pool_Collect(): fill rng_dest's pool with output drawn from rng_src – so a service instance's pool can be topped up by a daemon-owned generator.
int wc_RNG_Pool_Extract(WC_RNG * rng, byte * out, word32 * n)
Drain up to n bytes from rng's pool into out – atomic-context-safe. On success n reports the bytes actually delivered; on any error return *n is left unmodified.
int wc_RNG_Pool_Current(WC_RNG * rng, word32 * n)
Report the pool's current fill in bytes. The snapshot is racy by design.
int wc_rng_debug_stats_snap(struct wc_rng_debug_stats_snapshot * s, const WC_RNG * rng)
Snapshot the global RNG debug counters (WC_RNG_DEBUG_STATS) – seeds and reseeds by provenance, generates, pool and bank traffic – into s, for later delta accounting with wc_rng_debug_stats_sum().
int wc_rng_debug_stats_restore(const struct wc_rng_debug_stats_snapshot * s, WC_RNG * rng)
Restore the global RNG debug counters from a snapshot – so a test can unwind its own accounting.
int wc_rng_debug_stats_sum(struct wc_rng_debug_stats_snapshot * s, const WC_RNG * rng)
Accumulate the current global RNG debug counters into s – combined with a prior wc_rng_debug_stats_snap(), a delta accounting of the interval's RNG activity.

Functions Documentation

function wc_InitNetRandom

int wc_InitNetRandom(
    const char * configFile,
    wnr_hmac_key hmac_cb,
    int timeout
)

Init global Whitewood netRandom context.

Parameters:

  • configFile Path to configuration file
  • hmac_cb Optional to create HMAC callback.
  • timeout A timeout duration.

See: wc_FreeNetRandom

Return:

  • 0 Success
  • BAD_FUNC_ARG Either configFile is null or timeout is negative.
  • RNG_FAILURE_E There was a failure initializing the rng.

Example

char* config = "path/to/config/example.conf";
int time = // Some sufficient timeout value;

if (wc_InitNetRandom(config, NULL, time) != 0)
{
    // Some error occurred
}

function wc_FreeNetRandom

int wc_FreeNetRandom(
    void 
)

Free global Whitewood netRandom context.

Parameters:

  • none No returns.

See: wc_InitNetRandom

Return:

  • 0 Success
  • BAD_MUTEX_E Error locking mutex on wnr_mutex

Example

int ret = wc_FreeNetRandom();
if(ret != 0)
{
    // Handle the error
}

function wc_InitRng

int wc_InitRng(
    WC_RNG * rng
)

Gets the seed (from OS) and key cipher for rng. rng->drbg (deterministic random bit generator) allocated (should be deallocated with wc_FreeRng). This is a blocking operation.

Parameters:

  • rng random number generator to be initialized for use with a seed and key cipher

See:

Return:

  • 0 on success.
  • MEMORY_E XMALLOC failed
  • WINCRYPT_E wc_GenerateSeed: failed to acquire context
  • CRYPTGEN_E wc_GenerateSeed: failed to get random
  • BAD_FUNC_ARG wc_RNG_GenerateBlock input is null or sz exceeds MAX_REQUEST_LEN
  • DRBG_CONT_FIPS_E wc_RNG_GenerateBlock: Hash_gen returned DRBG_CONT_FAILURE
  • RNG_FAILURE_E wc_RNG_GenerateBlock: Default error. rng’s status originally not ok, or set to DRBG_FAILED

Example

RNG  rng;
int ret;

#ifdef HAVE_CAVIUM
ret = wc_InitRngCavium(&rng, CAVIUM_DEV_ID);
if (ret != 0){
    printf(“RNG Nitrox init for device: %d failed”, CAVIUM_DEV_ID);
    return -1;
}
#endif
ret = wc_InitRng(&rng);
if (ret != 0){
    printf(“RNG init failed”);
    return -1;
}

function wc_RNG_GenerateBlock

int wc_RNG_GenerateBlock(
    WC_RNG * rng,
    byte * output,
    word32 sz
)

Copies a sz bytes of pseudorandom data to output. Will reseed rng if needed (blocking).

Parameters:

  • rng random number generator initialized with wc_InitRng
  • output buffer to which the block is copied
  • sz size of output in bytes

See:

Return:

  • 0 on success
  • BAD_FUNC_ARG an input is null or sz exceeds MAX_REQUEST_LEN
  • DRBG_CONT_FIPS_E Hash_gen returned DRBG_CONT_FAILURE
  • RNG_FAILURE_E Default error. rng’s status originally not ok, or set to DRBG_FAILED

Example

RNG  rng;
int  sz = 32;
byte block[sz];

int ret = wc_InitRng(&rng);
if (ret != 0) {
    return -1; //init of rng failed!
}

ret = wc_RNG_GenerateBlock(&rng, block, sz);
if (ret != 0) {
    return -1; //generating block failed!
}

function wc_RNG_GenerateByte

int wc_RNG_GenerateByte(
    WC_RNG * rng,
    byte * b
)

Calls wc_RNG_GenerateBlock to copy a byte of pseudorandom data to b. Will reseed rng if needed.

Parameters:

  • rng random number generator initialized with wc_InitRng
  • b one byte buffer to which the block is copied

See:

Return:

  • 0 on success
  • BAD_FUNC_ARG an input is null or sz exceeds MAX_REQUEST_LEN
  • DRBG_CONT_FIPS_E Hash_gen returned DRBG_CONT_FAILURE
  • RNG_FAILURE_E Default error. rng’s status originally not ok, or set to DRBG_FAILED

Example

RNG  rng;
int  sz = 32;
byte b[1];

int ret = wc_InitRng(&rng);
if (ret != 0) {
    return -1; //init of rng failed!
}

ret = wc_RNG_GenerateByte(&rng, b);
if (ret != 0) {
    return -1; //generating block failed!
}

function wc_FreeRng

int wc_FreeRng(
    WC_RNG * rng
)

Should be called when RNG no longer needed in order to securely free drgb. Zeros and XFREEs rng-drbg.

Parameters:

  • rng random number generator initialized with wc_InitRng

See:

Return:

  • 0 on success
  • BAD_FUNC_ARG rng or rng->drgb null
  • RNG_FAILURE_E Failed to deallocated drbg

Example

RNG  rng;
int ret = wc_InitRng(&rng);
if (ret != 0) {
    return -1; //init of rng failed!
}

int ret = wc_FreeRng(&rng);
if (ret != 0) {
    return -1; //free of rng failed!
}

function wc_RNG_HealthTest

int wc_RNG_HealthTest(
    int reseed,
    const byte * seedA,
    word32 seedASz,
    const byte * seedB,
    word32 seedBSz,
    byte * output,
    word32 outputSz
)

Creates and tests functionality of drbg.

Parameters:

  • int reseed: if set, will test reseed functionality
  • seedA seed to instantiate drgb with
  • seedASz size of seedA in bytes
  • seedB If reseed set, drbg will be reseeded with seedB
  • seedBSz size of seedB in bytes
  • output initialized to random data seeded with seedB if seedrandom is set, and seedA otherwise
  • outputSz length of output in bytes

See:

Return:

  • 0 on success
  • BAD_FUNC_ARG seedA and output must not be null. If reseed set seedB must not be null
  • -1 test failed

Example

byte output[SHA256_DIGEST_SIZE * 4];
const byte test1EntropyB[] = ....; // test input for reseed false
const byte test1Output[] = ....;   // testvector: expected output of
                               // reseed false
ret = wc_RNG_HealthTest(0, test1Entropy, sizeof(test1Entropy), NULL, 0,
                    output, sizeof(output));
if (ret != 0)
    return -1;//healthtest without reseed failed

if (XMEMCMP(test1Output, output, sizeof(output)) != 0)
    return -1; //compare to testvector failed: unexpected output

const byte test2EntropyB[] = ....; // test input for reseed
const byte test2Output[] = ....;   // testvector expected output of reseed
ret = wc_RNG_HealthTest(1, test2EntropyA, sizeof(test2EntropyA),
                    test2EntropyB, sizeof(test2EntropyB),
                    output, sizeof(output));

if (XMEMCMP(test2Output, output, sizeof(output)) != 0)
    return -1; //compare to testvector failed

function wc_GenerateSeed

int wc_GenerateSeed(
    OS_Seed * os,
    byte * output,
    word32 sz
)

Generates seed from OS entropy source. Lower-level function used internally by wc_InitRng.

Parameters:

  • os Pointer to OS_Seed structure
  • output Buffer to store seed
  • sz Size of seed in bytes

See: wc_InitRng

Return:

  • 0 On success
  • WINCRYPT_E Failed to acquire context (Windows)
  • CRYPTGEN_E Failed to generate random (Windows)
  • RNG_FAILURE_E Failed to read entropy

Example

OS_Seed os;
byte seed[32];
int ret = wc_GenerateSeed(&os, seed, sizeof(seed));

function wc_rng_new

WC_RNG * wc_rng_new(
    byte * nonce,
    word32 nonceSz,
    void * heap
)

Allocates and initializes new WC_RNG with optional nonce.

Parameters:

  • nonce Nonce buffer (can be NULL)
  • nonceSz Nonce size
  • heap Heap hint (can be NULL)

See: wc_rng_free

Return:

  • Pointer to WC_RNG on success
  • NULL on failure

Example

WC_RNG* rng = wc_rng_new(NULL, 0, NULL);
wc_rng_free(rng);

function wc_rng_new_ex

int wc_rng_new_ex(
    WC_RNG ** rng,
    byte * nonce,
    word32 nonceSz,
    void * heap,
    int devId
)

Allocates and initializes WC_RNG with extended parameters.

Parameters:

  • rng Pointer to store WC_RNG pointer
  • nonce Nonce buffer (can be NULL)
  • nonceSz Nonce size
  • heap Heap hint (can be NULL)
  • devId Device ID (INVALID_DEVID for software)

See: wc_rng_new

Return:

  • 0 On success
  • BAD_FUNC_ARG If rng is NULL
  • MEMORY_E Memory allocation failed

Example

WC_RNG* rng;
int ret = wc_rng_new_ex(&rng, NULL, 0, NULL, INVALID_DEVID);
wc_rng_free(rng);

function wc_rng_free

void wc_rng_free(
    WC_RNG * rng
)

Frees WC_RNG allocated with wc_rng_new.

Parameters:

  • rng WC_RNG to free

See: wc_rng_new

Example

WC_RNG* rng = wc_rng_new(NULL, 0, NULL);
wc_rng_free(rng);

function wc_InitRng_ex

int wc_InitRng_ex(
    WC_RNG * rng,
    void * heap,
    int devId
)

Initializes WC_RNG with extended parameters.

Parameters:

  • rng WC_RNG to initialize
  • heap Heap hint (can be NULL)
  • devId Device ID (INVALID_DEVID for software)

See: wc_InitRng

Return:

  • 0 On success
  • BAD_FUNC_ARG If rng is NULL
  • RNG_FAILURE_E Initialization failed

Example

WC_RNG rng;
int ret = wc_InitRng_ex(&rng, NULL, INVALID_DEVID);
wc_FreeRng(&rng);

function wc_InitRngNonce

int wc_InitRngNonce(
    WC_RNG * rng,
    const byte * nonce,
    word32 nonceSz
)

Initializes WC_RNG with nonce.

Parameters:

  • rng WC_RNG to initialize
  • nonce Nonce buffer
  • nonceSz Nonce size

See: wc_InitRng

Return:

  • 0 On success
  • BAD_FUNC_ARG If rng is NULL
  • RNG_FAILURE_E Initialization failed

Example

WC_RNG rng;
byte nonce[16];
int ret = wc_InitRngNonce(&rng, nonce, sizeof(nonce));
wc_FreeRng(&rng);

function wc_InitRngNonce_ex

int wc_InitRngNonce_ex(
    WC_RNG * rng,
    const byte * nonce,
    word32 nonceSz,
    void * heap,
    int devId
)

Initializes WC_RNG with nonce and extended parameters.

Parameters:

  • rng WC_RNG to initialize
  • nonce Nonce buffer
  • nonceSz Nonce size
  • heap Heap hint (can be NULL)
  • devId Device ID (INVALID_DEVID for software)

See: wc_InitRngNonce

Return:

  • 0 On success
  • BAD_FUNC_ARG If rng is NULL
  • RNG_FAILURE_E Initialization failed

Example

WC_RNG rng;
byte nonce[16];
int ret = wc_InitRngNonce_ex(&rng, nonce, sizeof(nonce), NULL,
                             INVALID_DEVID);
wc_FreeRng(&rng);

function wc_SetSeed_Cb

int wc_SetSeed_Cb(
    wc_RngSeed_Cb cb
)

Sets callback for custom seed generation.

Parameters:

  • cb Seed callback function

See: wc_GenerateSeed

Return:

  • 0 On success
  • BAD_FUNC_ARG If cb is NULL

Example

int my_cb(OS_Seed* os, byte* out, word32 sz) { return 0; }
wc_SetSeed_Cb(my_cb);

function wc_RNG_DRBG_Reseed

int wc_RNG_DRBG_Reseed(
    WC_RNG * rng,
    const byte * seed,
    word32 seedSz
)

Reseeds DRBG with new entropy.

Parameters:

  • rng WC_RNG to reseed
  • seed Seed buffer
  • seedSz Seed size

See: wc_InitRng

Return:

  • 0 On success
  • BAD_FUNC_ARG If rng or seed is NULL
  • RNG_FAILURE_E Reseed failed

Example

WC_RNG rng;
byte seed[32];
wc_InitRng(&rng);
int ret = wc_RNG_DRBG_Reseed(&rng, seed, sizeof(seed));

function wc_RNG_TestSeed

int wc_RNG_TestSeed(
    const byte * seed,
    word32 seedSz
)

Tests seed validity for DRBG.

Parameters:

  • seed Seed to test
  • seedSz Seed size

See: wc_InitRng

Return:

  • 0 If valid
  • BAD_FUNC_ARG If seed is NULL
  • ENTROPY_RT_E || ENTROPY_APT_E Validation failed
  • ENTROPY_APT_E The adaptive proportion test failed.
  • MEMORY_E Allocation failed.

Example

byte seed[32];
int ret = wc_RNG_TestSeed(seed, sizeof(seed));

function wc_RNG_HealthTest_ex

int wc_RNG_HealthTest_ex(
    int reseed,
    const byte * nonce,
    word32 nonceSz,
    const byte * seedA,
    word32 seedASz,
    const byte * seedB,
    word32 seedBSz,
    byte * output,
    word32 outputSz,
    void * heap,
    int devId
)

RNG health test with extended parameters.

Parameters:

  • reseed Non-zero to test reseeding
  • nonce Nonce buffer (can be NULL)
  • nonceSz Nonce size
  • seedA Initial seed
  • seedASz Initial seed size
  • seedB Reseed buffer (required if reseed set)
  • seedBSz Reseed size
  • output Output buffer
  • outputSz Output size
  • heap Heap hint (can be NULL)
  • devId Device ID (INVALID_DEVID for software)

See: wc_RNG_HealthTest

Return:

  • 0 On success
  • BAD_FUNC_ARG If required params NULL
  • -1 Test failed

Example

byte seedA[32], seedB[32], out[64];
int ret = wc_RNG_HealthTest_ex(1, NULL, 0, seedA, 32, seedB, 32,
                               out, 64, NULL, INVALID_DEVID);

function wc_RNG_HealthTest_SHA512

int wc_RNG_HealthTest_SHA512(
    int reseed,
    const byte * seedA,
    word32 seedASz,
    const byte * seedB,
    word32 seedBSz,
    byte * output,
    word32 outputSz
)

Runs the SHA-512 Hash_DRBG Known Answer Test (KAT) per SP 800-90A. Instantiates a SHA-512 DRBG with seedA, optionally reseeds with seedB, generates output, and compares against known test vectors. Available when WOLFSSL_DRBG_SHA512 is defined.

Parameters:

  • reseed Non-zero to test reseeding
  • seedA Initial entropy seed
  • seedASz Size of seedA in bytes
  • seedB Reseed entropy (required if reseed is set)
  • seedBSz Size of seedB in bytes
  • output Buffer to receive generated output
  • outputSz Size of output in bytes

See:

Return:

  • 0 On success
  • BAD_FUNC_ARG If seedA or output is NULL, or if reseed is set and seedB is NULL
  • -1 Test failed

Example

byte output[WC_SHA512_DIGEST_SIZE * 4];
const byte seedA[] = { ... };
const byte seedB[] = { ... };

ret = wc_RNG_HealthTest_SHA512(0, seedA, sizeof(seedA), NULL, 0,
                               output, sizeof(output));
if (ret != 0)
    return -1;

ret = wc_RNG_HealthTest_SHA512(1, seedA, sizeof(seedA),
                               seedB, sizeof(seedB),
                               output, sizeof(output));
if (ret != 0)
    return -1;

function wc_RNG_HealthTest_SHA512_ex

int wc_RNG_HealthTest_SHA512_ex(
    int reseed,
    const byte * nonce,
    word32 nonceSz,
    const byte * persoString,
    word32 persoStringSz,
    const byte * seedA,
    word32 seedASz,
    const byte * seedB,
    word32 seedBSz,
    const byte * additionalA,
    word32 additionalASz,
    const byte * additionalB,
    word32 additionalBSz,
    byte * output,
    word32 outputSz,
    void * heap,
    int devId
)

Extended SHA-512 Hash_DRBG health test with nonce, personalization string, and additional input support. Suitable for full ACVP / CAVP test vector validation. Available when WOLFSSL_DRBG_SHA512 is defined.

Parameters:

  • reseed Non-zero to test reseeding
  • nonce Nonce buffer (can be NULL)
  • nonceSz Nonce size
  • persoString Personalization string (can be NULL)
  • persoStringSz Personalization string size
  • seedA Initial entropy seed
  • seedASz Initial seed size
  • seedB Reseed entropy (required if reseed is set)
  • seedBSz Reseed size
  • additionalA Additional input for first generate (can be NULL)
  • additionalASz Additional input A size
  • additionalB Additional input for second generate (can be NULL)
  • additionalBSz Additional input B size
  • output Output buffer
  • outputSz Output size
  • heap Heap hint (can be NULL)
  • devId Device ID (INVALID_DEVID for software)

See:

Return:

  • 0 On success
  • BAD_FUNC_ARG If required params are NULL
  • -1 Test failed

Example

byte output[WC_SHA512_DIGEST_SIZE * 4];
const byte seedA[] = { ... };
const byte nonce[] = { ... };

int ret = wc_RNG_HealthTest_SHA512_ex(0, nonce, sizeof(nonce),
                                      NULL, 0,
                                      seedA, sizeof(seedA),
                                      NULL, 0,
                                      NULL, 0, NULL, 0,
                                      output, sizeof(output),
                                      NULL, INVALID_DEVID);

function wc_Sha256Drbg_Disable

int wc_Sha256Drbg_Disable(
    void 
)

Disables the SHA-256 Hash_DRBG at runtime. When disabled, newly initialized WC_RNG instances will not use the SHA-256 DRBG. If the SHA-512 DRBG is enabled (WOLFSSL_DRBG_SHA512), new RNG instances will use SHA-512 instead. Requires HAVE_HASHDRBG.

See:

Return: 0 On success

Example

wc_Sha256Drbg_Disable();
// New WC_RNG instances will now use SHA-512 DRBG if available
WC_RNG rng;
wc_InitRng(&rng);

function wc_Sha256Drbg_Enable

int wc_Sha256Drbg_Enable(
    void 
)

Re-enables the SHA-256 Hash_DRBG at runtime after a prior call to wc_Sha256Drbg_Disable(). Requires HAVE_HASHDRBG.

See:

Return: 0 On success

Example

wc_Sha256Drbg_Disable();
// ... use SHA-512 DRBG only ...
wc_Sha256Drbg_Enable();
// New WC_RNG instances can use SHA-256 DRBG again

function wc_Sha256Drbg_IsDisabled

int wc_Sha256Drbg_IsDisabled(
    void 
)

Returns whether the SHA-256 Hash_DRBG is currently disabled. Requires HAVE_HASHDRBG.

See:

Return:

  • 1 SHA-256 DRBG is disabled
  • 0 SHA-256 DRBG is enabled (not disabled)

Example

if (wc_Sha256Drbg_IsDisabled()) {
    printf("SHA-256 DRBG is off\n");
}

function wc_Sha512Drbg_Disable

int wc_Sha512Drbg_Disable(
    void 
)

Disables the SHA-512 Hash_DRBG at runtime. When disabled, newly initialized WC_RNG instances will not use the SHA-512 DRBG. If the SHA-256 DRBG is still enabled, new RNG instances will fall back to SHA-256. Available when WOLFSSL_DRBG_SHA512 is defined. Requires HAVE_HASHDRBG.

See:

Return: 0 On success

Example

wc_Sha512Drbg_Disable();
// New WC_RNG instances will now use SHA-256 DRBG
WC_RNG rng;
wc_InitRng(&rng);

function wc_Sha512Drbg_Enable

int wc_Sha512Drbg_Enable(
    void 
)

Re-enables the SHA-512 Hash_DRBG at runtime after a prior call to wc_Sha512Drbg_Disable(). Available when WOLFSSL_DRBG_SHA512 is defined. Requires HAVE_HASHDRBG.

See:

Return: 0 On success

Example

wc_Sha512Drbg_Disable();
// ... use SHA-256 DRBG only ...
wc_Sha512Drbg_Enable();
// New WC_RNG instances can use SHA-512 DRBG again

function wc_Sha512Drbg_IsDisabled

int wc_Sha512Drbg_IsDisabled(
    void 
)

Returns whether the SHA-512 Hash_DRBG is currently disabled. Available when WOLFSSL_DRBG_SHA512 is defined. Requires HAVE_HASHDRBG.

See:

Return:

  • 1 SHA-512 DRBG is disabled
  • 0 SHA-512 DRBG is enabled (not disabled)

Example

if (wc_Sha512Drbg_IsDisabled()) {
    printf("SHA-512 DRBG is off\n");
}

function wc_InitRng_ex2

int wc_InitRng_ex2(
    WC_RNG * rng,
    void * heap,
    int devId,
    word32 flags
)

Initialize a WC_RNG with instantiation-time security attributes. Identical to wc_InitRng_ex(), with a flags argument fixing attributes at birth: WC_RNG_INIT_FLAG_LOCK_REQUIRED latches the sticky lock_required policy bit, so there is no reachable state in which the instance serves without its lock policy; WC_RNG_INIT_FLAG_LOCK_INITIALLY constructs into a held lease, to be released with wc_RNG_lock_put(); WC_RNG_INIT_FLAG_USE_FULL_MUTEX layers a blocking wolfSSL_Mutex outermost around the lock latch, for user_mode sharing of one instance among threads (requires WC_RNG_HAVE_LOCK_FULL_MUTEX).

Parameters:

  • rng The RNG object to initialize.
  • heap Heap hint for dynamic allocation.
  • devId Device id, or INVALID_DEVID.
  • flags Bitwise-or of WC_RNG_INIT_FLAG_* attributes.

See:

Return:

  • 0 Success
  • BAD_FUNC_ARG rng is null.
  • NOT_COMPILED_IN A requested flag is not compiled in.

Example

WC_RNG rng;
if (wc_InitRng_ex2(&rng, NULL, INVALID_DEVID,
                   WC_RNG_INIT_FLAG_LOCK_REQUIRED |
                   WC_RNG_INIT_FLAG_LOCK_INITIALLY) != 0) {
    // error handling
}
// caller holds the lease from birth

function wc_InitRngNonce_ex2

int wc_InitRngNonce_ex2(
    WC_RNG * rng,
    const byte * nonce,
    word32 nonceSz,
    const byte * perso,
    word32 persoSz,
    void * heap,
    int devId,
    word32 flags
)

Initialize a WC_RNG with a caller-supplied nonce and instantiation-time security attributes. The nonce semantics are those of wc_InitRngNonce_ex(); the flags semantics are those of wc_InitRng_ex2().

Parameters:

  • rng The RNG object to initialize.
  • nonce Optional nonce used as additional instantiation input.
  • nonceSz Length of nonce in bytes.
  • heap Heap hint for dynamic allocation.
  • devId Device id, or INVALID_DEVID.
  • perso Optional personalization string (may be null).
  • persoSz Length of perso in bytes.
  • flags Bitwise-or of WC_RNG_INIT_FLAG_* attributes.

See:

Return:

  • 0 Success
  • BAD_FUNC_ARG rng is null.
  • NOT_COMPILED_IN A requested flag is not compiled in.

function wc_RNG_GetStatus

int wc_RNG_GetStatus(
    const WC_RNG * rng
)

Read-only accessor for the RNG health status. Returns the instance's enum wc_RngHealthState value (WC_DRBG_NOT_INIT, WC_DRBG_OK, WC_DRBG_FAILED, WC_DRBG_CONT_FAILED).

Parameters:

  • rng The RNG object to interrogate.

See:

Return:

  • WC_DRBG_OK The instance is in service.
  • BAD_FUNC_ARG rng is null.

Example

if (wc_RNG_GetStatus(&rng) != WC_DRBG_OK) {
    // instance is not serviceable
}

function wc_RNG_DRBG_Present

int wc_RNG_DRBG_Present(
    const WC_RNG * rng
)

Returns 1 if rng has an instantiated DRBG, else 0. An in-service WC_RNG can lack one: instantiation bypasses the DRBG when the CPU has RDRAND (HAVE_INTEL_RDRAND). DRBG-specific services (commanded reseed, banked next seeds, RBG chains) are unavailable on such instances.

Parameters:

  • rng The RNG object to interrogate.

See:

Return:

  • 1 rng has a live DRBG.
  • 0 rng is null or has no DRBG.

function wc_RNG_DRBG_GetReseedCtr

int wc_RNG_DRBG_GetReseedCtr(
    const WC_RNG * rng,
    wc_drbg_reseed_ctr_t * reseedCtr
)

Report the DRBG's current reseed counter – the number of generate operations since the last credited (re)seed, starting at 1.

Parameters:

  • rng The RNG object to interrogate.
  • reseedCtr Receives the counter.

See:

Return:

  • 0 Success
  • BAD_FUNC_ARG rng or reseedCtr is null.
  • WRONG_TYPE_OBJECT_E rng has no DRBG (RDRAND et al.).

function wc_RNG_DRBG_ScheduleReseed

int wc_RNG_DRBG_ScheduleReseed(
    WC_RNG * rng
)

Mark rng due for reseed: the next generate operation reseeds from the module's built-in or registered seed source before producing output. This can only shorten the current seed's remaining lifetime, never extend it.

Parameters:

  • rng The RNG object to schedule.

See:

Return:

  • 0 Success
  • BAD_FUNC_ARG rng is null.
  • WRONG_TYPE_OBJECT_E rng has no DRBG (RDRAND et al.) – a commanded reseed that cannot happen is not a success.

function wc_RNG_DRBG_Reseed_Now

int wc_RNG_DRBG_Reseed_Now(
    WC_RNG * rng,
    const byte * nonce,
    word32 nonceSz
)

Immediately reseed rng from the module's built-in or registered seed source, with an optional nonce as additional input. The credited reseed resets the reseed counter.

Parameters:

  • rng The RNG object to reseed.
  • nonce Optional additional input.
  • nonceSz Length of nonce in bytes.

See:

Return:

  • 0 Success
  • BAD_FUNC_ARG rng is null, or nonce is null with nonceSz nonzero.
  • WRONG_TYPE_OBJECT_E rng has no DRBG (RDRAND et al.).
  • DRBG_CONT_FIPS_E The continuous test failed; the DRBG is out of service.
  • RNG_FAILURE_E The DRBG is out of service or reseeding failed.

function wc_RNG_DRBG_Reseed_Nonce

int wc_RNG_DRBG_Reseed_Nonce(
    WC_RNG * rng,
    const byte * seed,
    word32 seedSz,
    const byte * nonce,
    word32 nonceSz
)

Reseed rng's DRBG with caller-supplied seed material and an optional nonce as additional input. The material is credited as entropy: the reseed counter resets.

Parameters:

  • rng The RNG object to reseed.
  • seed Seed material.
  • seedSz Length of seed in bytes.
  • nonce Optional additional input.
  • nonceSz Length of nonce in bytes.

See:

Return:

  • 0 Success
  • RNG_FAILURE_E rng is condemned (status DRBG_FAILED): a condemned instance does not accept a credited reseed; recover with wc_FreeRng() then wc_InitRng*().
  • BAD_FUNC_ARG rng or seed is null.
  • WRONG_TYPE_OBJECT_E rng has no DRBG (RDRAND et al.).

function wc_RNG_DRBG_Stir

int wc_RNG_DRBG_Stir(
    WC_RNG * rng,
    const byte * seed,
    word32 seedSz
)

Similar to wc_RNG_DRBG_Reseed(), except the caller-supplied material is mixed through the reseed derivation function without being credited as entropy: the reseed counter is not reset, so only the module's own seed source ever extends the instance's seed lifetime.

Parameters:

  • rng The RNG object to stir.
  • seed Material to mix in.
  • seedSz Length of seed in bytes.

See:

Return:

  • 0 Success
  • BAD_FUNC_ARG rng or seed is null.
  • WRONG_TYPE_OBJECT_E rng has no DRBG (RDRAND et al.).

function wc_RNG_DRBG_Stir_Nonce

int wc_RNG_DRBG_Stir_Nonce(
    WC_RNG * rng,
    const byte * seed,
    word32 seedSz,
    const byte * nonce,
    word32 nonceSz
)

The nonce-bearing form of wc_RNG_DRBG_Stir().

Parameters:

  • rng The RNG object to stir.
  • seed Material to mix in.
  • seedSz Length of seed in bytes.
  • nonce Optional additional input.
  • nonceSz Length of nonce in bytes.

See:

Return:

  • 0 Success
  • BAD_FUNC_ARG rng or seed is null.
  • WRONG_TYPE_OBJECT_E rng has no DRBG (RDRAND et al.).

function wc_InitRngRBGC

int wc_InitRngRBGC(
    WC_RNG * child,
    WC_RNG * parent,
    word32 flags
)

Instantiate child as an SP 800-90C RBG-chain member subordinate to parent, drawing its seed material from parent's generate function in place of the module's seed source. Every other aspect of instantiation is wc_InitRng_ex2()'s. The child is tagged with stratum (parent's stratum + 1), sticky for the instance's lifetime even across subsequent source reseeds; its claimable security strength is capped by parent's, and it has no prediction resistance. The caller must hold exclusive access to parent for the duration of the call; the spawn debits parent's reseed counter by one generate.

Parameters:

  • child The caller-provided WC_RNG to instantiate (uninitialized).
  • parent The chain parent to draw seed material from.
  • flags Bitwise-or of WC_RNG_INIT_FLAG_* attributes for the child.

See:

Return:

  • 0 Success
  • BAD_FUNC_ARG child or parent is null, or child equals parent.
  • SEQ_OVERFLOW_E parent's stratum is at the representable maximum.

Example

WC_RNG root, child;
wc_InitRng(&root);
if (wc_InitRngRBGC(&child, &root, WC_RNG_INIT_FLAG_NONE) == 0) {
    // child serves independently; release with wc_FreeRng(&child)
}

function wc_InitRngNonceRBGC

int wc_InitRngNonceRBGC(
    WC_RNG * child,
    WC_RNG * parent,
    const byte * nonce,
    word32 nonceSz,
    word32 flags
)

The nonce-bearing form of wc_InitRngRBGC(): the nonce is used as additional instantiation input, as in wc_InitRngNonce_ex2().

Parameters:

  • child The caller-provided WC_RNG to instantiate (uninitialized).
  • parent The chain parent to draw seed material from.
  • nonce Additional instantiation input.
  • nonceSz Length of nonce in bytes.
  • flags Bitwise-or of WC_RNG_INIT_FLAG_* attributes for the child.

See:

Return:

  • 0 Success
  • BAD_FUNC_ARG child or parent is null, child equals parent, or nonce is null with nonceSz nonzero.
  • SEQ_OVERFLOW_E parent's stratum is at the representable maximum.

function wc_InitRngRBGC_New

int wc_InitRngRBGC_New(
    WC_RNG ** child,
    WC_RNG * parent,
    word32 flags
)

The allocating form of wc_InitRngRBGC(): the child is allocated from parent's heap and returned through child. Release with wc_rng_free().

Parameters:

  • child Receives the allocated, instantiated WC_RNG.
  • parent The chain parent to draw seed material from.
  • flags Bitwise-or of WC_RNG_INIT_FLAG_* attributes for the child.

See:

Return:

  • 0 Success
  • BAD_FUNC_ARG child or parent is null.
  • MEMORY_E Allocation failed.
  • SEQ_OVERFLOW_E parent's stratum is at the representable maximum.

function wc_InitRngNonceRBGC_New

int wc_InitRngNonceRBGC_New(
    WC_RNG ** child,
    WC_RNG * parent,
    const byte * nonce,
    word32 nonceSz,
    word32 flags
)

The allocating, nonce-bearing form of wc_InitRngRBGC().

Parameters:

  • child Receives the allocated, instantiated WC_RNG.
  • parent The chain parent to draw seed material from.
  • nonce Additional instantiation input.
  • nonceSz Length of nonce in bytes.
  • flags Bitwise-or of WC_RNG_INIT_FLAG_* attributes for the child.

See:

Return:

  • 0 Success
  • BAD_FUNC_ARG child or parent is null, or nonce is null with nonceSz nonzero.
  • MEMORY_E Allocation failed.
  • SEQ_OVERFLOW_E parent's stratum is at the representable maximum.

function wc_RNG_DRBG_ReseedRBGC

int wc_RNG_DRBG_ReseedRBGC(
    WC_RNG * rng,
    WC_RNG * root,
    const byte * nonce,
    word32 nonceSz
)

Reseed rng from root's generate output – the SP 800-90C chain reseed – with an optional nonce as additional input. The reseed is credited (the reseed counter resets) and rng acquires root's stratum plus one. The caller must hold exclusive access to both instances.

Parameters:

  • rng The chain member to reseed.
  • root The chain parent to draw seed material from.
  • nonce Optional additional input.
  • nonceSz Length of nonce in bytes.

See:

Return:

  • 0 Success
  • BAD_FUNC_ARG rng or root is null, rng equals root, or the no-downgrade rule refuses root as a chain parent (see
  • WRONG_TYPE_OBJECT_E rng has no DRBG (RDRAND et al.).
  • SEQ_OVERFLOW_E root's stratum is at the representable maximum.

Credited chain reseeds obey a no-downgrade rule: a primary-seeded (stratum-0) root is always accepted, and a chained (stratum > 0) root is accepted only when its stratum is strictly less than rng's – the acquired stratum never increases, so reseed cycles are impossible by construction, consistent with SP 800-90C 7.1.2.2. Lateral (equal-stratum) and downgrading reseeds are refused with BAD_FUNC_ARG. Building WC_RNG_NO_RBGC_RESEED restricts credited chain reseeds to primary-seeded roots. Uncredited chain stirs (wc_RNG_DRBG_StirRBGC()) are exempt from all of this: they are stirs, claim nothing, and leave rng's stratum untouched.

).

function wc_RNG_DRBG_StirRBGC

int wc_RNG_DRBG_StirRBGC(
    WC_RNG * rng,
    WC_RNG * root,
    const byte * nonce,
    word32 nonceSz
)

The uncredited form of wc_RNG_DRBG_ReseedRBGC(): material from root is mixed in without resetting rng's reseed counter.

Parameters:

  • rng The chain member to stir.
  • root The chain parent to draw material from.
  • nonce Optional additional input.
  • nonceSz Length of nonce in bytes.

See:

Return:

  • 0 Success
  • BAD_FUNC_ARG rng or root is null, or rng equals root.
  • WRONG_TYPE_OBJECT_E rng has no DRBG (RDRAND et al.).

Unrestricted by the credited no-downgrade rule: any source stratum is accepted, and rng's reseed counter, stratum, and entropy-invalidated state are all left untouched – an uncredited chain reseed is a stir, and a stir must never masquerade as recovery or promotion.

function wc_RNG_DRBG_GetRBGCStratum

int wc_RNG_DRBG_GetRBGCStratum(
    const WC_RNG * rng
)

Report rng's RBG-chain stratum: 0 for a root (never chain-seeded), n for a member seeded from a stratum-(n-1) parent. The stratum is sticky for the instance's lifetime, even across subsequent source reseeds.

Parameters:

  • rng The RNG object to interrogate.

See:

Return:

  • 0 rng is a chain root.
  • n The stratum, positive for a chain member.
  • BAD_FUNC_ARG rng is null.

function wc_RNG_DRBG_GetNextSeedRBGCStratum

int wc_RNG_DRBG_GetNextSeedRBGCStratum(
    const WC_RNG * rng
)

Report the RBG-chain stratum of rng's banked next seed – race-free via the aperture protocol – for provenance-aware consumers.

Parameters:

  • rng The RNG object to interrogate.

See:

Return:

  • 0 The banked seed has root (source) provenance.
  • n The banked seed's stratum, positive for chain provenance.
  • BAD_FUNC_ARG rng is null or has no DRBG.
  • NOT_READY_E No banked seed is ready.

function wc_RNG_DRBG_NextSeedGenerate

int wc_RNG_DRBG_NextSeedGenerate(
    WC_RNG * rng,
    word32 n
)

Bank up to n more bytes of next-seed material from the module's seed source, health-testing and publishing the bank when it completes. The fill is incremental and in-boundary; a scheduling daemon may call this without owning the instance – the single-writer fill and the atomic aperture hand-off make it safe alongside a concurrent consumer.

Parameters:

  • rng The RNG object whose bank to fill.
  • n Maximum bytes to bank this call (clamped to space remaining).

See:

Return:

  • 0 Bytes were banked (bank may or may not yet be complete).
  • ALREADY_E The bank is ready or being consumed.
  • NOT_READY_E The health test could not run; simply retry.
  • BAD_FUNC_ARG rng is null or n is 0.
  • MISSING_RNG_E rng has no DRBG (RDRAND et al.).

Example

// scheduling daemon: fill incrementally until published
int ret = wc_RNG_DRBG_NextSeedGenerate(rng, 16);
if (ret == ALREADY_E) {
    // bank is ready; nothing to do until a consumer claims it
}

function wc_RNG_DRBG_NextSeedGenerate_RBGC

int wc_RNG_DRBG_NextSeedGenerate_RBGC(
    WC_RNG * rng,
    WC_RNG * root,
    word32 n
)

The chain-sourced form of wc_RNG_DRBG_NextSeedGenerate(): the banked material is drawn from root's generate function, and the bank is tagged with root's stratum plus one for provenance-aware consumption.

Parameters:

  • rng The RNG object whose bank to fill.
  • root The chain parent to draw material from.
  • n Maximum bytes to bank this call.

See:

Return:

  • 0 Bytes were banked.
  • ALREADY_E The bank is ready or being consumed.
  • NOT_READY_E The health test could not run; simply retry.
  • BAD_FUNC_ARG rng or root is null, or n is 0.
  • MISSING_RNG_E rng has no DRBG (RDRAND et al.).
  • SEQ_OVERFLOW_E root's stratum is at the representable maximum.

Banking is bound for credited redemption, so the credited no-downgrade rule applies at bank time: a primary-seeded (stratum-0) root is always accepted, and a chained root only when its stratum is strictly less than rng's – banking whose redemption would raise rng's stratum is refused with BAD_FUNC_ARG. The banked material records root's stratum plus one, observable via wc_RNG_DRBG_GetNextSeedRBGCStratum(), and redemption (wc_RNG_DRBG_NextSeedNow()) carries it onto rng.

function wc_RNG_DRBG_NextSeedCurrent

int wc_RNG_DRBG_NextSeedCurrent(
    WC_RNG * rng,
    WC_ATOMIC_INT_ARG * n
)

Report the raw next-seed aperture value: a non-negative banked byte count (filling), WC_DRBG_NEXT_SEED_READY, or WC_DRBG_NEXT_SEED_CONSUMING. The snapshot is racy by design; use it for scheduling and diagnostics, not for hand-off decisions.

Parameters:

  • rng The RNG object to interrogate.
  • n Receives the aperture value.

See:

Return:

  • 0 Success
  • BAD_FUNC_ARG rng or n is null.
  • MISSING_RNG_E rng has no DRBG (RDRAND et al.).

function wc_RNG_DRBG_NextSeedNow

int wc_RNG_DRBG_NextSeedNow(
    WC_RNG * rng
)

Claim a ready next-seed bank and perform a source-free credited reseed with it – safe in atomic context. The bank empties (use-once) and the reseed counter resets. The caller must own the instance.

Parameters:

  • rng The RNG object to reseed.

See:

Return:

  • 0 Success
  • NOT_READY_E No bank is ready.
  • BAD_FUNC_ARG rng is null.
  • MISSING_RNG_E rng has no DRBG (RDRAND et al.).

Example

// atomic-context consumer
if (wc_RNG_DRBG_NextSeedNow(rng) == 0) {
    // freshly reseeded without touching the seed source
}

function wc_RNG_DRBG_NextSeedNow_Nonce

int wc_RNG_DRBG_NextSeedNow_Nonce(
    WC_RNG * rng,
    const byte * nonce,
    word32 nonceSz
)

The nonce-bearing form of wc_RNG_DRBG_NextSeedNow(): the nonce is mixed in as uncredited additional input alongside the banked seed.

Parameters:

  • rng The RNG object to reseed.
  • nonce Additional input.
  • nonceSz Length of nonce in bytes.

See: wc_RNG_DRBG_NextSeedNow

Return:

  • 0 Success
  • NEEDS_RECOVERY_E A purge crossed the consume (an invalidation epoch boundary): no material is adopted, the entropy-invalidated latch is re-asserted, and a recovery reseed is scheduled.
  • NOT_READY_E No bank is ready.
  • BAD_FUNC_ARG rng is null, or nonce is null with nonceSz nonzero.
  • MISSING_RNG_E rng has no DRBG (RDRAND et al.).
  • DRBG_CONT_FIPS_E The continuous test failed; the DRBG is out of service.
  • RNG_FAILURE_E The DRBG is out of service.

function wc_RNG_DRBG_NextStirStore

int wc_RNG_DRBG_NextStirStore(
    WC_RNG * rng,
    const byte * nonce,
    word32 nonceSz
)

Bank caller-supplied material (up to WC_DRBG_NEXT_STIR_LEN bytes) in the uncredited accumulator beside the banked next seed. Writer-safe without a lease (read-copy-store); if the accumulator is already full, the material is absorbed by xor. Harvested entropy deposited here improves the instance without claiming credit.

Parameters:

  • rng The RNG object whose accumulator to feed.
  • nonce Material to bank.
  • nonceSz Length of nonce in bytes.

See:

Return:

  • 0 Success
  • BAD_FUNC_ARG rng or nonce is null, or nonceSz is 0.
  • MISSING_RNG_E rng has no DRBG (RDRAND et al.).

function wc_RNG_DRBG_NextStirNow

int wc_RNG_DRBG_NextStirNow(
    WC_RNG * rng
)

Stir the banked uncredited accumulator into the DRBG as an uncredited, source-free mix-in – safe in atomic context; the reseed counter is not reset. The caller must own the instance.

Parameters:

  • rng The RNG object to stir.

See: wc_RNG_DRBG_NextStirStore

Return:

  • 0 Success
  • NOT_READY_E The accumulator is empty or still accumulating, or the stir is refused (reseed interval, entropy-invalidated quarantine).
  • BUSY_E The accumulator was claimed by a racing consumer – the stir is happening by another hand.
  • BAD_FUNC_ARG rng is null.
  • MISSING_RNG_E rng has no DRBG (RDRAND et al.).
  • RNG_FAILURE_E The DRBG is out of service, or its hash failed mid-stir leaving a half-applied update – the instance is then condemned (status DRBG_FAILED).

function wc_RNG_lock_get

int wc_RNG_lock_get(
    WC_RNG * rng,
    WC_RNG_lock_arg_t extra_bits
)

Acquire rng's exclusive-ownership lock latch, spinning on the CAS until acquired, and or the caller's extra bits into the lock word. On an instance without the lock-required policy the call is a successful no-op unless extra bits are supplied.

Parameters:

  • rng The RNG object to lock.
  • extra_bits Caller-defined bits (above WC_RNG_LOCK_EXTRA_SHIFT) to set atomically with the acquisition, or 0.

See:

Return:

  • 0 Success
  • BAD_FUNC_ARG rng is null.
  • BUSY_E The lock is held.
  • NEEDS_RECOVERY_E The instance's entropy is invalidated (see wc_RNG_invalidate_entropy()); recover with a credited reseed before use.
  • BAD_MUTEX_E (WC_RNG_HAVE_LOCK_FULL_MUTEX) The outer mutex failed.
  • UNEXPECTED_STATE_E Spurious acquisition failure; retry.

Example

if (wc_RNG_lock_get(rng, 0) == 0) {
    ret = wc_RNG_GenerateBlock(rng, out, sizeof(out));
    wc_RNG_lock_put(rng, 0);
}

function wc_RNG_lock_get_conditional

int wc_RNG_lock_get_conditional(
    WC_RNG * rng,
    WC_RNG_lock_arg_t expected_extra_bits,
    WC_RNG_lock_arg_t want_extra_bits
)

The conditional form of wc_RNG_lock_get(): acquire only if the current extra bits equal expected_extra_bits, atomically replacing them with want_extra_bits on success. Non-blocking with respect to the condition: a mismatch fails immediately rather than spinning.

Parameters:

  • rng The RNG object to lock.
  • expected_extra_bits The extra bits required for acquisition.
  • want_extra_bits The extra bits to install on acquisition.

See:

Return:

  • 0 Success
  • BAD_FUNC_ARG rng is null.
  • BUSY_E The lock is held, or the extra bits do not match expected_extra_bits.
  • NEEDS_RECOVERY_E Entropy-invalidated and WC_RNG_LOCK_ENTROPY_INVALIDATED is not in expected_extra_bits.
  • BAD_MUTEX_E (WC_RNG_HAVE_LOCK_FULL_MUTEX) The outer mutex failed.
  • UNEXPECTED_STATE_E Spurious acquisition failure; retry.

function wc_RNG_lock_put

int wc_RNG_lock_put(
    WC_RNG * rng,
    WC_RNG_lock_arg_t extra_bits
)

Release rng's lock latch, clearing the supplied extra bits atomically with the release.

Parameters:

  • rng The RNG object to unlock.
  • extra_bits Caller-defined bits to clear with the release, or 0.

See:

Return:

  • 0 Success
  • BAD_FUNC_ARG rng is null.
  • OBJECT_NOT_LOCKED_E The latch is not held.
  • NEEDS_RECOVERY_E Released successfully; informational notice that the instance is entropy-invalidated.

function wc_RNG_lock_put_conditional

int wc_RNG_lock_put_conditional(
    WC_RNG * rng,
    WC_RNG_lock_arg_t expected_extra_bits,
    WC_RNG_lock_arg_t want_extra_bits
)

The conditional form of wc_RNG_lock_put(): release only if the current extra bits equal expected_extra_bits, atomically replacing them with want_extra_bits on success.

Parameters:

  • rng The RNG object to unlock.
  • expected_extra_bits The extra bits required for release.
  • want_extra_bits The extra bits to install on release.

See:

Return:

  • 0 Success
  • BAD_FUNC_ARG rng is null.
  • BUSY_E The extra bits did not match expected_extra_bits.
  • OBJECT_NOT_LOCKED_E The latch is not held.
  • NEEDS_RECOVERY_E Released successfully; informational notice that the instance is entropy-invalidated.
  • UNEXPECTED_STATE_E Spurious release failure.

function wc_RNG_lock_read

int wc_RNG_lock_read(
    WC_RNG * rng,
    WC_RNG_lock_arg_t * state
)

Read rng's lock word: the held/required latch bits, the entropy-invalidated bit, and any caller extra bits. The snapshot is racy by design.

Parameters:

  • rng The RNG object to interrogate.
  • state Receives the lock word.

See:

Return:

  • 0 Success
  • BAD_FUNC_ARG rng or state is null.

function wc_RNG_lock_set_extra

int wc_RNG_lock_set_extra(
    WC_RNG * rng,
    WC_RNG_lock_arg_t extra_bits
)

Atomically set (or) the supplied caller extra bits in rng's lock word. The caller should hold the latch.

Parameters:

  • rng The RNG object to modify.
  • extra_bits The bits to set.

See:

Return:

  • 0 Success
  • BAD_FUNC_ARG rng is null.

function wc_RNG_lock_add_extra

int wc_RNG_lock_add_extra(
    WC_RNG * rng,
    WC_RNG_lock_arg_t extra_bits
)

Atomically add the supplied value to the caller extra-bits field of rng's lock word – for counters carried above WC_RNG_LOCK_EXTRA_SHIFT.

Parameters:

  • rng The RNG object to modify.
  • extra_bits The value to add.

See:

Return:

  • 0 Success
  • BAD_FUNC_ARG rng is null.

function wc_RNG_lock_clear_extra

int wc_RNG_lock_clear_extra(
    WC_RNG * rng,
    WC_RNG_lock_arg_t extra_bits
)

Atomically clear the supplied caller extra bits in rng's lock word.

Parameters:

  • rng The RNG object to modify.
  • extra_bits The bits to clear.

See:

Return:

  • 0 Success
  • BAD_FUNC_ARG rng is null.

function wc_RNG_invalidate_entropy

int wc_RNG_invalidate_entropy(
    WC_RNG * rng
)

Mark rng's seed material untrusted – for VM fork/resume and similar duplication events – opening a new invalidation epoch: banked and pooled pre-event material is purged and wiped first, then the entropy-invalidated bit is latched in the lock word. An invalidated instance refuses service (NEEDS_RECOVERY_E) until recovery-reseeded. Latch or condemn: on any error return the latch is down, and the instance is instead condemned (status DRBG_FAILED). A condemned bank instance is retired and recovered by the entropy daemon; a condemned leaf gets no daemon rescue – its owner sees RNG_FAILURE_E from subsequent operations and recovers it with wc_FreeRng() then wc_InitRng*().

Parameters:

  • rng The RNG object to invalidate.

See:

Return:

  • 0 Success: purges complete, latch asserted.
  • BAD_FUNC_ARG rng is null.
  • RNG_FAILURE_E (or other nonzero) A purge or the latch failed; the instance is condemned as above.

Example

// VM-resume handler
(void)wc_RNG_invalidate_entropy(rng);
// subsequent wc_RNG_lock_get() returns NEEDS_RECOVERY_E until recovery

function wc_RNG_register_free_hook

int wc_RNG_register_free_hook(
    WC_RNG * rng,
    wc_RNG_free_hook_cb_t free_hook,
    void * arg
)

Register a callback fired by wc_FreeRng() at teardown – for external registries (e.g. a kernel_module registry that must reach every live RNG on a VM duplication event) that need to drop their reference when the object dies.

Parameters:

  • rng The RNG object to hook.
  • free_hook The callback.
  • arg Opaque argument passed to the callback.

See:

Return:

  • 0 Success
  • BAD_FUNC_ARG rng or free_hook is null.

function wc_RNG_Pool_Alloc

int wc_RNG_Pool_Alloc(
    WC_RNG * rng,
    word32 size
)

Attach a random pool to rng: a buffer of size bytes of pre-generated output, filled by wc_RNG_Pool_Collect() and drained atomic_context_safely by wc_RNG_Pool_Extract(). The pool is released with the instance.

Parameters:

  • rng The RNG object to equip.
  • size Pool capacity in bytes.

See:

Return:

  • 0 Success
  • BAD_FUNC_ARG rng is null, or size is 0 or out of range.
  • MEMORY_E Allocation failed.
  • ALREADY_E The pool is already allocated.

Example

wc_RNG_Pool_Alloc(rng, 256);
wc_RNG_Pool_Collect(rng, 256);      // sleepable context
word32 n = 16;
if (wc_RNG_Pool_Extract(rng, out, &n) == 0) {
    // n bytes delivered, atomic-context-safe
}

function wc_RNG_Pool_Collect

int wc_RNG_Pool_Collect(
    WC_RNG * rng,
    word32 n
)

Generate up to n bytes into rng's pool from rng itself. The collect/extract hand-off is arbitrated by an atomic aperture word, so a single collector is safe alongside concurrent extractors.

Parameters:

  • rng The RNG object whose pool to fill.
  • n Maximum bytes to collect this call.

See:

Return:

  • 0 Success
  • ALREADY_E The pool is full or being drained.
  • BAD_FUNC_ARG rng is null, has no pool, or n is 0.

function wc_RNG_Pool_Collect2

int wc_RNG_Pool_Collect2(
    WC_RNG * rng_dest,
    WC_RNG * rng_src,
    word32 n
)

The two-instance form of wc_RNG_Pool_Collect(): fill rng_dest's pool with output drawn from rng_src – so a service instance's pool can be topped up by a daemon-owned generator.

Parameters:

  • rng_dest The RNG object whose pool to fill.
  • rng_src The RNG object to draw output from.
  • n Maximum bytes to collect this call.

See: wc_RNG_Pool_Collect

Return:

  • 0 Success
  • ALREADY_E The pool is full or being drained.
  • BAD_FUNC_ARG rng_dest or rng_src is null, or rng_dest has no pool, or n is 0.
  • BAD_STATE_E The pool is not allocated.
  • NOT_READY_E The source could not serve; retry later.

function wc_RNG_Pool_Extract

int wc_RNG_Pool_Extract(
    WC_RNG * rng,
    byte * out,
    word32 * n
)

Drain up to n bytes from rng's pool into out – atomic-context-safe. On success n reports the bytes actually delivered; on any error return *n is left unmodified.

Parameters:

  • rng The RNG object whose pool to drain.
  • out Receives the output.
  • n In: bytes requested; out: bytes delivered.

See:

Return:

  • 0 Success
  • NOT_READY_E The pool is empty or being filled.
  • BAD_FUNC_ARG rng, out, or n is null, or rng has no pool.
  • BAD_STATE_E The pool is not allocated.
  • RNG_FAILURE_E The instance is out of service.

function wc_RNG_Pool_Current

int wc_RNG_Pool_Current(
    WC_RNG * rng,
    word32 * n
)

Report the pool's current fill in bytes. The snapshot is racy by design.

Parameters:

  • rng The RNG object to interrogate.
  • n Receives the fill.

See: wc_RNG_Pool_Extract

Return:

  • 0 Success
  • BAD_FUNC_ARG rng or n is null, or rng has no pool.

function wc_rng_debug_stats_snap

int wc_rng_debug_stats_snap(
    struct wc_rng_debug_stats_snapshot * s,
    const WC_RNG * rng
)

Snapshot the global RNG debug counters (WC_RNG_DEBUG_STATS) – seeds and reseeds by provenance, generates, pool and bank traffic – into s, for later delta accounting with wc_rng_debug_stats_sum().

Parameters:

  • s Receives the snapshot.
  • rng Optional instance for per-instance context, or null.

See:

Return:

  • 0 Success
  • BAD_FUNC_ARG s is null.

function wc_rng_debug_stats_restore

int wc_rng_debug_stats_restore(
    const struct wc_rng_debug_stats_snapshot * s,
    WC_RNG * rng
)

Restore the global RNG debug counters from a snapshot – so a test can unwind its own accounting.

Parameters:

  • s The snapshot to restore from.
  • rng Optional instance for per-instance context, or null.

See: wc_rng_debug_stats_snap

Return:

  • 0 Success
  • BAD_FUNC_ARG s is null.

function wc_rng_debug_stats_sum

int wc_rng_debug_stats_sum(
    struct wc_rng_debug_stats_snapshot * s,
    const WC_RNG * rng
)

Accumulate the current global RNG debug counters into s – combined with a prior wc_rng_debug_stats_snap(), a delta accounting of the interval's RNG activity.

Parameters:

  • s The snapshot to accumulate into.
  • rng Optional instance for per-instance context, or null.

See: wc_rng_debug_stats_snap

Return:

  • 0 Success
  • BAD_FUNC_ARG s is null.

Source code


int  wc_InitNetRandom(const char* configFile, wnr_hmac_key hmac_cb, int timeout);

int  wc_FreeNetRandom(void);

int  wc_InitRng(WC_RNG* rng);

int  wc_RNG_GenerateBlock(WC_RNG* rng, byte* output, word32 sz);

int  wc_RNG_GenerateByte(WC_RNG* rng, byte* b);

int  wc_FreeRng(WC_RNG* rng);

int wc_RNG_HealthTest(int reseed, const byte* seedA, word32 seedASz,
        const byte* seedB, word32 seedBSz,
        byte* output, word32 outputSz);

int wc_GenerateSeed(OS_Seed* os, byte* output, word32 sz);

WC_RNG* wc_rng_new(byte* nonce, word32 nonceSz, void* heap);

int wc_rng_new_ex(WC_RNG **rng, byte* nonce, word32 nonceSz, void* heap,
                 int devId);

void wc_rng_free(WC_RNG* rng);

int wc_InitRng_ex(WC_RNG* rng, void* heap, int devId);

int wc_InitRngNonce(WC_RNG* rng, const byte* nonce, word32 nonceSz);

int wc_InitRngNonce_ex(WC_RNG* rng, const byte* nonce, word32 nonceSz,
                      void* heap, int devId);

int wc_SetSeed_Cb(wc_RngSeed_Cb cb);

int wc_RNG_DRBG_Reseed(WC_RNG* rng, const byte* seed, word32 seedSz);

int wc_RNG_TestSeed(const byte* seed, word32 seedSz);

int wc_RNG_HealthTest_ex(int reseed, const byte* nonce, word32 nonceSz,
                        const byte* seedA, word32 seedASz,
                        const byte* seedB, word32 seedBSz, byte* output,
                        word32 outputSz, void* heap, int devId);

int wc_RNG_HealthTest_SHA512(int reseed, const byte* seedA, word32 seedASz,
        const byte* seedB, word32 seedBSz,
        byte* output, word32 outputSz);

int wc_RNG_HealthTest_SHA512_ex(int reseed, const byte* nonce, word32 nonceSz,
        const byte* persoString, word32 persoStringSz,
        const byte* seedA, word32 seedASz,
        const byte* seedB, word32 seedBSz,
        const byte* additionalA, word32 additionalASz,
        const byte* additionalB, word32 additionalBSz,
        byte* output, word32 outputSz,
        void* heap, int devId);

int wc_Sha256Drbg_Disable(void);

int wc_Sha256Drbg_Enable(void);

int wc_Sha256Drbg_IsDisabled(void);

int wc_Sha512Drbg_Disable(void);

int wc_Sha512Drbg_Enable(void);

int wc_Sha512Drbg_IsDisabled(void);

int wc_InitRng_ex2(WC_RNG* rng, void* heap, int devId, word32 flags);

int wc_InitRngNonce_ex2(WC_RNG* rng, const byte* nonce, word32 nonceSz,
                        const byte *perso, word32 persoSz,
                        void* heap, int devId, word32 flags);

int wc_RNG_GetStatus(const WC_RNG* rng);

int wc_RNG_DRBG_Present(const WC_RNG* rng);

int wc_RNG_DRBG_GetReseedCtr(const WC_RNG* rng, wc_drbg_reseed_ctr_t* reseedCtr);

int wc_RNG_DRBG_ScheduleReseed(WC_RNG* rng);

int wc_RNG_DRBG_Reseed_Now(WC_RNG* rng, const byte* nonce, word32 nonceSz);

int wc_RNG_DRBG_Reseed_Nonce(WC_RNG* rng, const byte* seed, word32 seedSz,
                             const byte *nonce, word32 nonceSz);

int wc_RNG_DRBG_Stir(WC_RNG* rng, const byte* seed, word32 seedSz);

int wc_RNG_DRBG_Stir_Nonce(WC_RNG* rng, const byte* seed,
                                        word32 seedSz, const byte *nonce,
                                        word32 nonceSz);

int wc_InitRngRBGC(WC_RNG* child, WC_RNG* parent, word32 flags);

int wc_InitRngNonceRBGC(WC_RNG* child, WC_RNG* parent, const byte* nonce,
                        word32 nonceSz, word32 flags);

int wc_InitRngRBGC_New(WC_RNG** child, WC_RNG* parent, word32 flags);

int wc_InitRngNonceRBGC_New(WC_RNG** child, WC_RNG* parent, const byte* nonce,
                            word32 nonceSz, word32 flags);

int wc_RNG_DRBG_ReseedRBGC(WC_RNG* rng, WC_RNG* root, const byte* nonce,
                           word32 nonceSz);

int wc_RNG_DRBG_StirRBGC(WC_RNG* rng, WC_RNG* root,
                                      const byte* nonce, word32 nonceSz);

int wc_RNG_DRBG_GetRBGCStratum(const WC_RNG* rng);

int wc_RNG_DRBG_GetNextSeedRBGCStratum(const WC_RNG* rng);

int wc_RNG_DRBG_NextSeedGenerate(WC_RNG* rng, word32 n);

int wc_RNG_DRBG_NextSeedGenerate_RBGC(WC_RNG* rng, WC_RNG *root, word32 n);

int wc_RNG_DRBG_NextSeedCurrent(WC_RNG* rng, WC_ATOMIC_INT_ARG* n);

int wc_RNG_DRBG_NextSeedNow(WC_RNG* rng);

int wc_RNG_DRBG_NextSeedNow_Nonce(WC_RNG* rng, const byte* nonce,
                                  word32 nonceSz);

int wc_RNG_DRBG_NextStirStore(WC_RNG* rng, const byte *nonce,
                                        word32 nonceSz);

int wc_RNG_DRBG_NextStirNow(WC_RNG* rng);

int wc_RNG_lock_get(WC_RNG* rng, WC_RNG_lock_arg_t extra_bits);

int wc_RNG_lock_get_conditional(WC_RNG* rng,
                                WC_RNG_lock_arg_t expected_extra_bits,
                                WC_RNG_lock_arg_t want_extra_bits);

int wc_RNG_lock_put(WC_RNG* rng, WC_RNG_lock_arg_t extra_bits);

int wc_RNG_lock_put_conditional(WC_RNG* rng,
                                WC_RNG_lock_arg_t expected_extra_bits,
                                WC_RNG_lock_arg_t want_extra_bits);

int wc_RNG_lock_read(WC_RNG* rng, WC_RNG_lock_arg_t* state);

int wc_RNG_lock_set_extra(WC_RNG* rng, WC_RNG_lock_arg_t extra_bits);

int wc_RNG_lock_add_extra(WC_RNG* rng, WC_RNG_lock_arg_t extra_bits);

int wc_RNG_lock_clear_extra(WC_RNG* rng, WC_RNG_lock_arg_t extra_bits);

int wc_RNG_invalidate_entropy(WC_RNG* rng);

int wc_RNG_register_free_hook(WC_RNG* rng, wc_RNG_free_hook_cb_t free_hook,
                              void *arg);

int wc_RNG_Pool_Alloc(WC_RNG* rng, word32 size);

int wc_RNG_Pool_Collect(WC_RNG* rng, word32 n);

int wc_RNG_Pool_Collect2(WC_RNG* rng_dest, WC_RNG* rng_src, word32 n);

int wc_RNG_Pool_Extract(WC_RNG* rng, byte* out, word32* n);

int wc_RNG_Pool_Current(WC_RNG* rng, word32* n);

int wc_rng_debug_stats_snap(struct wc_rng_debug_stats_snapshot *s,
                            const WC_RNG *rng);

int wc_rng_debug_stats_restore(const struct wc_rng_debug_stats_snapshot *s,
                               WC_RNG *rng);

int wc_rng_debug_stats_sum(struct wc_rng_debug_stats_snapshot *s,
                           const WC_RNG *rng);

Updated on 2026-09-21 at 01:13:30 +0000