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 * ) 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. |
Attributes
Name | |
---|---|
WC_RNG byte * | b |
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:
- wc_InitRng
- wc_rng_free
- wc_FreeRng
- wc_RNG_HealthTest
- wc_InitRngCavium
- wc_InitRng
- wc_RNG_GenerateBlock
- wc_FreeRng
- wc_RNG_HealthTest
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
Attributes Documentation
variable b
WC_RNG byte * b;
Source code
int wc_InitNetRandom(const char* configFile, wnr_hmac_key hmac_cb, int timeout);
int wc_FreeNetRandom(void);
int wc_InitRng(WC_RNG*);
int wc_RNG_GenerateBlock(WC_RNG* rng, byte* b, word32 sz);
WC_RNG* wc_rng_new(byte* nonce, word32 nonceSz, void* heap)
int wc_RNG_GenerateByte(WC_RNG* rng, byte* b);
int wc_FreeRng(WC_RNG*);
WC_RNG* wc_rng_free(WC_RNG* rng);
int wc_RNG_HealthTest(int reseed,
const byte* entropyA, word32 entropyASz,
const byte* entropyB, word32 entropyBSz,
byte* output, word32 outputSz);
Updated on 2024-12-02 at 01:16:31 +0000