Random Number Generation

Functions
WOLFSSL_API int	wc_InitNetRandom (const char *, wnr_hmac_key, int)
	Init global Whitewood netRandom context. More...
WOLFSSL_API int	wc_FreeNetRandom (void)
	Free global Whitewood netRandom context. More...
WOLFSSL_API 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...
WOLFSSL_API int	wc_RNG_GenerateBlock (WC_RNG *, byte *, word32 sz)
	Copies a sz bytes of pseudorandom data to output. Will reseed rng if needed (blocking). More...
WOLFSSL_API int	wc_RNG_GenerateByte (WC_RNG *, byte *)
	Calls wc_RNG_GenerateBlock to copy a byte of pseudorandom data to b. Will reseed rng if needed. More...
WOLFSSL_API 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...
WOLFSSL_API 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()

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

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

WOLFSSL_API int wc_InitNetRandom	(	const char *	,
		wnr_hmac_key	,
		int
	)

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 *

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

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

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

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

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