329 lines
8.3 KiB
C
329 lines
8.3 KiB
C
/*!
|
||
\ingroup Random
|
||
|
||
\brief Init global Whitewood netRandom context
|
||
|
||
\return 0 Success
|
||
\return BAD_FUNC_ARG Either configFile is null or timeout is negative.
|
||
\return RNG_FAILURE_E There was a failure initializing the rng.
|
||
|
||
\param configFile Path to configuration file
|
||
\param hmac_cb Optional to create HMAC callback.
|
||
\param timeout A timeout duration.
|
||
|
||
_Example_
|
||
\code
|
||
char* config = "path/to/config/example.conf";
|
||
int time = // Some sufficient timeout value;
|
||
|
||
if (wc_InitNetRandom(config, NULL, time) != 0)
|
||
{
|
||
// Some error occurred
|
||
}
|
||
\endcode
|
||
|
||
\sa wc_FreeNetRandom
|
||
*/
|
||
WOLFSSL_API int wc_InitNetRandom(const char*, wnr_hmac_key, int);
|
||
|
||
/*!
|
||
\ingroup Random
|
||
|
||
\brief Free global Whitewood netRandom context.
|
||
|
||
\return 0 Success
|
||
\return BAD_MUTEX_E Error locking mutex on wnr_mutex
|
||
|
||
\param none No returns.
|
||
|
||
_Example_
|
||
\code
|
||
int ret = wc_FreeNetRandom();
|
||
if(ret != 0)
|
||
{
|
||
// Handle the error
|
||
}
|
||
\endcode
|
||
|
||
\sa wc_InitNetRandom
|
||
*/
|
||
WOLFSSL_API int wc_FreeNetRandom(void);
|
||
|
||
/*!
|
||
\ingroup Random
|
||
|
||
\brief 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.
|
||
|
||
\return 0 on success.
|
||
\return MEMORY_E XMALLOC failed
|
||
\return WINCRYPT_E wc_GenerateSeed: failed to acquire context
|
||
\return CRYPTGEN_E wc_GenerateSeed: failed to get random
|
||
\return BAD_FUNC_ARG wc_RNG_GenerateBlock input is null or sz exceeds
|
||
MAX_REQUEST_LEN
|
||
\return DRBG_CONT_FIPS_E wc_RNG_GenerateBlock: Hash_gen returned
|
||
DRBG_CONT_FAILURE
|
||
\return RNG_FAILURE_E wc_RNG_GenerateBlock: Default error. rng’s
|
||
status originally not ok, or set to DRBG_FAILED
|
||
|
||
\param rng random number generator to be initialized for use
|
||
with a seed and key cipher
|
||
|
||
_Example_
|
||
\code
|
||
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;
|
||
}
|
||
\endcode
|
||
|
||
\sa wc_InitRngCavium
|
||
\sa wc_RNG_GenerateBlock
|
||
\sa wc_RNG_GenerateByte
|
||
\sa wc_FreeRng
|
||
\sa wc_RNG_HealthTest
|
||
*/
|
||
WOLFSSL_API int wc_InitRng(WC_RNG*);
|
||
|
||
/*!
|
||
\ingroup Random
|
||
|
||
\brief Copies a sz bytes of pseudorandom data to output. Will
|
||
reseed rng if needed (blocking).
|
||
|
||
\return 0 on success
|
||
\return BAD_FUNC_ARG an input is null or sz exceeds MAX_REQUEST_LEN
|
||
\return DRBG_CONT_FIPS_E Hash_gen returned DRBG_CONT_FAILURE
|
||
\return RNG_FAILURE_E Default error. rng’s status originally not
|
||
ok, or set to DRBG_FAILED
|
||
|
||
\param rng random number generator initialized with wc_InitRng
|
||
\param output buffer to which the block is copied
|
||
\param sz size of output in bytes
|
||
|
||
_Example_
|
||
\code
|
||
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!
|
||
}
|
||
\endcode
|
||
|
||
\sa wc_InitRngCavium, wc_InitRng
|
||
\sa wc_RNG_GenerateByte
|
||
\sa wc_FreeRng
|
||
\sa wc_RNG_HealthTest
|
||
*/
|
||
WOLFSSL_API int wc_RNG_GenerateBlock(WC_RNG*, byte*, word32 sz);
|
||
|
||
/*!
|
||
\ingroup Random
|
||
|
||
\brief Creates a new WC_RNG structure.
|
||
|
||
|
||
\return WC_RNG structure on success
|
||
\return NULL on error
|
||
|
||
|
||
\param heap pointer to a heap identifier
|
||
\param nonce pointer to the buffer containing the nonce
|
||
\param nonceSz length of the nonce
|
||
|
||
_Example_
|
||
\code
|
||
RNG rng;
|
||
byte nonce[] = { initialize nonce };
|
||
word32 nonceSz = sizeof(nonce);
|
||
|
||
wc_rng_new(&nonce, nonceSz, &heap);
|
||
|
||
|
||
\endcode
|
||
|
||
\sa wc_InitRng
|
||
\sa wc_rng_free
|
||
\sa wc_FreeRng
|
||
\sa wc_RNG_HealthTest
|
||
*/
|
||
WOLFSSL_API WC_RNG* wc_rng_new(byte* nonce, word32 nonceSz, void* heap)
|
||
|
||
/*!
|
||
\ingroup Random
|
||
|
||
\brief Calls wc_RNG_GenerateBlock to copy a byte of pseudorandom
|
||
data to b. Will reseed rng if needed.
|
||
|
||
\return 0 on success
|
||
\return BAD_FUNC_ARG an input is null or sz exceeds MAX_REQUEST_LEN
|
||
\return DRBG_CONT_FIPS_E Hash_gen returned DRBG_CONT_FAILURE
|
||
\return RNG_FAILURE_E Default error. rng’s status originally not
|
||
ok, or set to DRBG_FAILED
|
||
|
||
\param rng: random number generator initialized with wc_InitRng
|
||
\param b one byte buffer to which the block is copied
|
||
|
||
_Example_
|
||
\code
|
||
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!
|
||
}
|
||
\endcode
|
||
|
||
\sa wc_InitRngCavium
|
||
\sa wc_InitRng
|
||
\sa wc_RNG_GenerateBlock
|
||
\sa wc_FreeRng
|
||
\sa wc_RNG_HealthTest
|
||
*/
|
||
WOLFSSL_API int wc_RNG_GenerateByte(WC_RNG*, byte*);
|
||
|
||
/*!
|
||
\ingroup Random
|
||
|
||
\brief Should be called when RNG no longer needed in order to securely
|
||
free drgb. Zeros and XFREEs rng-drbg.
|
||
|
||
\return 0 on success
|
||
\return BAD_FUNC_ARG rng or rng->drgb null
|
||
\return RNG_FAILURE_E Failed to deallocated drbg
|
||
|
||
\param rng random number generator initialized with wc_InitRng
|
||
|
||
_Example_
|
||
\code
|
||
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!
|
||
}
|
||
\endcode
|
||
|
||
\sa wc_InitRngCavium
|
||
\sa wc_InitRng
|
||
\sa wc_RNG_GenerateBlock
|
||
\sa wc_RNG_GenerateByte,
|
||
\sa wc_RNG_HealthTest
|
||
*/
|
||
WOLFSSL_API int wc_FreeRng(WC_RNG*);
|
||
|
||
/*!
|
||
\ingroup Random
|
||
|
||
\brief Should be called when RNG no longer needed in order to securely
|
||
free rng.
|
||
|
||
|
||
\param rng random number generator initialized with wc_InitRng
|
||
|
||
_Example_
|
||
\code
|
||
RNG rng;
|
||
byte nonce[] = { initialize nonce };
|
||
word32 nonceSz = sizeof(nonce);
|
||
|
||
rng = wc_rng_new(&nonce, nonceSz, &heap);
|
||
|
||
// use rng
|
||
|
||
wc_rng_free(&rng);
|
||
|
||
\endcode
|
||
|
||
\sa wc_InitRng
|
||
\sa wc_rng_new
|
||
\sa wc_FreeRng
|
||
\sa wc_RNG_HealthTest
|
||
*/
|
||
WOLFSSL_API WC_RNG* wc_rng_free(WC_RNG* rng);
|
||
|
||
/*!
|
||
\ingroup Random
|
||
|
||
\brief Creates and tests functionality of drbg.
|
||
|
||
\return 0 on success
|
||
\return BAD_FUNC_ARG entropyA and output must not be null. If reseed
|
||
set entropyB must not be null
|
||
\return -1 test failed
|
||
|
||
\param int reseed: if set, will test reseed functionality
|
||
\param entropyA: entropy to instantiate drgb with
|
||
\param entropyASz: size of entropyA in bytes
|
||
\param entropyB: If reseed set, drbg will be reseeded with entropyB
|
||
\param entropyBSz: size of entropyB in bytes
|
||
\param output: initialized to random data seeded with entropyB if
|
||
seedrandom is set, and entropyA otherwise
|
||
\param outputSz: length of output in bytes
|
||
|
||
_Example_
|
||
\code
|
||
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
|
||
\endcode
|
||
|
||
\sa wc_InitRngCavium
|
||
\sa wc_InitRng
|
||
\sa wc_RNG_GenerateBlock
|
||
\sa wc_RNG_GenerateByte
|
||
\sa wc_FreeRng
|
||
*/
|
||
WOLFSSL_API int wc_RNG_HealthTest(int reseed,
|
||
const byte* entropyA, word32 entropyASz,
|
||
const byte* entropyB, word32 entropyBSz,
|
||
byte* output, word32 outputSz);
|