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

• wc_InitRngCavium
• wc_RNG_GenerateBlock
• wc_RNG_GenerateByte
• wc_FreeRng
• wc_RNG_HealthTest

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:

• wc_InitRngCavium, wc_InitRng
• wc_RNG_GenerateByte
• wc_FreeRng
• wc_RNG_HealthTest

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:

• wc_InitRngCavium
• wc_InitRng
• wc_RNG_GenerateBlock
• wc_FreeRng
• wc_RNG_HealthTest

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:

• wc_InitRngCavium
• wc_InitRng
• wc_RNG_GenerateBlock
• wc_RNG_GenerateByte,
• wc_RNG_HealthTest

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:

• wc_InitRngCavium
• wc_InitRng
• wc_RNG_GenerateBlock
• wc_RNG_GenerateByte
• wc_FreeRng

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

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* b, 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, byte* nonce, word32 nonceSz);

int wc_InitRngNonce_ex(WC_RNG* rng, 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_Entropy_GetRawEntropy(unsigned char* raw, int cnt);

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

int wc_Entropy_OnDemandTest(void);

---

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