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 * ) 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).
WC_RNG *	wc_rng_new(byte * nonce, word32 nonceSz, void * heap) Creates a new WC_RNG structure.
int	wc_FreeRng(WC_RNG * ) Should be called when RNG no longer needed in order to securely free drgb. Zeros and XFREEs rng-drbg.
WC_RNG *	wc_rng_free(WC_RNG * rng) Should be called when RNG no longer needed in order to securely free rng.
int	wc_RNG_HealthTest(int reseed, const byte * entropyA, word32 entropyASz, const byte * entropyB, word32 entropyBSz, byte * output, word32 outputSz) Creates and tests functionality of drbg.

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

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_new

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

Creates a new WC_RNG structure.

Parameters:

heap pointer to a heap identifier
nonce pointer to the buffer containing the nonce
nonceSz length of the nonce
rng random number generator initialized with wc_InitRng
b one byte buffer to which the block is copied

See:

Return:

WC_RNG structure on success
NULL on error
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;
byte nonce[] = { initialize nonce };
word32 nonceSz = sizeof(nonce);

wc_rng_new(&nonce, nonceSz, &heap);

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

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

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_free

WC_RNG * wc_rng_free(
    WC_RNG * rng
)

Should be called when RNG no longer needed in order to securely free rng.

Parameters:

rng random number generator initialized with wc_InitRng

See:

Example

RNG  rng;
byte nonce[] = { initialize nonce };
word32 nonceSz = sizeof(nonce);

rng = wc_rng_new(&nonce, nonceSz, &heap);

// use rng

wc_rng_free(&rng);

function wc_RNG_HealthTest

int wc_RNG_HealthTest(
    int reseed,
    const byte * entropyA,
    word32 entropyASz,
    const byte * entropyB,
    word32 entropyBSz,
    byte * output,
    word32 outputSz
)

Creates and tests functionality of drbg.

Parameters:

int reseed: if set, will test reseed functionality
entropyA entropy to instantiate drgb with
entropyASz size of entropyA in bytes
entropyB If reseed set, drbg will be reseeded with entropyB
entropyBSz size of entropyB in bytes
output initialized to random data seeded with entropyB if seedrandom is set, and entropyA 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 entropyA and output must not be null. If reseed set entropyB 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

Updated on 2024-11-22 at 01:12:39 +0000