entropy.h 9.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289
  1. /**
  2. * \file entropy.h
  3. *
  4. * \brief Entropy accumulator implementation
  5. */
  6. /*
  7. * Copyright The Mbed TLS Contributors
  8. * SPDX-License-Identifier: Apache-2.0
  9. *
  10. * Licensed under the Apache License, Version 2.0 (the "License"); you may
  11. * not use this file except in compliance with the License.
  12. * You may obtain a copy of the License at
  13. *
  14. * http://www.apache.org/licenses/LICENSE-2.0
  15. *
  16. * Unless required by applicable law or agreed to in writing, software
  17. * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  18. * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19. * See the License for the specific language governing permissions and
  20. * limitations under the License.
  21. */
  22. #ifndef MBEDTLS_ENTROPY_H
  23. #define MBEDTLS_ENTROPY_H
  24. #if !defined(MBEDTLS_CONFIG_FILE)
  25. #include "mbedtls/config.h"
  26. #else
  27. #include MBEDTLS_CONFIG_FILE
  28. #endif
  29. #include <stddef.h>
  30. #if defined(MBEDTLS_SHA512_C) && !defined(MBEDTLS_ENTROPY_FORCE_SHA256)
  31. #include "mbedtls/sha512.h"
  32. #define MBEDTLS_ENTROPY_SHA512_ACCUMULATOR
  33. #else
  34. #if defined(MBEDTLS_SHA256_C)
  35. #define MBEDTLS_ENTROPY_SHA256_ACCUMULATOR
  36. #include "mbedtls/sha256.h"
  37. #endif
  38. #endif
  39. #if defined(MBEDTLS_THREADING_C)
  40. #include "mbedtls/threading.h"
  41. #endif
  42. #if defined(MBEDTLS_HAVEGE_C)
  43. #include "mbedtls/havege.h"
  44. #endif
  45. #define MBEDTLS_ERR_ENTROPY_SOURCE_FAILED -0x003C /**< Critical entropy source failure. */
  46. #define MBEDTLS_ERR_ENTROPY_MAX_SOURCES -0x003E /**< No more sources can be added. */
  47. #define MBEDTLS_ERR_ENTROPY_NO_SOURCES_DEFINED -0x0040 /**< No sources have been added to poll. */
  48. #define MBEDTLS_ERR_ENTROPY_NO_STRONG_SOURCE -0x003D /**< No strong sources have been added to poll. */
  49. #define MBEDTLS_ERR_ENTROPY_FILE_IO_ERROR -0x003F /**< Read/write error in file. */
  50. /**
  51. * \name SECTION: Module settings
  52. *
  53. * The configuration options you can set for this module are in this section.
  54. * Either change them in config.h or define them on the compiler command line.
  55. * \{
  56. */
  57. #if !defined(MBEDTLS_ENTROPY_MAX_SOURCES)
  58. #define MBEDTLS_ENTROPY_MAX_SOURCES 20 /**< Maximum number of sources supported */
  59. #endif
  60. #if !defined(MBEDTLS_ENTROPY_MAX_GATHER)
  61. #define MBEDTLS_ENTROPY_MAX_GATHER 128 /**< Maximum amount requested from entropy sources */
  62. #endif
  63. /* \} name SECTION: Module settings */
  64. #if defined(MBEDTLS_ENTROPY_SHA512_ACCUMULATOR)
  65. #define MBEDTLS_ENTROPY_BLOCK_SIZE 64 /**< Block size of entropy accumulator (SHA-512) */
  66. #else
  67. #define MBEDTLS_ENTROPY_BLOCK_SIZE 32 /**< Block size of entropy accumulator (SHA-256) */
  68. #endif
  69. #define MBEDTLS_ENTROPY_MAX_SEED_SIZE 1024 /**< Maximum size of seed we read from seed file */
  70. #define MBEDTLS_ENTROPY_SOURCE_MANUAL MBEDTLS_ENTROPY_MAX_SOURCES
  71. #define MBEDTLS_ENTROPY_SOURCE_STRONG 1 /**< Entropy source is strong */
  72. #define MBEDTLS_ENTROPY_SOURCE_WEAK 0 /**< Entropy source is weak */
  73. #ifdef __cplusplus
  74. extern "C" {
  75. #endif
  76. /**
  77. * \brief Entropy poll callback pointer
  78. *
  79. * \param data Callback-specific data pointer
  80. * \param output Data to fill
  81. * \param len Maximum size to provide
  82. * \param olen The actual amount of bytes put into the buffer (Can be 0)
  83. *
  84. * \return 0 if no critical failures occurred,
  85. * MBEDTLS_ERR_ENTROPY_SOURCE_FAILED otherwise
  86. */
  87. typedef int (*mbedtls_entropy_f_source_ptr)(void *data, unsigned char *output, size_t len,
  88. size_t *olen);
  89. /**
  90. * \brief Entropy source state
  91. */
  92. typedef struct mbedtls_entropy_source_state
  93. {
  94. mbedtls_entropy_f_source_ptr f_source; /**< The entropy source callback */
  95. void * p_source; /**< The callback data pointer */
  96. size_t size; /**< Amount received in bytes */
  97. size_t threshold; /**< Minimum bytes required before release */
  98. int strong; /**< Is the source strong? */
  99. }
  100. mbedtls_entropy_source_state;
  101. /**
  102. * \brief Entropy context structure
  103. */
  104. typedef struct mbedtls_entropy_context
  105. {
  106. int accumulator_started; /* 0 after init.
  107. * 1 after the first update.
  108. * -1 after free. */
  109. #if defined(MBEDTLS_ENTROPY_SHA512_ACCUMULATOR)
  110. mbedtls_sha512_context accumulator;
  111. #else
  112. mbedtls_sha256_context accumulator;
  113. #endif
  114. int source_count; /* Number of entries used in source. */
  115. mbedtls_entropy_source_state source[MBEDTLS_ENTROPY_MAX_SOURCES];
  116. #if defined(MBEDTLS_HAVEGE_C)
  117. mbedtls_havege_state havege_data;
  118. #endif
  119. #if defined(MBEDTLS_THREADING_C)
  120. mbedtls_threading_mutex_t mutex; /*!< mutex */
  121. #endif
  122. #if defined(MBEDTLS_ENTROPY_NV_SEED)
  123. int initial_entropy_run;
  124. #endif
  125. }
  126. mbedtls_entropy_context;
  127. /**
  128. * \brief Initialize the context
  129. *
  130. * \param ctx Entropy context to initialize
  131. */
  132. void mbedtls_entropy_init( mbedtls_entropy_context *ctx );
  133. /**
  134. * \brief Free the data in the context
  135. *
  136. * \param ctx Entropy context to free
  137. */
  138. void mbedtls_entropy_free( mbedtls_entropy_context *ctx );
  139. /**
  140. * \brief Adds an entropy source to poll
  141. * (Thread-safe if MBEDTLS_THREADING_C is enabled)
  142. *
  143. * \param ctx Entropy context
  144. * \param f_source Entropy function
  145. * \param p_source Function data
  146. * \param threshold Minimum required from source before entropy is released
  147. * ( with mbedtls_entropy_func() ) (in bytes)
  148. * \param strong MBEDTLS_ENTROPY_SOURCE_STRONG or
  149. * MBEDTLS_ENTROPY_SOURCE_WEAK.
  150. * At least one strong source needs to be added.
  151. * Weaker sources (such as the cycle counter) can be used as
  152. * a complement.
  153. *
  154. * \return 0 if successful or MBEDTLS_ERR_ENTROPY_MAX_SOURCES
  155. */
  156. int mbedtls_entropy_add_source( mbedtls_entropy_context *ctx,
  157. mbedtls_entropy_f_source_ptr f_source, void *p_source,
  158. size_t threshold, int strong );
  159. /**
  160. * \brief Trigger an extra gather poll for the accumulator
  161. * (Thread-safe if MBEDTLS_THREADING_C is enabled)
  162. *
  163. * \param ctx Entropy context
  164. *
  165. * \return 0 if successful, or MBEDTLS_ERR_ENTROPY_SOURCE_FAILED
  166. */
  167. int mbedtls_entropy_gather( mbedtls_entropy_context *ctx );
  168. /**
  169. * \brief Retrieve entropy from the accumulator
  170. * (Maximum length: MBEDTLS_ENTROPY_BLOCK_SIZE)
  171. * (Thread-safe if MBEDTLS_THREADING_C is enabled)
  172. *
  173. * \param data Entropy context
  174. * \param output Buffer to fill
  175. * \param len Number of bytes desired, must be at most MBEDTLS_ENTROPY_BLOCK_SIZE
  176. *
  177. * \return 0 if successful, or MBEDTLS_ERR_ENTROPY_SOURCE_FAILED
  178. */
  179. int mbedtls_entropy_func( void *data, unsigned char *output, size_t len );
  180. /**
  181. * \brief Add data to the accumulator manually
  182. * (Thread-safe if MBEDTLS_THREADING_C is enabled)
  183. *
  184. * \param ctx Entropy context
  185. * \param data Data to add
  186. * \param len Length of data
  187. *
  188. * \return 0 if successful
  189. */
  190. int mbedtls_entropy_update_manual( mbedtls_entropy_context *ctx,
  191. const unsigned char *data, size_t len );
  192. #if defined(MBEDTLS_ENTROPY_NV_SEED)
  193. /**
  194. * \brief Trigger an update of the seed file in NV by using the
  195. * current entropy pool.
  196. *
  197. * \param ctx Entropy context
  198. *
  199. * \return 0 if successful
  200. */
  201. int mbedtls_entropy_update_nv_seed( mbedtls_entropy_context *ctx );
  202. #endif /* MBEDTLS_ENTROPY_NV_SEED */
  203. #if defined(MBEDTLS_FS_IO)
  204. /**
  205. * \brief Write a seed file
  206. *
  207. * \param ctx Entropy context
  208. * \param path Name of the file
  209. *
  210. * \return 0 if successful,
  211. * MBEDTLS_ERR_ENTROPY_FILE_IO_ERROR on file error, or
  212. * MBEDTLS_ERR_ENTROPY_SOURCE_FAILED
  213. */
  214. int mbedtls_entropy_write_seed_file( mbedtls_entropy_context *ctx, const char *path );
  215. /**
  216. * \brief Read and update a seed file. Seed is added to this
  217. * instance. No more than MBEDTLS_ENTROPY_MAX_SEED_SIZE bytes are
  218. * read from the seed file. The rest is ignored.
  219. *
  220. * \param ctx Entropy context
  221. * \param path Name of the file
  222. *
  223. * \return 0 if successful,
  224. * MBEDTLS_ERR_ENTROPY_FILE_IO_ERROR on file error,
  225. * MBEDTLS_ERR_ENTROPY_SOURCE_FAILED
  226. */
  227. int mbedtls_entropy_update_seed_file( mbedtls_entropy_context *ctx, const char *path );
  228. #endif /* MBEDTLS_FS_IO */
  229. #if defined(MBEDTLS_SELF_TEST)
  230. /**
  231. * \brief Checkup routine
  232. *
  233. * This module self-test also calls the entropy self-test,
  234. * mbedtls_entropy_source_self_test();
  235. *
  236. * \return 0 if successful, or 1 if a test failed
  237. */
  238. int mbedtls_entropy_self_test( int verbose );
  239. #if defined(MBEDTLS_ENTROPY_HARDWARE_ALT)
  240. /**
  241. * \brief Checkup routine
  242. *
  243. * Verifies the integrity of the hardware entropy source
  244. * provided by the function 'mbedtls_hardware_poll()'.
  245. *
  246. * Note this is the only hardware entropy source that is known
  247. * at link time, and other entropy sources configured
  248. * dynamically at runtime by the function
  249. * mbedtls_entropy_add_source() will not be tested.
  250. *
  251. * \return 0 if successful, or 1 if a test failed
  252. */
  253. int mbedtls_entropy_source_self_test( int verbose );
  254. #endif /* MBEDTLS_ENTROPY_HARDWARE_ALT */
  255. #endif /* MBEDTLS_SELF_TEST */
  256. #ifdef __cplusplus
  257. }
  258. #endif
  259. #endif /* entropy.h */