random.h 7.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266
  1. /*!
  2. \ingroup Random
  3. \brief Init global Whitewood netRandom context
  4. \return 0 Success
  5. \return BAD_FUNC_ARG Either configFile is null or timeout is negative.
  6. \return RNG_FAILURE_E There was a failure initializing the rng.
  7. \param configFile Path to configuration file
  8. \param hmac_cb Optional to create HMAC callback.
  9. \param timeout A timeout duration.
  10. _Example_
  11. \code
  12. char* config = "path/to/config/example.conf";
  13. int time = // Some sufficient timeout value;
  14. if (wc_InitNetRandom(config, NULL, time) != 0)
  15. {
  16. // Some error occurred
  17. }
  18. \endcode
  19. \sa wc_FreeNetRandom
  20. */
  21. WOLFSSL_API int wc_InitNetRandom(const char*, wnr_hmac_key, int);
  22. /*!
  23. \ingroup Random
  24. \brief Free global Whitewood netRandom context.
  25. \return 0 Success
  26. \return BAD_MUTEX_E Error locking mutex on wnr_mutex
  27. \param none No returns.
  28. _Example_
  29. \code
  30. int ret = wc_FreeNetRandom();
  31. if(ret != 0)
  32. {
  33. // Handle the error
  34. }
  35. \endcode
  36. \sa wc_InitNetRandom
  37. */
  38. WOLFSSL_API int wc_FreeNetRandom(void);
  39. /*!
  40. \ingroup Random
  41. \brief Gets the seed (from OS) and key cipher for rng. rng->drbg
  42. (deterministic random bit generator) allocated (should be deallocated
  43. with wc_FreeRng). This is a blocking operation.
  44. \return 0 on success.
  45. \return MEMORY_E XMALLOC failed
  46. \return WINCRYPT_E wc_GenerateSeed: failed to acquire context
  47. \return CRYPTGEN_E wc_GenerateSeed: failed to get random
  48. \return BAD_FUNC_ARG wc_RNG_GenerateBlock input is null or sz exceeds
  49. MAX_REQUEST_LEN
  50. \return DRBG_CONT_FIPS_E wc_RNG_GenerateBlock: Hash_gen returned
  51. DRBG_CONT_FAILURE
  52. \return RNG_FAILURE_E wc_RNG_GenerateBlock: Default error. rng’s
  53. status originally not ok, or set to DRBG_FAILED
  54. \param rng random number generator to be initialized for use
  55. with a seed and key cipher
  56. _Example_
  57. \code
  58. RNG rng;
  59. int ret;
  60. #ifdef HAVE_CAVIUM
  61. ret = wc_InitRngCavium(&rng, CAVIUM_DEV_ID);
  62. if (ret != 0){
  63. printf(“RNG Nitrox init for device: %d failed”, CAVIUM_DEV_ID);
  64. return -1;
  65. }
  66. #endif
  67. ret = wc_InitRng(&rng);
  68. if (ret != 0){
  69. printf(“RNG init failed”);
  70. return -1;
  71. }
  72. \endcode
  73. \sa wc_InitRngCavium
  74. \sa wc_RNG_GenerateBlock
  75. \sa wc_RNG_GenerateByte
  76. \sa wc_FreeRng
  77. \sa wc_RNG_HealthTest
  78. */
  79. WOLFSSL_API int wc_InitRng(WC_RNG*);
  80. /*!
  81. \ingroup Random
  82. \brief Copies a sz bytes of pseudorandom data to output. Will
  83. reseed rng if needed (blocking).
  84. \return 0 on success
  85. \return BAD_FUNC_ARG an input is null or sz exceeds MAX_REQUEST_LEN
  86. \return DRBG_CONT_FIPS_E Hash_gen returned DRBG_CONT_FAILURE
  87. \return RNG_FAILURE_E Default error. rng’s status originally not
  88. ok, or set to DRBG_FAILED
  89. \param rng random number generator initialized with wc_InitRng
  90. \param output buffer to which the block is copied
  91. \param sz size of output in bytes
  92. _Example_
  93. \code
  94. RNG rng;
  95. int sz = 32;
  96. byte block[sz];
  97. int ret = wc_InitRng(&rng);
  98. if (ret != 0) {
  99. return -1; //init of rng failed!
  100. }
  101. ret = wc_RNG_GenerateBlock(&rng, block, sz);
  102. if (ret != 0) {
  103. return -1; //generating block failed!
  104. }
  105. \endcode
  106. \sa wc_InitRngCavium, wc_InitRng
  107. \sa wc_RNG_GenerateByte
  108. \sa wc_FreeRng
  109. \sa wc_RNG_HealthTest
  110. */
  111. WOLFSSL_API int wc_RNG_GenerateBlock(WC_RNG*, byte*, word32 sz);
  112. /*!
  113. \ingroup Random
  114. \brief Calls wc_RNG_GenerateBlock to copy a byte of pseudorandom
  115. data to b. Will reseed rng if needed.
  116. \return 0 on success
  117. \return BAD_FUNC_ARG an input is null or sz exceeds MAX_REQUEST_LEN
  118. \return DRBG_CONT_FIPS_E Hash_gen returned DRBG_CONT_FAILURE
  119. \return RNG_FAILURE_E Default error. rng’s status originally not
  120. ok, or set to DRBG_FAILED
  121. \param rng: random number generator initialized with wc_InitRng
  122. \param b one byte buffer to which the block is copied
  123. _Example_
  124. \code
  125. RNG rng;
  126. int sz = 32;
  127. byte b[1];
  128. int ret = wc_InitRng(&rng);
  129. if (ret != 0) {
  130. return -1; //init of rng failed!
  131. }
  132. ret = wc_RNG_GenerateByte(&rng, b);
  133. if (ret != 0) {
  134. return -1; //generating block failed!
  135. }
  136. \endcode
  137. \sa wc_InitRngCavium
  138. \sa wc_InitRng
  139. \sa wc_RNG_GenerateBlock
  140. \sa wc_FreeRng
  141. \sa wc_RNG_HealthTest
  142. */
  143. WOLFSSL_API int wc_RNG_GenerateByte(WC_RNG*, byte*);
  144. /*!
  145. \ingroup Random
  146. \brief Should be called when RNG no longer needed in order to securely
  147. free drgb. Zeros and XFREEs rng-drbg.
  148. \return 0 on success
  149. \return BAD_FUNC_ARG rng or rng->drgb null
  150. \return RNG_FAILURE_E Failed to deallocated drbg
  151. \param rng random number generator initialized with wc_InitRng
  152. _Example_
  153. \code
  154. RNG rng;
  155. int ret = wc_InitRng(&rng);
  156. if (ret != 0) {
  157. return -1; //init of rng failed!
  158. }
  159. int ret = wc_FreeRng(&rng);
  160. if (ret != 0) {
  161. return -1; //free of rng failed!
  162. }
  163. \endcode
  164. \sa wc_InitRngCavium
  165. \sa wc_InitRng
  166. \sa wc_RNG_GenerateBlock
  167. \sa wc_RNG_GenerateByte,
  168. \sa wc_RNG_HealthTest
  169. */
  170. WOLFSSL_API int wc_FreeRng(WC_RNG*);
  171. /*!
  172. \ingroup Random
  173. \brief Creates and tests functionality of drbg.
  174. \return 0 on success
  175. \return BAD_FUNC_ARG entropyA and output must not be null. If reseed
  176. set entropyB must not be null
  177. \return -1 test failed
  178. \param int reseed: if set, will test reseed functionality
  179. \param entropyA: entropy to instantiate drgb with
  180. \param entropyASz: size of entropyA in bytes
  181. \param entropyB: If reseed set, drbg will be reseeded with entropyB
  182. \param entropyBSz: size of entropyB in bytes
  183. \param output: initialized to random data seeded with entropyB if
  184. seedrandom is set, and entropyA otherwise
  185. \param outputSz: length of output in bytes
  186. _Example_
  187. \code
  188. byte output[SHA256_DIGEST_SIZE * 4];
  189. const byte test1EntropyB[] = ....; // test input for reseed false
  190. const byte test1Output[] = ....; // testvector: expected output of
  191. // reseed false
  192. ret = wc_RNG_HealthTest(0, test1Entropy, sizeof(test1Entropy), NULL, 0,
  193. output, sizeof(output));
  194. if (ret != 0)
  195. return -1;//healthtest without reseed failed
  196. if (XMEMCMP(test1Output, output, sizeof(output)) != 0)
  197. return -1; //compare to testvector failed: unexpected output
  198. const byte test2EntropyB[] = ....; // test input for reseed
  199. const byte test2Output[] = ....; // testvector expected output of reseed
  200. ret = wc_RNG_HealthTest(1, test2EntropyA, sizeof(test2EntropyA),
  201. test2EntropyB, sizeof(test2EntropyB),
  202. output, sizeof(output));
  203. if (XMEMCMP(test2Output, output, sizeof(output)) != 0)
  204. return -1; //compare to testvector failed
  205. \endcode
  206. \sa wc_InitRngCavium
  207. \sa wc_InitRng
  208. \sa wc_RNG_GenerateBlock
  209. \sa wc_RNG_GenerateByte
  210. \sa wc_FreeRng
  211. */
  212. WOLFSSL_API int wc_RNG_HealthTest(int reseed,
  213. const byte* entropyA, word32 entropyASz,
  214. const byte* entropyB, word32 entropyBSz,
  215. byte* output, word32 outputSz);