ctr_drbg.h 25 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607
  1. /**
  2. * \file ctr_drbg.h
  3. *
  4. * \brief This file contains definitions and functions for the
  5. * CTR_DRBG pseudorandom generator.
  6. *
  7. * CTR_DRBG is a standardized way of building a PRNG from a block-cipher
  8. * in counter mode operation, as defined in <em>NIST SP 800-90A:
  9. * Recommendation for Random Number Generation Using Deterministic Random
  10. * Bit Generators</em>.
  11. *
  12. * The Mbed TLS implementation of CTR_DRBG uses AES-256 (default) or AES-128
  13. * (if \c MBEDTLS_CTR_DRBG_USE_128_BIT_KEY is enabled at compile time)
  14. * as the underlying block cipher, with a derivation function.
  15. *
  16. * The security strength as defined in NIST SP 800-90A is
  17. * 128 bits when AES-128 is used (\c MBEDTLS_CTR_DRBG_USE_128_BIT_KEY enabled)
  18. * and 256 bits otherwise, provided that #MBEDTLS_CTR_DRBG_ENTROPY_LEN is
  19. * kept at its default value (and not overridden in config.h) and that the
  20. * DRBG instance is set up with default parameters.
  21. * See the documentation of mbedtls_ctr_drbg_seed() for more
  22. * information.
  23. */
  24. /*
  25. * Copyright The Mbed TLS Contributors
  26. * SPDX-License-Identifier: Apache-2.0
  27. *
  28. * Licensed under the Apache License, Version 2.0 (the "License"); you may
  29. * not use this file except in compliance with the License.
  30. * You may obtain a copy of the License at
  31. *
  32. * http://www.apache.org/licenses/LICENSE-2.0
  33. *
  34. * Unless required by applicable law or agreed to in writing, software
  35. * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  36. * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  37. * See the License for the specific language governing permissions and
  38. * limitations under the License.
  39. */
  40. #ifndef MBEDTLS_CTR_DRBG_H
  41. #define MBEDTLS_CTR_DRBG_H
  42. #if !defined(MBEDTLS_CONFIG_FILE)
  43. #include "mbedtls/config.h"
  44. #else
  45. #include MBEDTLS_CONFIG_FILE
  46. #endif
  47. #include "mbedtls/aes.h"
  48. #if defined(MBEDTLS_THREADING_C)
  49. #include "mbedtls/threading.h"
  50. #endif
  51. #define MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED -0x0034 /**< The entropy source failed. */
  52. #define MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG -0x0036 /**< The requested random buffer length is too big. */
  53. #define MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG -0x0038 /**< The input (entropy + additional data) is too large. */
  54. #define MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR -0x003A /**< Read or write error in file. */
  55. #define MBEDTLS_CTR_DRBG_BLOCKSIZE 16 /**< The block size used by the cipher. */
  56. #if defined(MBEDTLS_CTR_DRBG_USE_128_BIT_KEY)
  57. #define MBEDTLS_CTR_DRBG_KEYSIZE 16
  58. /**< The key size in bytes used by the cipher.
  59. *
  60. * Compile-time choice: 16 bytes (128 bits)
  61. * because #MBEDTLS_CTR_DRBG_USE_128_BIT_KEY is enabled.
  62. */
  63. #else
  64. #define MBEDTLS_CTR_DRBG_KEYSIZE 32
  65. /**< The key size in bytes used by the cipher.
  66. *
  67. * Compile-time choice: 32 bytes (256 bits)
  68. * because \c MBEDTLS_CTR_DRBG_USE_128_BIT_KEY is disabled.
  69. */
  70. #endif
  71. #define MBEDTLS_CTR_DRBG_KEYBITS ( MBEDTLS_CTR_DRBG_KEYSIZE * 8 ) /**< The key size for the DRBG operation, in bits. */
  72. #define MBEDTLS_CTR_DRBG_SEEDLEN ( MBEDTLS_CTR_DRBG_KEYSIZE + MBEDTLS_CTR_DRBG_BLOCKSIZE ) /**< The seed length, calculated as (counter + AES key). */
  73. /**
  74. * \name SECTION: Module settings
  75. *
  76. * The configuration options you can set for this module are in this section.
  77. * Either change them in config.h or define them using the compiler command
  78. * line.
  79. * \{
  80. */
  81. /** \def MBEDTLS_CTR_DRBG_ENTROPY_LEN
  82. *
  83. * \brief The amount of entropy used per seed by default, in bytes.
  84. */
  85. #if !defined(MBEDTLS_CTR_DRBG_ENTROPY_LEN)
  86. #if defined(MBEDTLS_SHA512_C) && !defined(MBEDTLS_ENTROPY_FORCE_SHA256)
  87. /** This is 48 bytes because the entropy module uses SHA-512
  88. * (\c MBEDTLS_ENTROPY_FORCE_SHA256 is disabled).
  89. */
  90. #define MBEDTLS_CTR_DRBG_ENTROPY_LEN 48
  91. #else /* defined(MBEDTLS_SHA512_C) && !defined(MBEDTLS_ENTROPY_FORCE_SHA256) */
  92. /** This is 32 bytes because the entropy module uses SHA-256
  93. * (the SHA512 module is disabled or
  94. * \c MBEDTLS_ENTROPY_FORCE_SHA256 is enabled).
  95. */
  96. #if !defined(MBEDTLS_CTR_DRBG_USE_128_BIT_KEY)
  97. /** \warning To achieve a 256-bit security strength, you must pass a nonce
  98. * to mbedtls_ctr_drbg_seed().
  99. */
  100. #endif /* !defined(MBEDTLS_CTR_DRBG_USE_128_BIT_KEY) */
  101. #define MBEDTLS_CTR_DRBG_ENTROPY_LEN 32
  102. #endif /* defined(MBEDTLS_SHA512_C) && !defined(MBEDTLS_ENTROPY_FORCE_SHA256) */
  103. #endif /* !defined(MBEDTLS_CTR_DRBG_ENTROPY_LEN) */
  104. #if !defined(MBEDTLS_CTR_DRBG_RESEED_INTERVAL)
  105. #define MBEDTLS_CTR_DRBG_RESEED_INTERVAL 10000
  106. /**< The interval before reseed is performed by default. */
  107. #endif
  108. #if !defined(MBEDTLS_CTR_DRBG_MAX_INPUT)
  109. #define MBEDTLS_CTR_DRBG_MAX_INPUT 256
  110. /**< The maximum number of additional input Bytes. */
  111. #endif
  112. #if !defined(MBEDTLS_CTR_DRBG_MAX_REQUEST)
  113. #define MBEDTLS_CTR_DRBG_MAX_REQUEST 1024
  114. /**< The maximum number of requested Bytes per call. */
  115. #endif
  116. #if !defined(MBEDTLS_CTR_DRBG_MAX_SEED_INPUT)
  117. #define MBEDTLS_CTR_DRBG_MAX_SEED_INPUT 384
  118. /**< The maximum size of seed or reseed buffer in bytes. */
  119. #endif
  120. /* \} name SECTION: Module settings */
  121. #define MBEDTLS_CTR_DRBG_PR_OFF 0
  122. /**< Prediction resistance is disabled. */
  123. #define MBEDTLS_CTR_DRBG_PR_ON 1
  124. /**< Prediction resistance is enabled. */
  125. #ifdef __cplusplus
  126. extern "C" {
  127. #endif
  128. #if MBEDTLS_CTR_DRBG_ENTROPY_LEN >= MBEDTLS_CTR_DRBG_KEYSIZE * 3 / 2
  129. /** The default length of the nonce read from the entropy source.
  130. *
  131. * This is \c 0 because a single read from the entropy source is sufficient
  132. * to include a nonce.
  133. * See the documentation of mbedtls_ctr_drbg_seed() for more information.
  134. */
  135. #define MBEDTLS_CTR_DRBG_ENTROPY_NONCE_LEN 0
  136. #else
  137. /** The default length of the nonce read from the entropy source.
  138. *
  139. * This is half of the default entropy length because a single read from
  140. * the entropy source does not provide enough material to form a nonce.
  141. * See the documentation of mbedtls_ctr_drbg_seed() for more information.
  142. */
  143. #define MBEDTLS_CTR_DRBG_ENTROPY_NONCE_LEN ( MBEDTLS_CTR_DRBG_ENTROPY_LEN + 1 ) / 2
  144. #endif
  145. /**
  146. * \brief The CTR_DRBG context structure.
  147. */
  148. typedef struct mbedtls_ctr_drbg_context
  149. {
  150. unsigned char counter[16]; /*!< The counter (V). */
  151. int reseed_counter; /*!< The reseed counter.
  152. * This is the number of requests that have
  153. * been made since the last (re)seeding,
  154. * minus one.
  155. * Before the initial seeding, this field
  156. * contains the amount of entropy in bytes
  157. * to use as a nonce for the initial seeding,
  158. * or -1 if no nonce length has been explicitly
  159. * set (see mbedtls_ctr_drbg_set_nonce_len()).
  160. */
  161. int prediction_resistance; /*!< This determines whether prediction
  162. resistance is enabled, that is
  163. whether to systematically reseed before
  164. each random generation. */
  165. size_t entropy_len; /*!< The amount of entropy grabbed on each
  166. seed or reseed operation, in bytes. */
  167. int reseed_interval; /*!< The reseed interval.
  168. * This is the maximum number of requests
  169. * that can be made between reseedings. */
  170. mbedtls_aes_context aes_ctx; /*!< The AES context. */
  171. /*
  172. * Callbacks (Entropy)
  173. */
  174. int (*f_entropy)(void *, unsigned char *, size_t);
  175. /*!< The entropy callback function. */
  176. void *p_entropy; /*!< The context for the entropy function. */
  177. #if defined(MBEDTLS_THREADING_C)
  178. /* Invariant: the mutex is initialized if and only if f_entropy != NULL.
  179. * This means that the mutex is initialized during the initial seeding
  180. * in mbedtls_ctr_drbg_seed() and freed in mbedtls_ctr_drbg_free().
  181. *
  182. * Note that this invariant may change without notice. Do not rely on it
  183. * and do not access the mutex directly in application code.
  184. */
  185. mbedtls_threading_mutex_t mutex;
  186. #endif
  187. }
  188. mbedtls_ctr_drbg_context;
  189. /**
  190. * \brief This function initializes the CTR_DRBG context,
  191. * and prepares it for mbedtls_ctr_drbg_seed()
  192. * or mbedtls_ctr_drbg_free().
  193. *
  194. * \note The reseed interval is
  195. * #MBEDTLS_CTR_DRBG_RESEED_INTERVAL by default.
  196. * You can override it by calling
  197. * mbedtls_ctr_drbg_set_reseed_interval().
  198. *
  199. * \param ctx The CTR_DRBG context to initialize.
  200. */
  201. void mbedtls_ctr_drbg_init( mbedtls_ctr_drbg_context *ctx );
  202. /**
  203. * \brief This function seeds and sets up the CTR_DRBG
  204. * entropy source for future reseeds.
  205. *
  206. * A typical choice for the \p f_entropy and \p p_entropy parameters is
  207. * to use the entropy module:
  208. * - \p f_entropy is mbedtls_entropy_func();
  209. * - \p p_entropy is an instance of ::mbedtls_entropy_context initialized
  210. * with mbedtls_entropy_init() (which registers the platform's default
  211. * entropy sources).
  212. *
  213. * The entropy length is #MBEDTLS_CTR_DRBG_ENTROPY_LEN by default.
  214. * You can override it by calling mbedtls_ctr_drbg_set_entropy_len().
  215. *
  216. * The entropy nonce length is:
  217. * - \c 0 if the entropy length is at least 3/2 times the entropy length,
  218. * which guarantees that the security strength is the maximum permitted
  219. * by the key size and entropy length according to NIST SP 800-90A §10.2.1;
  220. * - Half the entropy length otherwise.
  221. * You can override it by calling mbedtls_ctr_drbg_set_nonce_len().
  222. * With the default entropy length, the entropy nonce length is
  223. * #MBEDTLS_CTR_DRBG_ENTROPY_NONCE_LEN.
  224. *
  225. * You can provide a nonce and personalization string in addition to the
  226. * entropy source, to make this instantiation as unique as possible.
  227. * See SP 800-90A §8.6.7 for more details about nonces.
  228. *
  229. * The _seed_material_ value passed to the derivation function in
  230. * the CTR_DRBG Instantiate Process described in NIST SP 800-90A §10.2.1.3.2
  231. * is the concatenation of the following strings:
  232. * - A string obtained by calling \p f_entropy function for the entropy
  233. * length.
  234. */
  235. #if MBEDTLS_CTR_DRBG_ENTROPY_NONCE_LEN == 0
  236. /**
  237. * - If mbedtls_ctr_drbg_set_nonce_len() has been called, a string
  238. * obtained by calling \p f_entropy function for the specified length.
  239. */
  240. #else
  241. /**
  242. * - A string obtained by calling \p f_entropy function for the entropy nonce
  243. * length. If the entropy nonce length is \c 0, this function does not
  244. * make a second call to \p f_entropy.
  245. */
  246. #endif
  247. #if defined(MBEDTLS_THREADING_C)
  248. /**
  249. * \note When Mbed TLS is built with threading support,
  250. * after this function returns successfully,
  251. * it is safe to call mbedtls_ctr_drbg_random()
  252. * from multiple threads. Other operations, including
  253. * reseeding, are not thread-safe.
  254. */
  255. #endif /* MBEDTLS_THREADING_C */
  256. /**
  257. * - The \p custom string.
  258. *
  259. * \note To achieve the nominal security strength permitted
  260. * by CTR_DRBG, the entropy length must be:
  261. * - at least 16 bytes for a 128-bit strength
  262. * (maximum achievable strength when using AES-128);
  263. * - at least 32 bytes for a 256-bit strength
  264. * (maximum achievable strength when using AES-256).
  265. *
  266. * In addition, if you do not pass a nonce in \p custom,
  267. * the sum of the entropy length
  268. * and the entropy nonce length must be:
  269. * - at least 24 bytes for a 128-bit strength
  270. * (maximum achievable strength when using AES-128);
  271. * - at least 48 bytes for a 256-bit strength
  272. * (maximum achievable strength when using AES-256).
  273. *
  274. * \param ctx The CTR_DRBG context to seed.
  275. * It must have been initialized with
  276. * mbedtls_ctr_drbg_init().
  277. * After a successful call to mbedtls_ctr_drbg_seed(),
  278. * you may not call mbedtls_ctr_drbg_seed() again on
  279. * the same context unless you call
  280. * mbedtls_ctr_drbg_free() and mbedtls_ctr_drbg_init()
  281. * again first.
  282. * After a failed call to mbedtls_ctr_drbg_seed(),
  283. * you must call mbedtls_ctr_drbg_free().
  284. * \param f_entropy The entropy callback, taking as arguments the
  285. * \p p_entropy context, the buffer to fill, and the
  286. * length of the buffer.
  287. * \p f_entropy is always called with a buffer size
  288. * less than or equal to the entropy length.
  289. * \param p_entropy The entropy context to pass to \p f_entropy.
  290. * \param custom The personalization string.
  291. * This can be \c NULL, in which case the personalization
  292. * string is empty regardless of the value of \p len.
  293. * \param len The length of the personalization string.
  294. * This must be at most
  295. * #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT
  296. * - #MBEDTLS_CTR_DRBG_ENTROPY_LEN.
  297. *
  298. * \return \c 0 on success.
  299. * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure.
  300. */
  301. int mbedtls_ctr_drbg_seed( mbedtls_ctr_drbg_context *ctx,
  302. int (*f_entropy)(void *, unsigned char *, size_t),
  303. void *p_entropy,
  304. const unsigned char *custom,
  305. size_t len );
  306. /**
  307. * \brief This function resets CTR_DRBG context to the state immediately
  308. * after initial call of mbedtls_ctr_drbg_init().
  309. *
  310. * \param ctx The CTR_DRBG context to clear.
  311. */
  312. void mbedtls_ctr_drbg_free( mbedtls_ctr_drbg_context *ctx );
  313. /**
  314. * \brief This function turns prediction resistance on or off.
  315. * The default value is off.
  316. *
  317. * \note If enabled, entropy is gathered at the beginning of
  318. * every call to mbedtls_ctr_drbg_random_with_add()
  319. * or mbedtls_ctr_drbg_random().
  320. * Only use this if your entropy source has sufficient
  321. * throughput.
  322. *
  323. * \param ctx The CTR_DRBG context.
  324. * \param resistance #MBEDTLS_CTR_DRBG_PR_ON or #MBEDTLS_CTR_DRBG_PR_OFF.
  325. */
  326. void mbedtls_ctr_drbg_set_prediction_resistance( mbedtls_ctr_drbg_context *ctx,
  327. int resistance );
  328. /**
  329. * \brief This function sets the amount of entropy grabbed on each
  330. * seed or reseed.
  331. *
  332. * The default value is #MBEDTLS_CTR_DRBG_ENTROPY_LEN.
  333. *
  334. * \note The security strength of CTR_DRBG is bounded by the
  335. * entropy length. Thus:
  336. * - When using AES-256
  337. * (\c MBEDTLS_CTR_DRBG_USE_128_BIT_KEY is disabled,
  338. * which is the default),
  339. * \p len must be at least 32 (in bytes)
  340. * to achieve a 256-bit strength.
  341. * - When using AES-128
  342. * (\c MBEDTLS_CTR_DRBG_USE_128_BIT_KEY is enabled)
  343. * \p len must be at least 16 (in bytes)
  344. * to achieve a 128-bit strength.
  345. *
  346. * \param ctx The CTR_DRBG context.
  347. * \param len The amount of entropy to grab, in bytes.
  348. * This must be at most #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT
  349. * and at most the maximum length accepted by the
  350. * entropy function that is set in the context.
  351. */
  352. void mbedtls_ctr_drbg_set_entropy_len( mbedtls_ctr_drbg_context *ctx,
  353. size_t len );
  354. /**
  355. * \brief This function sets the amount of entropy grabbed
  356. * as a nonce for the initial seeding.
  357. *
  358. * Call this function before calling mbedtls_ctr_drbg_seed() to read
  359. * a nonce from the entropy source during the initial seeding.
  360. *
  361. * \param ctx The CTR_DRBG context.
  362. * \param len The amount of entropy to grab for the nonce, in bytes.
  363. * This must be at most #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT
  364. * and at most the maximum length accepted by the
  365. * entropy function that is set in the context.
  366. *
  367. * \return \c 0 on success.
  368. * \return #MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG if \p len is
  369. * more than #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT.
  370. * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED
  371. * if the initial seeding has already taken place.
  372. */
  373. int mbedtls_ctr_drbg_set_nonce_len( mbedtls_ctr_drbg_context *ctx,
  374. size_t len );
  375. /**
  376. * \brief This function sets the reseed interval.
  377. *
  378. * The reseed interval is the number of calls to mbedtls_ctr_drbg_random()
  379. * or mbedtls_ctr_drbg_random_with_add() after which the entropy function
  380. * is called again.
  381. *
  382. * The default value is #MBEDTLS_CTR_DRBG_RESEED_INTERVAL.
  383. *
  384. * \param ctx The CTR_DRBG context.
  385. * \param interval The reseed interval.
  386. */
  387. void mbedtls_ctr_drbg_set_reseed_interval( mbedtls_ctr_drbg_context *ctx,
  388. int interval );
  389. /**
  390. * \brief This function reseeds the CTR_DRBG context, that is
  391. * extracts data from the entropy source.
  392. *
  393. * \note This function is not thread-safe. It is not safe
  394. * to call this function if another thread might be
  395. * concurrently obtaining random numbers from the same
  396. * context or updating or reseeding the same context.
  397. *
  398. * \param ctx The CTR_DRBG context.
  399. * \param additional Additional data to add to the state. Can be \c NULL.
  400. * \param len The length of the additional data.
  401. * This must be less than
  402. * #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT - \c entropy_len
  403. * where \c entropy_len is the entropy length
  404. * configured for the context.
  405. *
  406. * \return \c 0 on success.
  407. * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure.
  408. */
  409. int mbedtls_ctr_drbg_reseed( mbedtls_ctr_drbg_context *ctx,
  410. const unsigned char *additional, size_t len );
  411. /**
  412. * \brief This function updates the state of the CTR_DRBG context.
  413. *
  414. * \note This function is not thread-safe. It is not safe
  415. * to call this function if another thread might be
  416. * concurrently obtaining random numbers from the same
  417. * context or updating or reseeding the same context.
  418. *
  419. * \param ctx The CTR_DRBG context.
  420. * \param additional The data to update the state with. This must not be
  421. * \c NULL unless \p add_len is \c 0.
  422. * \param add_len Length of \p additional in bytes. This must be at
  423. * most #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT.
  424. *
  425. * \return \c 0 on success.
  426. * \return #MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG if
  427. * \p add_len is more than
  428. * #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT.
  429. * \return An error from the underlying AES cipher on failure.
  430. */
  431. int mbedtls_ctr_drbg_update_ret( mbedtls_ctr_drbg_context *ctx,
  432. const unsigned char *additional,
  433. size_t add_len );
  434. /**
  435. * \brief This function updates a CTR_DRBG instance with additional
  436. * data and uses it to generate random data.
  437. *
  438. * This function automatically reseeds if the reseed counter is exceeded
  439. * or prediction resistance is enabled.
  440. *
  441. * \note This function is not thread-safe. It is not safe
  442. * to call this function if another thread might be
  443. * concurrently obtaining random numbers from the same
  444. * context or updating or reseeding the same context.
  445. *
  446. * \param p_rng The CTR_DRBG context. This must be a pointer to a
  447. * #mbedtls_ctr_drbg_context structure.
  448. * \param output The buffer to fill.
  449. * \param output_len The length of the buffer in bytes.
  450. * \param additional Additional data to update. Can be \c NULL, in which
  451. * case the additional data is empty regardless of
  452. * the value of \p add_len.
  453. * \param add_len The length of the additional data
  454. * if \p additional is not \c NULL.
  455. * This must be less than #MBEDTLS_CTR_DRBG_MAX_INPUT
  456. * and less than
  457. * #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT - \c entropy_len
  458. * where \c entropy_len is the entropy length
  459. * configured for the context.
  460. *
  461. * \return \c 0 on success.
  462. * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
  463. * #MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure.
  464. */
  465. int mbedtls_ctr_drbg_random_with_add( void *p_rng,
  466. unsigned char *output, size_t output_len,
  467. const unsigned char *additional, size_t add_len );
  468. /**
  469. * \brief This function uses CTR_DRBG to generate random data.
  470. *
  471. * This function automatically reseeds if the reseed counter is exceeded
  472. * or prediction resistance is enabled.
  473. */
  474. #if defined(MBEDTLS_THREADING_C)
  475. /**
  476. * \note When Mbed TLS is built with threading support,
  477. * it is safe to call mbedtls_ctr_drbg_random()
  478. * from multiple threads. Other operations, including
  479. * reseeding, are not thread-safe.
  480. */
  481. #endif /* MBEDTLS_THREADING_C */
  482. /**
  483. * \param p_rng The CTR_DRBG context. This must be a pointer to a
  484. * #mbedtls_ctr_drbg_context structure.
  485. * \param output The buffer to fill.
  486. * \param output_len The length of the buffer in bytes.
  487. *
  488. * \return \c 0 on success.
  489. * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
  490. * #MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure.
  491. */
  492. int mbedtls_ctr_drbg_random( void *p_rng,
  493. unsigned char *output, size_t output_len );
  494. #if ! defined(MBEDTLS_DEPRECATED_REMOVED)
  495. #if defined(MBEDTLS_DEPRECATED_WARNING)
  496. #define MBEDTLS_DEPRECATED __attribute__((deprecated))
  497. #else
  498. #define MBEDTLS_DEPRECATED
  499. #endif
  500. /**
  501. * \brief This function updates the state of the CTR_DRBG context.
  502. *
  503. * \deprecated Superseded by mbedtls_ctr_drbg_update_ret()
  504. * in 2.16.0.
  505. *
  506. * \note If \p add_len is greater than
  507. * #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT, only the first
  508. * #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT Bytes are used.
  509. * The remaining Bytes are silently discarded.
  510. *
  511. * \param ctx The CTR_DRBG context.
  512. * \param additional The data to update the state with.
  513. * \param add_len Length of \p additional data.
  514. */
  515. MBEDTLS_DEPRECATED void mbedtls_ctr_drbg_update(
  516. mbedtls_ctr_drbg_context *ctx,
  517. const unsigned char *additional,
  518. size_t add_len );
  519. #undef MBEDTLS_DEPRECATED
  520. #endif /* !MBEDTLS_DEPRECATED_REMOVED */
  521. #if defined(MBEDTLS_FS_IO)
  522. /**
  523. * \brief This function writes a seed file.
  524. *
  525. * \param ctx The CTR_DRBG context.
  526. * \param path The name of the file.
  527. *
  528. * \return \c 0 on success.
  529. * \return #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error.
  530. * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on reseed
  531. * failure.
  532. */
  533. int mbedtls_ctr_drbg_write_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path );
  534. /**
  535. * \brief This function reads and updates a seed file. The seed
  536. * is added to this instance.
  537. *
  538. * \param ctx The CTR_DRBG context.
  539. * \param path The name of the file.
  540. *
  541. * \return \c 0 on success.
  542. * \return #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error.
  543. * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on
  544. * reseed failure.
  545. * \return #MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG if the existing
  546. * seed file is too large.
  547. */
  548. int mbedtls_ctr_drbg_update_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path );
  549. #endif /* MBEDTLS_FS_IO */
  550. #if defined(MBEDTLS_SELF_TEST)
  551. /**
  552. * \brief The CTR_DRBG checkup routine.
  553. *
  554. * \return \c 0 on success.
  555. * \return \c 1 on failure.
  556. */
  557. int mbedtls_ctr_drbg_self_test( int verbose );
  558. #endif /* MBEDTLS_SELF_TEST */
  559. #ifdef __cplusplus
  560. }
  561. #endif
  562. #endif /* ctr_drbg.h */