mirror of
https://github.com/wolfSSL/wolfssl.git
synced 2026-01-27 08:52:23 +01:00
20b2fd200f
Update ret code to match docs and update docs Replace magic numbers with appropriate define Define MAX_ENTROPY_BITS when MEMUSE not enabled Fix type cast windows detection Older FIPS modules still need the old check CodeSpell you're wrong, that is what I want to name my variable Turn the hostap into a manual dispatch until it gets fixed Upon closer review we can not skip the test when memuse enabled Fix whitespace stuff found by multitest More syntax things Correct comments based on latest findings
586 lines
14 KiB
C
586 lines
14 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
|
||
*/
|
||
int wc_InitNetRandom(const char* configFile, wnr_hmac_key hmac_cb, int timeout);
|
||
|
||
/*!
|
||
\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
|
||
*/
|
||
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
|
||
*/
|
||
int wc_InitRng(WC_RNG* 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
|
||
*/
|
||
int wc_RNG_GenerateBlock(WC_RNG* rng, byte* b, word32 sz);
|
||
|
||
/*!
|
||
\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
|
||
*/
|
||
int wc_RNG_GenerateByte(WC_RNG* rng, byte* b);
|
||
|
||
/*!
|
||
\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
|
||
*/
|
||
int wc_FreeRng(WC_RNG* rng);
|
||
|
||
/*!
|
||
\ingroup Random
|
||
|
||
\brief Creates and tests functionality of drbg.
|
||
|
||
\return 0 on success
|
||
\return BAD_FUNC_ARG seedA and output must not be null. If reseed
|
||
set seedB must not be null
|
||
\return -1 test failed
|
||
|
||
\param int reseed: if set, will test reseed functionality
|
||
\param seedA: seed to instantiate drgb with
|
||
\param seedASz: size of seedA in bytes
|
||
\param seedB: If reseed set, drbg will be reseeded with seedB
|
||
\param seedBSz: size of seedB in bytes
|
||
\param output: initialized to random data seeded with seedB if
|
||
seedrandom is set, and seedA 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
|
||
*/
|
||
int wc_RNG_HealthTest(int reseed, const byte* seedA, word32 seedASz,
|
||
const byte* seedB, word32 seedBSz,
|
||
byte* output, word32 outputSz);
|
||
|
||
/*!
|
||
\ingroup Random
|
||
\brief Generates seed from OS entropy source. Lower-level function
|
||
used internally by wc_InitRng.
|
||
|
||
\return 0 On success
|
||
\return WINCRYPT_E Failed to acquire context (Windows)
|
||
\return CRYPTGEN_E Failed to generate random (Windows)
|
||
\return RNG_FAILURE_E Failed to read entropy
|
||
|
||
\param os Pointer to OS_Seed structure
|
||
\param output Buffer to store seed
|
||
\param sz Size of seed in bytes
|
||
|
||
_Example_
|
||
\code
|
||
OS_Seed os;
|
||
byte seed[32];
|
||
int ret = wc_GenerateSeed(&os, seed, sizeof(seed));
|
||
\endcode
|
||
|
||
\sa wc_InitRng
|
||
*/
|
||
int wc_GenerateSeed(OS_Seed* os, byte* output, word32 sz);
|
||
|
||
/*!
|
||
\ingroup Random
|
||
\brief Allocates and initializes new WC_RNG with optional nonce.
|
||
|
||
\return Pointer to WC_RNG on success
|
||
\return NULL on failure
|
||
|
||
\param nonce Nonce buffer (can be NULL)
|
||
\param nonceSz Nonce size
|
||
\param heap Heap hint (can be NULL)
|
||
|
||
_Example_
|
||
\code
|
||
WC_RNG* rng = wc_rng_new(NULL, 0, NULL);
|
||
wc_rng_free(rng);
|
||
\endcode
|
||
|
||
\sa wc_rng_free
|
||
*/
|
||
WC_RNG* wc_rng_new(byte* nonce, word32 nonceSz, void* heap);
|
||
|
||
/*!
|
||
\ingroup Random
|
||
\brief Allocates and initializes WC_RNG with extended parameters.
|
||
|
||
\return 0 On success
|
||
\return BAD_FUNC_ARG If rng is NULL
|
||
\return MEMORY_E Memory allocation failed
|
||
|
||
\param rng Pointer to store WC_RNG pointer
|
||
\param nonce Nonce buffer (can be NULL)
|
||
\param nonceSz Nonce size
|
||
\param heap Heap hint (can be NULL)
|
||
\param devId Device ID (INVALID_DEVID for software)
|
||
|
||
_Example_
|
||
\code
|
||
WC_RNG* rng;
|
||
int ret = wc_rng_new_ex(&rng, NULL, 0, NULL, INVALID_DEVID);
|
||
wc_rng_free(rng);
|
||
\endcode
|
||
|
||
\sa wc_rng_new
|
||
*/
|
||
int wc_rng_new_ex(WC_RNG **rng, byte* nonce, word32 nonceSz, void* heap,
|
||
int devId);
|
||
|
||
/*!
|
||
\ingroup Random
|
||
\brief Frees WC_RNG allocated with wc_rng_new.
|
||
|
||
\param rng WC_RNG to free
|
||
|
||
_Example_
|
||
\code
|
||
WC_RNG* rng = wc_rng_new(NULL, 0, NULL);
|
||
wc_rng_free(rng);
|
||
\endcode
|
||
|
||
\sa wc_rng_new
|
||
*/
|
||
void wc_rng_free(WC_RNG* rng);
|
||
|
||
/*!
|
||
\ingroup Random
|
||
\brief Initializes WC_RNG with extended parameters.
|
||
|
||
\return 0 On success
|
||
\return BAD_FUNC_ARG If rng is NULL
|
||
\return RNG_FAILURE_E Initialization failed
|
||
|
||
\param rng WC_RNG to initialize
|
||
\param heap Heap hint (can be NULL)
|
||
\param devId Device ID (INVALID_DEVID for software)
|
||
|
||
_Example_
|
||
\code
|
||
WC_RNG rng;
|
||
int ret = wc_InitRng_ex(&rng, NULL, INVALID_DEVID);
|
||
wc_FreeRng(&rng);
|
||
\endcode
|
||
|
||
\sa wc_InitRng
|
||
*/
|
||
int wc_InitRng_ex(WC_RNG* rng, void* heap, int devId);
|
||
|
||
/*!
|
||
\ingroup Random
|
||
\brief Initializes WC_RNG with nonce.
|
||
|
||
\return 0 On success
|
||
\return BAD_FUNC_ARG If rng is NULL
|
||
\return RNG_FAILURE_E Initialization failed
|
||
|
||
\param rng WC_RNG to initialize
|
||
\param nonce Nonce buffer
|
||
\param nonceSz Nonce size
|
||
|
||
_Example_
|
||
\code
|
||
WC_RNG rng;
|
||
byte nonce[16];
|
||
int ret = wc_InitRngNonce(&rng, nonce, sizeof(nonce));
|
||
wc_FreeRng(&rng);
|
||
\endcode
|
||
|
||
\sa wc_InitRng
|
||
*/
|
||
int wc_InitRngNonce(WC_RNG* rng, byte* nonce, word32 nonceSz);
|
||
|
||
/*!
|
||
\ingroup Random
|
||
\brief Initializes WC_RNG with nonce and extended parameters.
|
||
|
||
\return 0 On success
|
||
\return BAD_FUNC_ARG If rng is NULL
|
||
\return RNG_FAILURE_E Initialization failed
|
||
|
||
\param rng WC_RNG to initialize
|
||
\param nonce Nonce buffer
|
||
\param nonceSz Nonce size
|
||
\param heap Heap hint (can be NULL)
|
||
\param devId Device ID (INVALID_DEVID for software)
|
||
|
||
_Example_
|
||
\code
|
||
WC_RNG rng;
|
||
byte nonce[16];
|
||
int ret = wc_InitRngNonce_ex(&rng, nonce, sizeof(nonce), NULL,
|
||
INVALID_DEVID);
|
||
wc_FreeRng(&rng);
|
||
\endcode
|
||
|
||
\sa wc_InitRngNonce
|
||
*/
|
||
int wc_InitRngNonce_ex(WC_RNG* rng, byte* nonce, word32 nonceSz,
|
||
void* heap, int devId);
|
||
|
||
/*!
|
||
\ingroup Random
|
||
\brief Sets callback for custom seed generation.
|
||
|
||
\return 0 On success
|
||
\return BAD_FUNC_ARG If cb is NULL
|
||
|
||
\param cb Seed callback function
|
||
|
||
_Example_
|
||
\code
|
||
int my_cb(OS_Seed* os, byte* out, word32 sz) { return 0; }
|
||
wc_SetSeed_Cb(my_cb);
|
||
\endcode
|
||
|
||
\sa wc_GenerateSeed
|
||
*/
|
||
int wc_SetSeed_Cb(wc_RngSeed_Cb cb);
|
||
|
||
/*!
|
||
\ingroup Random
|
||
\brief Reseeds DRBG with new entropy.
|
||
|
||
\return 0 On success
|
||
\return BAD_FUNC_ARG If rng or seed is NULL
|
||
\return RNG_FAILURE_E Reseed failed
|
||
|
||
\param rng WC_RNG to reseed
|
||
\param seed Seed buffer
|
||
\param seedSz Seed size
|
||
|
||
_Example_
|
||
\code
|
||
WC_RNG rng;
|
||
byte seed[32];
|
||
wc_InitRng(&rng);
|
||
int ret = wc_RNG_DRBG_Reseed(&rng, seed, sizeof(seed));
|
||
\endcode
|
||
|
||
\sa wc_InitRng
|
||
*/
|
||
int wc_RNG_DRBG_Reseed(WC_RNG* rng, const byte* seed, word32 seedSz);
|
||
|
||
/*!
|
||
\ingroup Random
|
||
\brief Tests seed validity for DRBG.
|
||
|
||
\return 0 If valid
|
||
\return BAD_FUNC_ARG If seed is NULL
|
||
\return ENTROPY_RT_E || ENTROPY_APT_E Validation failed
|
||
|
||
\param seed Seed to test
|
||
\param seedSz Seed size
|
||
|
||
_Example_
|
||
\code
|
||
byte seed[32];
|
||
int ret = wc_RNG_TestSeed(seed, sizeof(seed));
|
||
\endcode
|
||
|
||
\sa wc_InitRng
|
||
*/
|
||
int wc_RNG_TestSeed(const byte* seed, word32 seedSz);
|
||
|
||
/*!
|
||
\ingroup Random
|
||
\brief RNG health test with extended parameters.
|
||
|
||
\return 0 On success
|
||
\return BAD_FUNC_ARG If required params NULL
|
||
\return -1 Test failed
|
||
|
||
\param reseed Non-zero to test reseeding
|
||
\param nonce Nonce buffer (can be NULL)
|
||
\param nonceSz Nonce size
|
||
\param seedA Initial seed
|
||
\param seedASz Initial seed size
|
||
\param seedB Reseed buffer (required if reseed set)
|
||
\param seedBSz Reseed size
|
||
\param output Output buffer
|
||
\param outputSz Output size
|
||
\param heap Heap hint (can be NULL)
|
||
\param devId Device ID (INVALID_DEVID for software)
|
||
|
||
_Example_
|
||
\code
|
||
byte seedA[32], seedB[32], out[64];
|
||
int ret = wc_RNG_HealthTest_ex(1, NULL, 0, seedA, 32, seedB, 32,
|
||
out, 64, NULL, INVALID_DEVID);
|
||
\endcode
|
||
|
||
\sa wc_RNG_HealthTest
|
||
*/
|
||
int wc_RNG_HealthTest_ex(int reseed, const byte* nonce, word32 nonceSz,
|
||
const byte* seedA, word32 seedASz,
|
||
const byte* seedB, word32 seedBSz, byte* output,
|
||
word32 outputSz, void* heap, int devId);
|
||
|
||
/*!
|
||
\ingroup Random
|
||
\brief Gets raw entropy without DRBG processing.
|
||
|
||
\return 0 On success
|
||
\return BAD_FUNC_ARG If raw is NULL
|
||
\return RNG_FAILURE_E Failed
|
||
|
||
\param raw Buffer for entropy
|
||
\param cnt Bytes to retrieve
|
||
|
||
_Example_
|
||
\code
|
||
byte raw[32];
|
||
int ret = wc_Entropy_GetRawEntropy(raw, sizeof(raw));
|
||
\endcode
|
||
|
||
\sa wc_Entropy_Get
|
||
*/
|
||
int wc_Entropy_GetRawEntropy(unsigned char* raw, int cnt);
|
||
|
||
/*!
|
||
\ingroup Random
|
||
\brief Gets processed entropy with specified bits.
|
||
|
||
\return 0 On success
|
||
\return BAD_FUNC_ARG If entropy is NULL
|
||
\return RNG_FAILURE_E Failed
|
||
|
||
\param bits Entropy bits required
|
||
\param entropy Buffer for entropy
|
||
\param len Buffer size
|
||
|
||
_Example_
|
||
\code
|
||
byte entropy[32];
|
||
int ret = wc_Entropy_Get(256, entropy, sizeof(entropy));
|
||
\endcode
|
||
|
||
\sa wc_Entropy_GetRawEntropy
|
||
*/
|
||
int wc_Entropy_Get(int bits, unsigned char* entropy, word32 len);
|
||
|
||
/*!
|
||
\ingroup Random
|
||
\brief Tests entropy source on demand.
|
||
|
||
\return 0 On success
|
||
\return RNG_FAILURE_E Test failed
|
||
|
||
_Example_
|
||
\code
|
||
int ret = wc_Entropy_OnDemandTest();
|
||
\endcode
|
||
|
||
\sa wc_Entropy_Get
|
||
*/
|
||
int wc_Entropy_OnDemandTest(void);
|