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:

• wc_InitRng
• wc_rng_new
• wc_FreeRng
• wc_RNG_HealthTest

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-20 at 01:22:24 +0000