Random Number Generation

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 * b, 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, byte * nonce, word32 nonceSz) Initializes WC_RNG with nonce.
int	wc_InitRngNonce_ex(WC_RNG * rng, 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_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.

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 * b,
    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,
    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,
    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
RNG_FAILURE_E Validation 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_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: wc_Entropy_Get

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: wc_Entropy_GetRawEntropy

Return:

0 On success
BAD_FUNC_ARG If entropy is NULL
RNG_FAILURE_E Failed

Example

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

function wc_Entropy_OnDemandTest

int wc_Entropy_OnDemandTest(
    void 
)

Tests entropy source on demand.

See: wc_Entropy_Get

Return:

0 On success
RNG_FAILURE_E Test failed

Example

int ret = wc_Entropy_OnDemandTest();

Updated on 2025-12-31 at 01:16:02 +0000