blob: 0348281e41d5c8b139a3c5a6c6fad0f868c054d8 [file] [log] [blame]
Paul Bakker0e04d0e2011-11-27 14:46:59 +00001/**
2 * \file ctr_drbg.h
3 *
Gilles Peskineec51dd12019-09-30 15:01:02 +02004 * \brief This file contains definitions and functions for the
5 * CTR_DRBG pseudorandom generator.
Rose Zadikc9474eb2018-03-27 10:58:22 +01006 *
Rose Zadikf25eb6e2018-04-16 14:51:52 +01007 * 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>.
Rose Zadik2f8163d2018-01-25 21:55:14 +000011 *
Nir Sonnenscheineb73f7a2018-07-30 17:46:49 +030012 * The Mbed TLS implementation of CTR_DRBG uses AES-256 (default) or AES-128
Gilles Peskined0c64c82019-10-03 14:20:46 +020013 * (if \c MBEDTLS_CTR_DRBG_USE_128_BIT_KEY is enabled at compile time)
Gilles Peskinedddda812019-10-03 14:22:04 +020014 * as the underlying block cipher, with a derivation function.
Gilles Peskinedddda812019-10-03 14:22:04 +020015 *
Gilles Peskinee9a34542019-10-22 20:43:24 +020016 * 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
Bence Szépkútibb0cfeb2021-05-28 09:42:25 +020019 * kept at its default value (and not overridden in mbedtls_config.h) and that the
Gilles Peskinee9a34542019-10-22 20:43:24 +020020 * DRBG instance is set up with default parameters.
21 * See the documentation of mbedtls_ctr_drbg_seed() for more
22 * information.
Darryl Greena40a1012018-01-05 15:33:17 +000023 */
24/*
Bence Szépkúti1e148272020-08-07 13:07:28 +020025 * Copyright The Mbed TLS Contributors
Manuel Pégourié-Gonnard37ff1402015-09-04 14:21:07 +020026 * 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.
Paul Bakker0e04d0e2011-11-27 14:46:59 +000039 */
Rose Zadik2f8163d2018-01-25 21:55:14 +000040
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020041#ifndef MBEDTLS_CTR_DRBG_H
42#define MBEDTLS_CTR_DRBG_H
Mateusz Starzyk846f0212021-05-19 19:44:07 +020043#include "mbedtls/private_access.h"
Paul Bakker0e04d0e2011-11-27 14:46:59 +000044
Bence Szépkútic662b362021-05-27 11:25:03 +020045#include "mbedtls/build_info.h"
Andrzej Kurekc470b6b2019-01-31 08:20:20 -050046
Jaeden Ameroc49fbbf2019-07-04 20:01:14 +010047#include "mbedtls/aes.h"
Manuel Pégourié-Gonnard4011eb42023-03-21 17:10:45 +010048#include "entropy.h"
Paul Bakker0e04d0e2011-11-27 14:46:59 +000049
Manuel Pégourié-Gonnard0a4fb092015-05-07 12:50:31 +010050#if defined(MBEDTLS_THREADING_C)
Jaeden Ameroc49fbbf2019-07-04 20:01:14 +010051#include "mbedtls/threading.h"
Manuel Pégourié-Gonnard0a4fb092015-05-07 12:50:31 +010052#endif
53
Gilles Peskined2971572021-07-26 18:48:10 +020054/** The entropy source failed. */
55#define MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED -0x0034
56/** The requested random buffer length is too big. */
57#define MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG -0x0036
58/** The input (entropy + additional data) is too large. */
59#define MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG -0x0038
60/** Read or write error in file. */
61#define MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR -0x003A
Paul Bakker0e04d0e2011-11-27 14:46:59 +000062
Rose Zadik2f8163d2018-01-25 21:55:14 +000063#define MBEDTLS_CTR_DRBG_BLOCKSIZE 16 /**< The block size used by the cipher. */
Nir Sonnenscheince266e42018-08-29 10:11:46 +030064
Nir Sonnenschein43e4ff02018-09-03 14:15:46 +030065#if defined(MBEDTLS_CTR_DRBG_USE_128_BIT_KEY)
Gilles Peskine08875d42019-09-24 14:40:40 +020066#define MBEDTLS_CTR_DRBG_KEYSIZE 16
67/**< The key size in bytes used by the cipher.
68 *
69 * Compile-time choice: 16 bytes (128 bits)
Gilles Peskined0c64c82019-10-03 14:20:46 +020070 * because #MBEDTLS_CTR_DRBG_USE_128_BIT_KEY is enabled.
Gilles Peskine08875d42019-09-24 14:40:40 +020071 */
Nir Sonnenscheineb73f7a2018-07-30 17:46:49 +030072#else
Gilles Peskine08875d42019-09-24 14:40:40 +020073#define MBEDTLS_CTR_DRBG_KEYSIZE 32
74/**< The key size in bytes used by the cipher.
75 *
76 * Compile-time choice: 32 bytes (256 bits)
Gilles Peskined0c64c82019-10-03 14:20:46 +020077 * because \c MBEDTLS_CTR_DRBG_USE_128_BIT_KEY is disabled.
Gilles Peskine08875d42019-09-24 14:40:40 +020078 */
Nir Sonnenscheina4588d42018-07-30 16:59:36 +030079#endif
Nir Sonnenschein43e4ff02018-09-03 14:15:46 +030080
Gilles Peskine449bd832023-01-11 14:50:10 +010081#define MBEDTLS_CTR_DRBG_KEYBITS (MBEDTLS_CTR_DRBG_KEYSIZE * 8) /**< The key size for the DRBG operation, in bits. */
82#define MBEDTLS_CTR_DRBG_SEEDLEN (MBEDTLS_CTR_DRBG_KEYSIZE + MBEDTLS_CTR_DRBG_BLOCKSIZE) /**< The seed length, calculated as (counter + AES key). */
Paul Bakker9bcf16c2013-06-24 19:31:17 +020083
Paul Bakker088c5c52014-04-25 11:11:10 +020084/**
85 * \name SECTION: Module settings
86 *
87 * The configuration options you can set for this module are in this section.
Bence Szépkútibb0cfeb2021-05-28 09:42:25 +020088 * Either change them in mbedtls_config.h or define them using the compiler command
Rose Zadik2f8163d2018-01-25 21:55:14 +000089 * line.
Paul Bakker088c5c52014-04-25 11:11:10 +020090 * \{
91 */
92
Gilles Peskinedddda812019-10-03 14:22:04 +020093/** \def MBEDTLS_CTR_DRBG_ENTROPY_LEN
94 *
95 * \brief The amount of entropy used per seed by default, in bytes.
96 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020097#if !defined(MBEDTLS_CTR_DRBG_ENTROPY_LEN)
Manuel Pégourié-Gonnard4011eb42023-03-21 17:10:45 +010098#if defined(MBEDTLS_ENTROPY_SHA512_ACCUMULATOR)
99/** This is 48 bytes because the entropy module uses SHA-512.
Gilles Peskine08875d42019-09-24 14:40:40 +0200100 */
Rose Zadik2f8163d2018-01-25 21:55:14 +0000101#define MBEDTLS_CTR_DRBG_ENTROPY_LEN 48
Gilles Peskinedddda812019-10-03 14:22:04 +0200102
Manuel Pégourié-Gonnard4011eb42023-03-21 17:10:45 +0100103#else /* MBEDTLS_ENTROPY_SHA512_ACCUMULATOR */
Gilles Peskinedddda812019-10-03 14:22:04 +0200104
Manuel Pégourié-Gonnard4011eb42023-03-21 17:10:45 +0100105/** This is 32 bytes because the entropy module uses SHA-256.
Rose Zadik2f8163d2018-01-25 21:55:14 +0000106 */
Gilles Peskinedddda812019-10-03 14:22:04 +0200107#if !defined(MBEDTLS_CTR_DRBG_USE_128_BIT_KEY)
108/** \warning To achieve a 256-bit security strength, you must pass a nonce
109 * to mbedtls_ctr_drbg_seed().
110 */
111#endif /* !defined(MBEDTLS_CTR_DRBG_USE_128_BIT_KEY) */
Gilles Peskine08875d42019-09-24 14:40:40 +0200112#define MBEDTLS_CTR_DRBG_ENTROPY_LEN 32
Manuel Pégourié-Gonnard4011eb42023-03-21 17:10:45 +0100113#endif /* MBEDTLS_ENTROPY_SHA512_ACCUMULATOR */
Gilles Peskinedddda812019-10-03 14:22:04 +0200114#endif /* !defined(MBEDTLS_CTR_DRBG_ENTROPY_LEN) */
Paul Bakker088c5c52014-04-25 11:11:10 +0200115
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200116#if !defined(MBEDTLS_CTR_DRBG_RESEED_INTERVAL)
Rose Zadik2f8163d2018-01-25 21:55:14 +0000117#define MBEDTLS_CTR_DRBG_RESEED_INTERVAL 10000
118/**< The interval before reseed is performed by default. */
Paul Bakker088c5c52014-04-25 11:11:10 +0200119#endif
120
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200121#if !defined(MBEDTLS_CTR_DRBG_MAX_INPUT)
Rose Zadik2f8163d2018-01-25 21:55:14 +0000122#define MBEDTLS_CTR_DRBG_MAX_INPUT 256
123/**< The maximum number of additional input Bytes. */
Paul Bakker088c5c52014-04-25 11:11:10 +0200124#endif
125
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200126#if !defined(MBEDTLS_CTR_DRBG_MAX_REQUEST)
Rose Zadik2f8163d2018-01-25 21:55:14 +0000127#define MBEDTLS_CTR_DRBG_MAX_REQUEST 1024
128/**< The maximum number of requested Bytes per call. */
Paul Bakker088c5c52014-04-25 11:11:10 +0200129#endif
130
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200131#if !defined(MBEDTLS_CTR_DRBG_MAX_SEED_INPUT)
Rose Zadik2f8163d2018-01-25 21:55:14 +0000132#define MBEDTLS_CTR_DRBG_MAX_SEED_INPUT 384
Gilles Peskine08875d42019-09-24 14:40:40 +0200133/**< The maximum size of seed or reseed buffer in bytes. */
Paul Bakker088c5c52014-04-25 11:11:10 +0200134#endif
135
Andrzej Kurek38d4fdd2021-12-28 16:22:52 +0100136/** \} name SECTION: Module settings */
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000137
Rose Zadik2f8163d2018-01-25 21:55:14 +0000138#define MBEDTLS_CTR_DRBG_PR_OFF 0
139/**< Prediction resistance is disabled. */
140#define MBEDTLS_CTR_DRBG_PR_ON 1
141/**< Prediction resistance is enabled. */
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000142
143#ifdef __cplusplus
144extern "C" {
145#endif
146
Gilles Peskine69971662019-10-23 19:39:36 +0200147#if MBEDTLS_CTR_DRBG_ENTROPY_LEN >= MBEDTLS_CTR_DRBG_KEYSIZE * 3 / 2
148/** The default length of the nonce read from the entropy source.
149 *
150 * This is \c 0 because a single read from the entropy source is sufficient
151 * to include a nonce.
152 * See the documentation of mbedtls_ctr_drbg_seed() for more information.
153 */
154#define MBEDTLS_CTR_DRBG_ENTROPY_NONCE_LEN 0
155#else
156/** The default length of the nonce read from the entropy source.
157 *
158 * This is half of the default entropy length because a single read from
159 * the entropy source does not provide enough material to form a nonce.
160 * See the documentation of mbedtls_ctr_drbg_seed() for more information.
161 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100162#define MBEDTLS_CTR_DRBG_ENTROPY_NONCE_LEN (MBEDTLS_CTR_DRBG_ENTROPY_LEN + 1) / 2
Gilles Peskine69971662019-10-23 19:39:36 +0200163#endif
164
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000165/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000166 * \brief The CTR_DRBG context structure.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000167 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100168typedef struct mbedtls_ctr_drbg_context {
Mateusz Starzyk846f0212021-05-19 19:44:07 +0200169 unsigned char MBEDTLS_PRIVATE(counter)[16]; /*!< The counter (V). */
170 int MBEDTLS_PRIVATE(reseed_counter); /*!< The reseed counter.
Gilles Peskine449bd832023-01-11 14:50:10 +0100171 * This is the number of requests that have
172 * been made since the last (re)seeding,
173 * minus one.
174 * Before the initial seeding, this field
175 * contains the amount of entropy in bytes
176 * to use as a nonce for the initial seeding,
177 * or -1 if no nonce length has been explicitly
178 * set (see mbedtls_ctr_drbg_set_nonce_len()).
179 */
Mateusz Starzyk846f0212021-05-19 19:44:07 +0200180 int MBEDTLS_PRIVATE(prediction_resistance); /*!< This determines whether prediction
Gilles Peskine449bd832023-01-11 14:50:10 +0100181 resistance is enabled, that is
182 whether to systematically reseed before
183 each random generation. */
Mateusz Starzyk846f0212021-05-19 19:44:07 +0200184 size_t MBEDTLS_PRIVATE(entropy_len); /*!< The amount of entropy grabbed on each
Gilles Peskine449bd832023-01-11 14:50:10 +0100185 seed or reseed operation, in bytes. */
Mateusz Starzyk846f0212021-05-19 19:44:07 +0200186 int MBEDTLS_PRIVATE(reseed_interval); /*!< The reseed interval.
Gilles Peskine449bd832023-01-11 14:50:10 +0100187 * This is the maximum number of requests
188 * that can be made between reseedings. */
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000189
Mateusz Starzyk846f0212021-05-19 19:44:07 +0200190 mbedtls_aes_context MBEDTLS_PRIVATE(aes_ctx); /*!< The AES context. */
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000191
192 /*
193 * Callbacks (Entropy)
194 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100195 int(*MBEDTLS_PRIVATE(f_entropy))(void *, unsigned char *, size_t);
196 /*!< The entropy callback function. */
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000197
Mateusz Starzyk846f0212021-05-19 19:44:07 +0200198 void *MBEDTLS_PRIVATE(p_entropy); /*!< The context for the entropy function. */
Manuel Pégourié-Gonnard0a4fb092015-05-07 12:50:31 +0100199
200#if defined(MBEDTLS_THREADING_C)
Gilles Peskineda290f92021-02-09 18:44:02 +0100201 /* Invariant: the mutex is initialized if and only if f_entropy != NULL.
202 * This means that the mutex is initialized during the initial seeding
203 * in mbedtls_ctr_drbg_seed() and freed in mbedtls_ctr_drbg_free().
204 *
205 * Note that this invariant may change without notice. Do not rely on it
206 * and do not access the mutex directly in application code.
207 */
Mateusz Starzyk846f0212021-05-19 19:44:07 +0200208 mbedtls_threading_mutex_t MBEDTLS_PRIVATE(mutex);
Manuel Pégourié-Gonnard0a4fb092015-05-07 12:50:31 +0100209#endif
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000210}
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200211mbedtls_ctr_drbg_context;
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000212
213/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000214 * \brief This function initializes the CTR_DRBG context,
215 * and prepares it for mbedtls_ctr_drbg_seed()
216 * or mbedtls_ctr_drbg_free().
Manuel Pégourié-Gonnard8d128ef2015-04-28 22:38:08 +0200217 *
Gavin Acquroff6aceb512020-03-01 17:06:11 -0800218 * \note The reseed interval is
219 * #MBEDTLS_CTR_DRBG_RESEED_INTERVAL by default.
220 * You can override it by calling
221 * mbedtls_ctr_drbg_set_reseed_interval().
222 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000223 * \param ctx The CTR_DRBG context to initialize.
Manuel Pégourié-Gonnard8d128ef2015-04-28 22:38:08 +0200224 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100225void mbedtls_ctr_drbg_init(mbedtls_ctr_drbg_context *ctx);
Manuel Pégourié-Gonnard8d128ef2015-04-28 22:38:08 +0200226
227/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000228 * \brief This function seeds and sets up the CTR_DRBG
229 * entropy source for future reseeds.
Paul Bakker9af723c2014-05-01 13:03:14 +0200230 *
Gilles Peskine223deea2019-09-24 14:48:53 +0200231 * A typical choice for the \p f_entropy and \p p_entropy parameters is
232 * to use the entropy module:
233 * - \p f_entropy is mbedtls_entropy_func();
234 * - \p p_entropy is an instance of ::mbedtls_entropy_context initialized
235 * with mbedtls_entropy_init() (which registers the platform's default
236 * entropy sources).
237 *
Gilles Peskine50ed86b2019-10-04 12:15:55 +0200238 * The entropy length is #MBEDTLS_CTR_DRBG_ENTROPY_LEN by default.
239 * You can override it by calling mbedtls_ctr_drbg_set_entropy_len().
Gilles Peskineec51dd12019-09-30 15:01:02 +0200240 *
Gilles Peskinee9a34542019-10-22 20:43:24 +0200241 * The entropy nonce length is:
242 * - \c 0 if the entropy length is at least 3/2 times the entropy length,
243 * which guarantees that the security strength is the maximum permitted
244 * by the key size and entropy length according to NIST SP 800-90A §10.2.1;
245 * - Half the entropy length otherwise.
246 * You can override it by calling mbedtls_ctr_drbg_set_nonce_len().
Gilles Peskine69971662019-10-23 19:39:36 +0200247 * With the default entropy length, the entropy nonce length is
248 * #MBEDTLS_CTR_DRBG_ENTROPY_NONCE_LEN.
249 *
Gilles Peskine9be50982019-10-22 18:42:27 +0200250 * You can provide a nonce and personalization string in addition to the
Gilles Peskine223deea2019-09-24 14:48:53 +0200251 * entropy source, to make this instantiation as unique as possible.
Gilles Peskine9be50982019-10-22 18:42:27 +0200252 * See SP 800-90A §8.6.7 for more details about nonces.
Gilles Peskine223deea2019-09-24 14:48:53 +0200253 *
Gilles Peskine9be50982019-10-22 18:42:27 +0200254 * The _seed_material_ value passed to the derivation function in
255 * the CTR_DRBG Instantiate Process described in NIST SP 800-90A §10.2.1.3.2
256 * is the concatenation of the following strings:
257 * - A string obtained by calling \p f_entropy function for the entropy
258 * length.
Gilles Peskinee9a34542019-10-22 20:43:24 +0200259 */
Gilles Peskine69971662019-10-23 19:39:36 +0200260#if MBEDTLS_CTR_DRBG_ENTROPY_NONCE_LEN == 0
Gilles Peskinee9a34542019-10-22 20:43:24 +0200261/**
262 * - If mbedtls_ctr_drbg_set_nonce_len() has been called, a string
263 * obtained by calling \p f_entropy function for the specified length.
264 */
265#else
266/**
267 * - A string obtained by calling \p f_entropy function for the entropy nonce
268 * length. If the entropy nonce length is \c 0, this function does not
269 * make a second call to \p f_entropy.
270 */
271#endif
Gilles Peskinef305d922021-02-09 18:44:18 +0100272#if defined(MBEDTLS_THREADING_C)
273/**
274 * \note When Mbed TLS is built with threading support,
275 * after this function returns successfully,
276 * it is safe to call mbedtls_ctr_drbg_random()
277 * from multiple threads. Other operations, including
278 * reseeding, are not thread-safe.
279 */
280#endif /* MBEDTLS_THREADING_C */
Gilles Peskinee9a34542019-10-22 20:43:24 +0200281/**
Gilles Peskine9be50982019-10-22 18:42:27 +0200282 * - The \p custom string.
283 *
284 * \note To achieve the nominal security strength permitted
285 * by CTR_DRBG, the entropy length must be:
286 * - at least 16 bytes for a 128-bit strength
287 * (maximum achievable strength when using AES-128);
288 * - at least 32 bytes for a 256-bit strength
289 * (maximum achievable strength when using AES-256).
290 *
291 * In addition, if you do not pass a nonce in \p custom,
292 * the sum of the entropy length
Gilles Peskinee9a34542019-10-22 20:43:24 +0200293 * and the entropy nonce length must be:
Gilles Peskine9be50982019-10-22 18:42:27 +0200294 * - at least 24 bytes for a 128-bit strength
295 * (maximum achievable strength when using AES-128);
296 * - at least 48 bytes for a 256-bit strength
297 * (maximum achievable strength when using AES-256).
298 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000299 * \param ctx The CTR_DRBG context to seed.
Gilles Peskinebd326f92019-10-28 17:33:07 +0100300 * It must have been initialized with
301 * mbedtls_ctr_drbg_init().
302 * After a successful call to mbedtls_ctr_drbg_seed(),
303 * you may not call mbedtls_ctr_drbg_seed() again on
304 * the same context unless you call
305 * mbedtls_ctr_drbg_free() and mbedtls_ctr_drbg_init()
306 * again first.
Gilles Peskinef305d922021-02-09 18:44:18 +0100307 * After a failed call to mbedtls_ctr_drbg_seed(),
308 * you must call mbedtls_ctr_drbg_free().
Rose Zadik2f8163d2018-01-25 21:55:14 +0000309 * \param f_entropy The entropy callback, taking as arguments the
310 * \p p_entropy context, the buffer to fill, and the
Gilles Peskine08875d42019-09-24 14:40:40 +0200311 * length of the buffer.
Gilles Peskine50ed86b2019-10-04 12:15:55 +0200312 * \p f_entropy is always called with a buffer size
Gilles Peskine9be50982019-10-22 18:42:27 +0200313 * less than or equal to the entropy length.
Gilles Peskineec51dd12019-09-30 15:01:02 +0200314 * \param p_entropy The entropy context to pass to \p f_entropy.
Gilles Peskine217b8152019-10-01 18:39:45 +0200315 * \param custom The personalization string.
316 * This can be \c NULL, in which case the personalization
317 * string is empty regardless of the value of \p len.
318 * \param len The length of the personalization string.
Gilles Peskine944bc582019-09-24 14:48:30 +0200319 * This must be at most
320 * #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT
321 * - #MBEDTLS_CTR_DRBG_ENTROPY_LEN.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000322 *
Rose Zadikc9474eb2018-03-27 10:58:22 +0100323 * \return \c 0 on success.
324 * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000325 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100326int mbedtls_ctr_drbg_seed(mbedtls_ctr_drbg_context *ctx,
327 int (*f_entropy)(void *, unsigned char *, size_t),
328 void *p_entropy,
329 const unsigned char *custom,
330 size_t len);
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000331
332/**
Gavin Acquroff6aceb512020-03-01 17:06:11 -0800333 * \brief This function resets CTR_DRBG context to the state immediately
334 * after initial call of mbedtls_ctr_drbg_init().
Paul Bakkerfff03662014-06-18 16:21:25 +0200335 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000336 * \param ctx The CTR_DRBG context to clear.
Paul Bakkerfff03662014-06-18 16:21:25 +0200337 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100338void mbedtls_ctr_drbg_free(mbedtls_ctr_drbg_context *ctx);
Paul Bakkerfff03662014-06-18 16:21:25 +0200339
340/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000341 * \brief This function turns prediction resistance on or off.
342 * The default value is off.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000343 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000344 * \note If enabled, entropy is gathered at the beginning of
Gilles Peskineec51dd12019-09-30 15:01:02 +0200345 * every call to mbedtls_ctr_drbg_random_with_add()
346 * or mbedtls_ctr_drbg_random().
Rose Zadik2f8163d2018-01-25 21:55:14 +0000347 * Only use this if your entropy source has sufficient
348 * throughput.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000349 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000350 * \param ctx The CTR_DRBG context.
351 * \param resistance #MBEDTLS_CTR_DRBG_PR_ON or #MBEDTLS_CTR_DRBG_PR_OFF.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000352 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100353void mbedtls_ctr_drbg_set_prediction_resistance(mbedtls_ctr_drbg_context *ctx,
354 int resistance);
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000355
356/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000357 * \brief This function sets the amount of entropy grabbed on each
Gilles Peskine50ed86b2019-10-04 12:15:55 +0200358 * seed or reseed.
Gilles Peskineec51dd12019-09-30 15:01:02 +0200359 *
360 * The default value is #MBEDTLS_CTR_DRBG_ENTROPY_LEN.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000361 *
Gilles Peskinedddda812019-10-03 14:22:04 +0200362 * \note The security strength of CTR_DRBG is bounded by the
363 * entropy length. Thus:
364 * - When using AES-256
365 * (\c MBEDTLS_CTR_DRBG_USE_128_BIT_KEY is disabled,
366 * which is the default),
367 * \p len must be at least 32 (in bytes)
368 * to achieve a 256-bit strength.
369 * - When using AES-128
370 * (\c MBEDTLS_CTR_DRBG_USE_128_BIT_KEY is enabled)
371 * \p len must be at least 16 (in bytes)
372 * to achieve a 128-bit strength.
Gilles Peskine223deea2019-09-24 14:48:53 +0200373 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000374 * \param ctx The CTR_DRBG context.
Gilles Peskine08875d42019-09-24 14:40:40 +0200375 * \param len The amount of entropy to grab, in bytes.
Gilles Peskine9be50982019-10-22 18:42:27 +0200376 * This must be at most #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT
377 * and at most the maximum length accepted by the
378 * entropy function that is set in the context.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000379 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100380void mbedtls_ctr_drbg_set_entropy_len(mbedtls_ctr_drbg_context *ctx,
381 size_t len);
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000382
383/**
Gilles Peskine9be50982019-10-22 18:42:27 +0200384 * \brief This function sets the amount of entropy grabbed
385 * as a nonce for the initial seeding.
386 *
387 * Call this function before calling mbedtls_ctr_drbg_seed() to read
388 * a nonce from the entropy source during the initial seeding.
389 *
390 * \param ctx The CTR_DRBG context.
391 * \param len The amount of entropy to grab for the nonce, in bytes.
392 * This must be at most #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT
393 * and at most the maximum length accepted by the
394 * entropy function that is set in the context.
395 *
396 * \return \c 0 on success.
397 * \return #MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG if \p len is
398 * more than #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT.
399 * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED
400 * if the initial seeding has already taken place.
401 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100402int mbedtls_ctr_drbg_set_nonce_len(mbedtls_ctr_drbg_context *ctx,
403 size_t len);
Gilles Peskine9be50982019-10-22 18:42:27 +0200404
405/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000406 * \brief This function sets the reseed interval.
Gilles Peskineec51dd12019-09-30 15:01:02 +0200407 *
408 * The reseed interval is the number of calls to mbedtls_ctr_drbg_random()
409 * or mbedtls_ctr_drbg_random_with_add() after which the entropy function
410 * is called again.
411 *
412 * The default value is #MBEDTLS_CTR_DRBG_RESEED_INTERVAL.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000413 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000414 * \param ctx The CTR_DRBG context.
415 * \param interval The reseed interval.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000416 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100417void mbedtls_ctr_drbg_set_reseed_interval(mbedtls_ctr_drbg_context *ctx,
418 int interval);
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000419
420/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000421 * \brief This function reseeds the CTR_DRBG context, that is
422 * extracts data from the entropy source.
Paul Bakker9af723c2014-05-01 13:03:14 +0200423 *
Gilles Peskinef305d922021-02-09 18:44:18 +0100424 * \note This function is not thread-safe. It is not safe
425 * to call this function if another thread might be
426 * concurrently obtaining random numbers from the same
427 * context or updating or reseeding the same context.
428 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000429 * \param ctx The CTR_DRBG context.
Gilles Peskine10f16ac2019-10-01 18:30:02 +0200430 * \param additional Additional data to add to the state. Can be \c NULL.
Rose Zadik2f8163d2018-01-25 21:55:14 +0000431 * \param len The length of the additional data.
Gilles Peskine944bc582019-09-24 14:48:30 +0200432 * This must be less than
433 * #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT - \c entropy_len
434 * where \c entropy_len is the entropy length
435 * configured for the context.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000436 *
Rose Zadikc9474eb2018-03-27 10:58:22 +0100437 * \return \c 0 on success.
438 * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000439 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100440int mbedtls_ctr_drbg_reseed(mbedtls_ctr_drbg_context *ctx,
441 const unsigned char *additional, size_t len);
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000442
443/**
Rose Zadikc9474eb2018-03-27 10:58:22 +0100444 * \brief This function updates the state of the CTR_DRBG context.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000445 *
Gilles Peskinef305d922021-02-09 18:44:18 +0100446 * \note This function is not thread-safe. It is not safe
447 * to call this function if another thread might be
448 * concurrently obtaining random numbers from the same
449 * context or updating or reseeding the same context.
450 *
Rose Zadikc9474eb2018-03-27 10:58:22 +0100451 * \param ctx The CTR_DRBG context.
Gilles Peskine08875d42019-09-24 14:40:40 +0200452 * \param additional The data to update the state with. This must not be
Gilles Peskine10f16ac2019-10-01 18:30:02 +0200453 * \c NULL unless \p add_len is \c 0.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500454 * \param add_len Length of \p additional in bytes. This must be at
455 * most #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT.
Rose Zadikc9474eb2018-03-27 10:58:22 +0100456 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500457 * \return \c 0 on success.
458 * \return #MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG if
459 * \p add_len is more than
460 * #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT.
461 * \return An error from the underlying AES cipher on failure.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000462 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100463int mbedtls_ctr_drbg_update(mbedtls_ctr_drbg_context *ctx,
464 const unsigned char *additional,
465 size_t add_len);
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000466
467/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000468 * \brief This function updates a CTR_DRBG instance with additional
469 * data and uses it to generate random data.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000470 *
Gilles Peskine2d8f0692019-10-01 18:31:28 +0200471 * This function automatically reseeds if the reseed counter is exceeded
472 * or prediction resistance is enabled.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000473 *
Gilles Peskinef305d922021-02-09 18:44:18 +0100474 * \note This function is not thread-safe. It is not safe
475 * to call this function if another thread might be
476 * concurrently obtaining random numbers from the same
477 * context or updating or reseeding the same context.
478 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000479 * \param p_rng The CTR_DRBG context. This must be a pointer to a
480 * #mbedtls_ctr_drbg_context structure.
481 * \param output The buffer to fill.
Gilles Peskineec51dd12019-09-30 15:01:02 +0200482 * \param output_len The length of the buffer in bytes.
Gilles Peskine10f16ac2019-10-01 18:30:02 +0200483 * \param additional Additional data to update. Can be \c NULL, in which
Gilles Peskine08875d42019-09-24 14:40:40 +0200484 * case the additional data is empty regardless of
485 * the value of \p add_len.
486 * \param add_len The length of the additional data
Gilles Peskine10f16ac2019-10-01 18:30:02 +0200487 * if \p additional is not \c NULL.
Gilles Peskine944bc582019-09-24 14:48:30 +0200488 * This must be less than #MBEDTLS_CTR_DRBG_MAX_INPUT
489 * and less than
490 * #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT - \c entropy_len
491 * where \c entropy_len is the entropy length
492 * configured for the context.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000493 *
Rose Zadikc9474eb2018-03-27 10:58:22 +0100494 * \return \c 0 on success.
495 * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
Rose Zadik2f8163d2018-01-25 21:55:14 +0000496 * #MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000497 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100498int mbedtls_ctr_drbg_random_with_add(void *p_rng,
499 unsigned char *output, size_t output_len,
500 const unsigned char *additional, size_t add_len);
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000501
502/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000503 * \brief This function uses CTR_DRBG to generate random data.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000504 *
Gilles Peskine2d8f0692019-10-01 18:31:28 +0200505 * This function automatically reseeds if the reseed counter is exceeded
506 * or prediction resistance is enabled.
Gilles Peskinef305d922021-02-09 18:44:18 +0100507 */
508#if defined(MBEDTLS_THREADING_C)
509/**
510 * \note When Mbed TLS is built with threading support,
511 * it is safe to call mbedtls_ctr_drbg_random()
512 * from multiple threads. Other operations, including
513 * reseeding, are not thread-safe.
514 */
515#endif /* MBEDTLS_THREADING_C */
516/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000517 * \param p_rng The CTR_DRBG context. This must be a pointer to a
518 * #mbedtls_ctr_drbg_context structure.
519 * \param output The buffer to fill.
Gilles Peskine944bc582019-09-24 14:48:30 +0200520 * \param output_len The length of the buffer in bytes.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000521 *
Rose Zadikc9474eb2018-03-27 10:58:22 +0100522 * \return \c 0 on success.
523 * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
Rose Zadik2f8163d2018-01-25 21:55:14 +0000524 * #MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000525 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100526int mbedtls_ctr_drbg_random(void *p_rng,
527 unsigned char *output, size_t output_len);
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000528
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200529#if defined(MBEDTLS_FS_IO)
Paul Bakkerfc754a92011-12-05 13:23:51 +0000530/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000531 * \brief This function writes a seed file.
Paul Bakkerfc754a92011-12-05 13:23:51 +0000532 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000533 * \param ctx The CTR_DRBG context.
534 * \param path The name of the file.
Paul Bakkerfc754a92011-12-05 13:23:51 +0000535 *
Rose Zadikc9474eb2018-03-27 10:58:22 +0100536 * \return \c 0 on success.
Rose Zadikf25eb6e2018-04-16 14:51:52 +0100537 * \return #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error.
Gilles Peskineec51dd12019-09-30 15:01:02 +0200538 * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on reseed
Rose Zadik2f8163d2018-01-25 21:55:14 +0000539 * failure.
Paul Bakkerfc754a92011-12-05 13:23:51 +0000540 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100541int mbedtls_ctr_drbg_write_seed_file(mbedtls_ctr_drbg_context *ctx, const char *path);
Paul Bakkerfc754a92011-12-05 13:23:51 +0000542
543/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000544 * \brief This function reads and updates a seed file. The seed
545 * is added to this instance.
Paul Bakkerfc754a92011-12-05 13:23:51 +0000546 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000547 * \param ctx The CTR_DRBG context.
548 * \param path The name of the file.
Paul Bakkerfc754a92011-12-05 13:23:51 +0000549 *
Rose Zadikc9474eb2018-03-27 10:58:22 +0100550 * \return \c 0 on success.
551 * \return #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error.
Gilles Peskineec51dd12019-09-30 15:01:02 +0200552 * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on
553 * reseed failure.
554 * \return #MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG if the existing
555 * seed file is too large.
Paul Bakkerfc754a92011-12-05 13:23:51 +0000556 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100557int mbedtls_ctr_drbg_update_seed_file(mbedtls_ctr_drbg_context *ctx, const char *path);
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200558#endif /* MBEDTLS_FS_IO */
Paul Bakkerfc754a92011-12-05 13:23:51 +0000559
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500560#if defined(MBEDTLS_SELF_TEST)
561
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000562/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000563 * \brief The CTR_DRBG checkup routine.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000564 *
Rose Zadikc9474eb2018-03-27 10:58:22 +0100565 * \return \c 0 on success.
566 * \return \c 1 on failure.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000567 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100568int mbedtls_ctr_drbg_self_test(int verbose);
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000569
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500570#endif /* MBEDTLS_SELF_TEST */
571
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000572#ifdef __cplusplus
573}
574#endif
575
576#endif /* ctr_drbg.h */