Functions
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
noneNo 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
rngrandom 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
configFilePath to configuration file
hmac_cbOptional to create HMAC callback.
timeoutA 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 occured
}
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
rngrandom 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()

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
rngrandom number generator initialized with wc_InitRng
outputbuffer to which the block is copied
szsize 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
rngrandom number generator initialized with wc_InitRng
bone 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
intreseed: if set, will test reseed functionality
entropyAentropy to instantiate drgb with
entropyASzsize of entropyA in bytes
entropyBIf reseed set, drbg will be reseeded with entropyB
entropyBSzsize of entropyB in bytes
outputinitialized to random data seeded with entropyB if seedrandom is set, and entropyA otherwise
outputSzlength 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