entropy.h 8.2 KB

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