Skip to content

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:

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:

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:

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:

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:

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-03-19 at 01:20:40 +0000