Random Number Generation

Functions
int	wc_InitNetRandom (const char *configFile, wnr_hmac_key hmac_cb, int timeout)
	Init global Whitewood netRandom context. More...
int	wc_FreeNetRandom (void)
	Free global Whitewood netRandom context. More...
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. More...
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). More...
WC_RNG *	wc_rng_new (byte *nonce, word32 nonceSz, void *heap) int wc_RNG_GenerateByte(WC_RNG *rng
	Creates a new WC_RNG structure. More...
int	wc_FreeRng (WC_RNG *)
	Should be called when RNG no longer needed in order to securely free drgb. Zeros and XFREEs rng-drbg. More...
WC_RNG *	wc_rng_free (WC_RNG *rng)
	Should be called when RNG no longer needed in order to securely free rng. More...
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. More...

Detailed Description

Function Documentation

wc_FreeNetRandom()

int wc_FreeNetRandom

(

void

)

Free global Whitewood netRandom context.

Returns

0 Success

BAD_MUTEX_E Error locking mutex on wnr_mutex

Parameters

none	No returns.

Example

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

See also

wc_InitNetRandom

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.

Returns

0 on success

BAD_FUNC_ARG rng or rng->drgb null

RNG_FAILURE_E Failed to deallocated drbg

Parameters

rng	random number generator initialized with wc_InitRng

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!
}

See also

wc_InitRngCavium

wc_InitRng

wc_RNG_GenerateBlock

wc_RNG_GenerateByte,

wc_RNG_HealthTest

wc_InitNetRandom()

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

Init global Whitewood netRandom context.

Returns

0 Success

BAD_FUNC_ARG Either configFile is null or timeout is negative.

RNG_FAILURE_E There was a failure initializing the rng.

Parameters

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

Example

char* config = "path/to/config/example.conf";
int time = // Some sufficient timeout value;
 
if (wc_InitNetRandom(config, NULL, time) != 0)
{
    // Some error occurred
}

See also

wc_FreeNetRandom

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.

Returns

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

Parameters

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

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;
}

See also

wc_InitRngCavium

wc_RNG_GenerateBlock

wc_RNG_GenerateByte

wc_FreeRng

wc_RNG_HealthTest

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

Example

RNG  rng;
byte nonce[] = { initialize nonce };
word32 nonceSz = sizeof(nonce);
 
rng = wc_rng_new(&nonce, nonceSz, &heap);
 
// use rng
 
wc_rng_free(&rng);

See also

wc_InitRng

wc_rng_new

wc_FreeRng

wc_RNG_HealthTest

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

Returns

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

Parameters

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

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!
}

See also

wc_InitRngCavium, wc_InitRng

wc_RNG_GenerateByte

wc_FreeRng

wc_RNG_HealthTest

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.

Returns

0 on success

BAD_FUNC_ARG entropyA and output must not be null. If reseed set entropyB must not be null

-1 test failed

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

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

See also

wc_InitRngCavium

wc_InitRng

wc_RNG_GenerateBlock

wc_RNG_GenerateByte

wc_FreeRng

wc_rng_new()

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

Creates a new WC_RNG structure.

Returns

WC_RNG structure on success

NULL on error

Parameters

heap	pointer to a heap identifier
nonce	pointer to the buffer containing the nonce
nonceSz	length of the nonce

Example

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

See also

wc_InitRng

wc_rng_free

wc_FreeRng

wc_RNG_HealthTest

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

Returns

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

Parameters

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

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!
}

See also

wc_InitRngCavium

wc_InitRng

wc_RNG_GenerateBlock

wc_FreeRng

wc_RNG_HealthTest