blob: 550006eefd65ea6724a7a077527df6b7f0d7a90c [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
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.
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
Paul Bakker0e04d0e2011-11-27 14:46:59 +000043
Andrzej Kurekc470b6b2019-01-31 08:20:20 -050044#if !defined(MBEDTLS_CONFIG_FILE)
Jaeden Ameroc49fbbf2019-07-04 20:01:14 +010045#include "mbedtls/config.h"
Andrzej Kurekc470b6b2019-01-31 08:20:20 -050046#else
47#include MBEDTLS_CONFIG_FILE
48#endif
49
Jaeden Ameroc49fbbf2019-07-04 20:01:14 +010050#include "mbedtls/aes.h"
Paul Bakker0e04d0e2011-11-27 14:46:59 +000051
Manuel Pégourié-Gonnard0a4fb092015-05-07 12:50:31 +010052#if defined(MBEDTLS_THREADING_C)
Jaeden Ameroc49fbbf2019-07-04 20:01:14 +010053#include "mbedtls/threading.h"
Manuel Pégourié-Gonnard0a4fb092015-05-07 12:50:31 +010054#endif
55
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020056#define MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED -0x0034 /**< The entropy source failed. */
Rose Zadik2f8163d2018-01-25 21:55:14 +000057#define MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG -0x0036 /**< The requested random buffer length is too big. */
58#define MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG -0x0038 /**< The input (entropy + additional data) is too large. */
59#define MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR -0x003A /**< Read or write error in file. */
Paul Bakker0e04d0e2011-11-27 14:46:59 +000060
Rose Zadik2f8163d2018-01-25 21:55:14 +000061#define MBEDTLS_CTR_DRBG_BLOCKSIZE 16 /**< The block size used by the cipher. */
Nir Sonnenscheince266e42018-08-29 10:11:46 +030062
Nir Sonnenschein43e4ff02018-09-03 14:15:46 +030063#if defined(MBEDTLS_CTR_DRBG_USE_128_BIT_KEY)
Gilles Peskine08875d42019-09-24 14:40:40 +020064#define MBEDTLS_CTR_DRBG_KEYSIZE 16
65/**< The key size in bytes used by the cipher.
66 *
67 * Compile-time choice: 16 bytes (128 bits)
Gilles Peskined0c64c82019-10-03 14:20:46 +020068 * because #MBEDTLS_CTR_DRBG_USE_128_BIT_KEY is enabled.
Gilles Peskine08875d42019-09-24 14:40:40 +020069 */
Nir Sonnenscheineb73f7a2018-07-30 17:46:49 +030070#else
Gilles Peskine08875d42019-09-24 14:40:40 +020071#define MBEDTLS_CTR_DRBG_KEYSIZE 32
72/**< The key size in bytes used by the cipher.
73 *
74 * Compile-time choice: 32 bytes (256 bits)
Gilles Peskined0c64c82019-10-03 14:20:46 +020075 * because \c MBEDTLS_CTR_DRBG_USE_128_BIT_KEY is disabled.
Gilles Peskine08875d42019-09-24 14:40:40 +020076 */
Nir Sonnenscheina4588d42018-07-30 16:59:36 +030077#endif
Nir Sonnenschein43e4ff02018-09-03 14:15:46 +030078
Rose Zadik2f8163d2018-01-25 21:55:14 +000079#define MBEDTLS_CTR_DRBG_KEYBITS ( MBEDTLS_CTR_DRBG_KEYSIZE * 8 ) /**< The key size for the DRBG operation, in bits. */
80#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 +020081
Paul Bakker088c5c52014-04-25 11:11:10 +020082/**
83 * \name SECTION: Module settings
84 *
85 * The configuration options you can set for this module are in this section.
Rose Zadik2f8163d2018-01-25 21:55:14 +000086 * Either change them in config.h or define them using the compiler command
87 * line.
Paul Bakker088c5c52014-04-25 11:11:10 +020088 * \{
89 */
90
Gilles Peskinedddda812019-10-03 14:22:04 +020091/** \def MBEDTLS_CTR_DRBG_ENTROPY_LEN
92 *
93 * \brief The amount of entropy used per seed by default, in bytes.
94 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020095#if !defined(MBEDTLS_CTR_DRBG_ENTROPY_LEN)
96#if defined(MBEDTLS_SHA512_C) && !defined(MBEDTLS_ENTROPY_FORCE_SHA256)
Gilles Peskinedddda812019-10-03 14:22:04 +020097/** This is 48 bytes because the entropy module uses SHA-512
Gilles Peskined0c64c82019-10-03 14:20:46 +020098 * (\c MBEDTLS_ENTROPY_FORCE_SHA256 is disabled).
Gilles Peskine08875d42019-09-24 14:40:40 +020099 */
Rose Zadik2f8163d2018-01-25 21:55:14 +0000100#define MBEDTLS_CTR_DRBG_ENTROPY_LEN 48
Gilles Peskinedddda812019-10-03 14:22:04 +0200101
102#else /* defined(MBEDTLS_SHA512_C) && !defined(MBEDTLS_ENTROPY_FORCE_SHA256) */
103
104/** This is 32 bytes because the entropy module uses SHA-256
105 * (the SHA512 module is disabled or
106 * \c MBEDTLS_ENTROPY_FORCE_SHA256 is enabled).
Rose Zadik2f8163d2018-01-25 21:55:14 +0000107 */
Gilles Peskinedddda812019-10-03 14:22:04 +0200108#if !defined(MBEDTLS_CTR_DRBG_USE_128_BIT_KEY)
109/** \warning To achieve a 256-bit security strength, you must pass a nonce
110 * to mbedtls_ctr_drbg_seed().
111 */
112#endif /* !defined(MBEDTLS_CTR_DRBG_USE_128_BIT_KEY) */
Gilles Peskine08875d42019-09-24 14:40:40 +0200113#define MBEDTLS_CTR_DRBG_ENTROPY_LEN 32
Gilles Peskinedddda812019-10-03 14:22:04 +0200114#endif /* defined(MBEDTLS_SHA512_C) && !defined(MBEDTLS_ENTROPY_FORCE_SHA256) */
115#endif /* !defined(MBEDTLS_CTR_DRBG_ENTROPY_LEN) */
Paul Bakker088c5c52014-04-25 11:11:10 +0200116
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200117#if !defined(MBEDTLS_CTR_DRBG_RESEED_INTERVAL)
Rose Zadik2f8163d2018-01-25 21:55:14 +0000118#define MBEDTLS_CTR_DRBG_RESEED_INTERVAL 10000
119/**< The interval before reseed is performed by default. */
Paul Bakker088c5c52014-04-25 11:11:10 +0200120#endif
121
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200122#if !defined(MBEDTLS_CTR_DRBG_MAX_INPUT)
Rose Zadik2f8163d2018-01-25 21:55:14 +0000123#define MBEDTLS_CTR_DRBG_MAX_INPUT 256
124/**< The maximum number of additional input Bytes. */
Paul Bakker088c5c52014-04-25 11:11:10 +0200125#endif
126
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200127#if !defined(MBEDTLS_CTR_DRBG_MAX_REQUEST)
Rose Zadik2f8163d2018-01-25 21:55:14 +0000128#define MBEDTLS_CTR_DRBG_MAX_REQUEST 1024
129/**< The maximum number of requested Bytes per call. */
Paul Bakker088c5c52014-04-25 11:11:10 +0200130#endif
131
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200132#if !defined(MBEDTLS_CTR_DRBG_MAX_SEED_INPUT)
Rose Zadik2f8163d2018-01-25 21:55:14 +0000133#define MBEDTLS_CTR_DRBG_MAX_SEED_INPUT 384
Gilles Peskine08875d42019-09-24 14:40:40 +0200134/**< The maximum size of seed or reseed buffer in bytes. */
Paul Bakker088c5c52014-04-25 11:11:10 +0200135#endif
136
137/* \} name SECTION: Module settings */
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000138
Rose Zadik2f8163d2018-01-25 21:55:14 +0000139#define MBEDTLS_CTR_DRBG_PR_OFF 0
140/**< Prediction resistance is disabled. */
141#define MBEDTLS_CTR_DRBG_PR_ON 1
142/**< Prediction resistance is enabled. */
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000143
144#ifdef __cplusplus
145extern "C" {
146#endif
147
Gilles Peskine69971662019-10-23 19:39:36 +0200148#if MBEDTLS_CTR_DRBG_ENTROPY_LEN >= MBEDTLS_CTR_DRBG_KEYSIZE * 3 / 2
149/** The default length of the nonce read from the entropy source.
150 *
151 * This is \c 0 because a single read from the entropy source is sufficient
152 * to include a nonce.
153 * See the documentation of mbedtls_ctr_drbg_seed() for more information.
154 */
155#define MBEDTLS_CTR_DRBG_ENTROPY_NONCE_LEN 0
156#else
157/** The default length of the nonce read from the entropy source.
158 *
159 * This is half of the default entropy length because a single read from
160 * the entropy source does not provide enough material to form a nonce.
161 * See the documentation of mbedtls_ctr_drbg_seed() for more information.
162 */
163#define MBEDTLS_CTR_DRBG_ENTROPY_NONCE_LEN ( MBEDTLS_CTR_DRBG_ENTROPY_LEN + 1 ) / 2
164#endif
165
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000166/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000167 * \brief The CTR_DRBG context structure.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000168 */
Dawid Drozd428cc522018-07-24 10:02:47 +0200169typedef struct mbedtls_ctr_drbg_context
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000170{
Rose Zadik2f8163d2018-01-25 21:55:14 +0000171 unsigned char counter[16]; /*!< The counter (V). */
Gilles Peskinec0ace352019-10-22 17:06:31 +0200172 int reseed_counter; /*!< The reseed counter.
173 * This is the number of requests that have
174 * been made since the last (re)seeding,
Gilles Peskine9be50982019-10-22 18:42:27 +0200175 * minus one.
176 * Before the initial seeding, this field
177 * contains the amount of entropy in bytes
Jaeden Ameroa15c7132020-01-09 13:02:16 +0000178 * to use as a nonce for the initial seeding,
179 * or -1 if no nonce length has been explicitly
180 * set (see mbedtls_ctr_drbg_set_nonce_len()).
Gilles Peskine9be50982019-10-22 18:42:27 +0200181 */
Rose Zadik2f8163d2018-01-25 21:55:14 +0000182 int prediction_resistance; /*!< This determines whether prediction
183 resistance is enabled, that is
184 whether to systematically reseed before
185 each random generation. */
186 size_t entropy_len; /*!< The amount of entropy grabbed on each
Gilles Peskinec0ace352019-10-22 17:06:31 +0200187 seed or reseed operation, in bytes. */
188 int reseed_interval; /*!< The reseed interval.
189 * This is the maximum number of requests
190 * that can be made between reseedings. */
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000191
Rose Zadik2f8163d2018-01-25 21:55:14 +0000192 mbedtls_aes_context aes_ctx; /*!< The AES context. */
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000193
194 /*
195 * Callbacks (Entropy)
196 */
197 int (*f_entropy)(void *, unsigned char *, size_t);
Rose Zadik2f8163d2018-01-25 21:55:14 +0000198 /*!< The entropy callback function. */
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000199
Rose Zadik2f8163d2018-01-25 21:55:14 +0000200 void *p_entropy; /*!< The context for the entropy function. */
Manuel Pégourié-Gonnard0a4fb092015-05-07 12:50:31 +0100201
202#if defined(MBEDTLS_THREADING_C)
Gilles Peskineda290f92021-02-09 18:44:02 +0100203 /* Invariant: the mutex is initialized if and only if f_entropy != NULL.
204 * This means that the mutex is initialized during the initial seeding
205 * in mbedtls_ctr_drbg_seed() and freed in mbedtls_ctr_drbg_free().
206 *
207 * Note that this invariant may change without notice. Do not rely on it
208 * and do not access the mutex directly in application code.
209 */
Manuel Pégourié-Gonnard0a4fb092015-05-07 12:50:31 +0100210 mbedtls_threading_mutex_t mutex;
211#endif
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000212}
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200213mbedtls_ctr_drbg_context;
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000214
215/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000216 * \brief This function initializes the CTR_DRBG context,
217 * and prepares it for mbedtls_ctr_drbg_seed()
218 * or mbedtls_ctr_drbg_free().
Manuel Pégourié-Gonnard8d128ef2015-04-28 22:38:08 +0200219 *
Gavin Acquroff6aceb512020-03-01 17:06:11 -0800220 * \note The reseed interval is
221 * #MBEDTLS_CTR_DRBG_RESEED_INTERVAL by default.
222 * You can override it by calling
223 * mbedtls_ctr_drbg_set_reseed_interval().
224 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000225 * \param ctx The CTR_DRBG context to initialize.
Manuel Pégourié-Gonnard8d128ef2015-04-28 22:38:08 +0200226 */
227void mbedtls_ctr_drbg_init( mbedtls_ctr_drbg_context *ctx );
228
229/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000230 * \brief This function seeds and sets up the CTR_DRBG
231 * entropy source for future reseeds.
Paul Bakker9af723c2014-05-01 13:03:14 +0200232 *
Gilles Peskine223deea2019-09-24 14:48:53 +0200233 * A typical choice for the \p f_entropy and \p p_entropy parameters is
234 * to use the entropy module:
235 * - \p f_entropy is mbedtls_entropy_func();
236 * - \p p_entropy is an instance of ::mbedtls_entropy_context initialized
237 * with mbedtls_entropy_init() (which registers the platform's default
238 * entropy sources).
239 *
Gilles Peskine50ed86b2019-10-04 12:15:55 +0200240 * The entropy length is #MBEDTLS_CTR_DRBG_ENTROPY_LEN by default.
241 * You can override it by calling mbedtls_ctr_drbg_set_entropy_len().
Gilles Peskineec51dd12019-09-30 15:01:02 +0200242 *
Gilles Peskinee9a34542019-10-22 20:43:24 +0200243 * The entropy nonce length is:
244 * - \c 0 if the entropy length is at least 3/2 times the entropy length,
245 * which guarantees that the security strength is the maximum permitted
246 * by the key size and entropy length according to NIST SP 800-90A §10.2.1;
247 * - Half the entropy length otherwise.
248 * You can override it by calling mbedtls_ctr_drbg_set_nonce_len().
Gilles Peskine69971662019-10-23 19:39:36 +0200249 * With the default entropy length, the entropy nonce length is
250 * #MBEDTLS_CTR_DRBG_ENTROPY_NONCE_LEN.
251 *
Gilles Peskine9be50982019-10-22 18:42:27 +0200252 * You can provide a nonce and personalization string in addition to the
Gilles Peskine223deea2019-09-24 14:48:53 +0200253 * entropy source, to make this instantiation as unique as possible.
Gilles Peskine9be50982019-10-22 18:42:27 +0200254 * See SP 800-90A §8.6.7 for more details about nonces.
Gilles Peskine223deea2019-09-24 14:48:53 +0200255 *
Gilles Peskine9be50982019-10-22 18:42:27 +0200256 * The _seed_material_ value passed to the derivation function in
257 * the CTR_DRBG Instantiate Process described in NIST SP 800-90A §10.2.1.3.2
258 * is the concatenation of the following strings:
259 * - A string obtained by calling \p f_entropy function for the entropy
260 * length.
Gilles Peskinee9a34542019-10-22 20:43:24 +0200261 */
Gilles Peskine69971662019-10-23 19:39:36 +0200262#if MBEDTLS_CTR_DRBG_ENTROPY_NONCE_LEN == 0
Gilles Peskinee9a34542019-10-22 20:43:24 +0200263/**
264 * - If mbedtls_ctr_drbg_set_nonce_len() has been called, a string
265 * obtained by calling \p f_entropy function for the specified length.
266 */
267#else
268/**
269 * - A string obtained by calling \p f_entropy function for the entropy nonce
270 * length. If the entropy nonce length is \c 0, this function does not
271 * make a second call to \p f_entropy.
272 */
273#endif
274/**
Gilles Peskine9be50982019-10-22 18:42:27 +0200275 * - The \p custom string.
276 *
277 * \note To achieve the nominal security strength permitted
278 * by CTR_DRBG, the entropy length must be:
279 * - at least 16 bytes for a 128-bit strength
280 * (maximum achievable strength when using AES-128);
281 * - at least 32 bytes for a 256-bit strength
282 * (maximum achievable strength when using AES-256).
283 *
284 * In addition, if you do not pass a nonce in \p custom,
285 * the sum of the entropy length
Gilles Peskinee9a34542019-10-22 20:43:24 +0200286 * and the entropy nonce length must be:
Gilles Peskine9be50982019-10-22 18:42:27 +0200287 * - at least 24 bytes for a 128-bit strength
288 * (maximum achievable strength when using AES-128);
289 * - at least 48 bytes for a 256-bit strength
290 * (maximum achievable strength when using AES-256).
291 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000292 * \param ctx The CTR_DRBG context to seed.
Gilles Peskinebd326f92019-10-28 17:33:07 +0100293 * It must have been initialized with
294 * mbedtls_ctr_drbg_init().
295 * After a successful call to mbedtls_ctr_drbg_seed(),
296 * you may not call mbedtls_ctr_drbg_seed() again on
297 * the same context unless you call
298 * mbedtls_ctr_drbg_free() and mbedtls_ctr_drbg_init()
299 * again first.
Rose Zadik2f8163d2018-01-25 21:55:14 +0000300 * \param f_entropy The entropy callback, taking as arguments the
301 * \p p_entropy context, the buffer to fill, and the
Gilles Peskine08875d42019-09-24 14:40:40 +0200302 * length of the buffer.
Gilles Peskine50ed86b2019-10-04 12:15:55 +0200303 * \p f_entropy is always called with a buffer size
Gilles Peskine9be50982019-10-22 18:42:27 +0200304 * less than or equal to the entropy length.
Gilles Peskineec51dd12019-09-30 15:01:02 +0200305 * \param p_entropy The entropy context to pass to \p f_entropy.
Gilles Peskine217b8152019-10-01 18:39:45 +0200306 * \param custom The personalization string.
307 * This can be \c NULL, in which case the personalization
308 * string is empty regardless of the value of \p len.
309 * \param len The length of the personalization string.
Gilles Peskine944bc582019-09-24 14:48:30 +0200310 * This must be at most
311 * #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT
312 * - #MBEDTLS_CTR_DRBG_ENTROPY_LEN.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000313 *
Rose Zadikc9474eb2018-03-27 10:58:22 +0100314 * \return \c 0 on success.
315 * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000316 */
Manuel Pégourié-Gonnard8d128ef2015-04-28 22:38:08 +0200317int mbedtls_ctr_drbg_seed( mbedtls_ctr_drbg_context *ctx,
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000318 int (*f_entropy)(void *, unsigned char *, size_t),
319 void *p_entropy,
Paul Bakker1bc9efc2011-12-03 11:29:32 +0000320 const unsigned char *custom,
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000321 size_t len );
322
323/**
Gavin Acquroff6aceb512020-03-01 17:06:11 -0800324 * \brief This function resets CTR_DRBG context to the state immediately
325 * after initial call of mbedtls_ctr_drbg_init().
Paul Bakkerfff03662014-06-18 16:21:25 +0200326 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000327 * \param ctx The CTR_DRBG context to clear.
Paul Bakkerfff03662014-06-18 16:21:25 +0200328 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200329void mbedtls_ctr_drbg_free( mbedtls_ctr_drbg_context *ctx );
Paul Bakkerfff03662014-06-18 16:21:25 +0200330
331/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000332 * \brief This function turns prediction resistance on or off.
333 * The default value is off.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000334 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000335 * \note If enabled, entropy is gathered at the beginning of
Gilles Peskineec51dd12019-09-30 15:01:02 +0200336 * every call to mbedtls_ctr_drbg_random_with_add()
337 * or mbedtls_ctr_drbg_random().
Rose Zadik2f8163d2018-01-25 21:55:14 +0000338 * Only use this if your entropy source has sufficient
339 * throughput.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000340 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000341 * \param ctx The CTR_DRBG context.
342 * \param resistance #MBEDTLS_CTR_DRBG_PR_ON or #MBEDTLS_CTR_DRBG_PR_OFF.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000343 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200344void mbedtls_ctr_drbg_set_prediction_resistance( mbedtls_ctr_drbg_context *ctx,
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000345 int resistance );
346
347/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000348 * \brief This function sets the amount of entropy grabbed on each
Gilles Peskine50ed86b2019-10-04 12:15:55 +0200349 * seed or reseed.
Gilles Peskineec51dd12019-09-30 15:01:02 +0200350 *
351 * The default value is #MBEDTLS_CTR_DRBG_ENTROPY_LEN.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000352 *
Gilles Peskinedddda812019-10-03 14:22:04 +0200353 * \note The security strength of CTR_DRBG is bounded by the
354 * entropy length. Thus:
355 * - When using AES-256
356 * (\c MBEDTLS_CTR_DRBG_USE_128_BIT_KEY is disabled,
357 * which is the default),
358 * \p len must be at least 32 (in bytes)
359 * to achieve a 256-bit strength.
360 * - When using AES-128
361 * (\c MBEDTLS_CTR_DRBG_USE_128_BIT_KEY is enabled)
362 * \p len must be at least 16 (in bytes)
363 * to achieve a 128-bit strength.
Gilles Peskine223deea2019-09-24 14:48:53 +0200364 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000365 * \param ctx The CTR_DRBG context.
Gilles Peskine08875d42019-09-24 14:40:40 +0200366 * \param len The amount of entropy to grab, in bytes.
Gilles Peskine9be50982019-10-22 18:42:27 +0200367 * This must be at most #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT
368 * and at most the maximum length accepted by the
369 * entropy function that is set in the context.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000370 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200371void mbedtls_ctr_drbg_set_entropy_len( mbedtls_ctr_drbg_context *ctx,
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000372 size_t len );
373
374/**
Gilles Peskine9be50982019-10-22 18:42:27 +0200375 * \brief This function sets the amount of entropy grabbed
376 * as a nonce for the initial seeding.
377 *
378 * Call this function before calling mbedtls_ctr_drbg_seed() to read
379 * a nonce from the entropy source during the initial seeding.
380 *
381 * \param ctx The CTR_DRBG context.
382 * \param len The amount of entropy to grab for the nonce, in bytes.
383 * This must be at most #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT
384 * and at most the maximum length accepted by the
385 * entropy function that is set in the context.
386 *
387 * \return \c 0 on success.
388 * \return #MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG if \p len is
389 * more than #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT.
390 * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED
391 * if the initial seeding has already taken place.
392 */
393int mbedtls_ctr_drbg_set_nonce_len( mbedtls_ctr_drbg_context *ctx,
394 size_t len );
395
396/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000397 * \brief This function sets the reseed interval.
Gilles Peskineec51dd12019-09-30 15:01:02 +0200398 *
399 * The reseed interval is the number of calls to mbedtls_ctr_drbg_random()
400 * or mbedtls_ctr_drbg_random_with_add() after which the entropy function
401 * is called again.
402 *
403 * The default value is #MBEDTLS_CTR_DRBG_RESEED_INTERVAL.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000404 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000405 * \param ctx The CTR_DRBG context.
406 * \param interval The reseed interval.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000407 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200408void mbedtls_ctr_drbg_set_reseed_interval( mbedtls_ctr_drbg_context *ctx,
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000409 int interval );
410
411/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000412 * \brief This function reseeds the CTR_DRBG context, that is
413 * extracts data from the entropy source.
Paul Bakker9af723c2014-05-01 13:03:14 +0200414 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000415 * \param ctx The CTR_DRBG context.
Gilles Peskine10f16ac2019-10-01 18:30:02 +0200416 * \param additional Additional data to add to the state. Can be \c NULL.
Rose Zadik2f8163d2018-01-25 21:55:14 +0000417 * \param len The length of the additional data.
Gilles Peskine944bc582019-09-24 14:48:30 +0200418 * This must be less than
419 * #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT - \c entropy_len
420 * where \c entropy_len is the entropy length
421 * configured for the context.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000422 *
Rose Zadikc9474eb2018-03-27 10:58:22 +0100423 * \return \c 0 on success.
424 * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000425 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200426int mbedtls_ctr_drbg_reseed( mbedtls_ctr_drbg_context *ctx,
Paul Bakker1bc9efc2011-12-03 11:29:32 +0000427 const unsigned char *additional, size_t len );
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000428
429/**
Rose Zadikc9474eb2018-03-27 10:58:22 +0100430 * \brief This function updates the state of the CTR_DRBG context.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000431 *
Rose Zadikc9474eb2018-03-27 10:58:22 +0100432 * \param ctx The CTR_DRBG context.
Gilles Peskine08875d42019-09-24 14:40:40 +0200433 * \param additional The data to update the state with. This must not be
Gilles Peskine10f16ac2019-10-01 18:30:02 +0200434 * \c NULL unless \p add_len is \c 0.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500435 * \param add_len Length of \p additional in bytes. This must be at
436 * most #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT.
Rose Zadikc9474eb2018-03-27 10:58:22 +0100437 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500438 * \return \c 0 on success.
439 * \return #MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG if
440 * \p add_len is more than
441 * #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT.
442 * \return An error from the underlying AES cipher on failure.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000443 */
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500444int mbedtls_ctr_drbg_update_ret( mbedtls_ctr_drbg_context *ctx,
445 const unsigned char *additional,
446 size_t add_len );
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000447
448/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000449 * \brief This function updates a CTR_DRBG instance with additional
450 * data and uses it to generate random data.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000451 *
Gilles Peskine2d8f0692019-10-01 18:31:28 +0200452 * This function automatically reseeds if the reseed counter is exceeded
453 * or prediction resistance is enabled.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000454 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000455 * \param p_rng The CTR_DRBG context. This must be a pointer to a
456 * #mbedtls_ctr_drbg_context structure.
457 * \param output The buffer to fill.
Gilles Peskineec51dd12019-09-30 15:01:02 +0200458 * \param output_len The length of the buffer in bytes.
Gilles Peskine10f16ac2019-10-01 18:30:02 +0200459 * \param additional Additional data to update. Can be \c NULL, in which
Gilles Peskine08875d42019-09-24 14:40:40 +0200460 * case the additional data is empty regardless of
461 * the value of \p add_len.
462 * \param add_len The length of the additional data
Gilles Peskine10f16ac2019-10-01 18:30:02 +0200463 * if \p additional is not \c NULL.
Gilles Peskine944bc582019-09-24 14:48:30 +0200464 * This must be less than #MBEDTLS_CTR_DRBG_MAX_INPUT
465 * and less than
466 * #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT - \c entropy_len
467 * where \c entropy_len is the entropy length
468 * configured for the context.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000469 *
Rose Zadikc9474eb2018-03-27 10:58:22 +0100470 * \return \c 0 on success.
471 * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
Rose Zadik2f8163d2018-01-25 21:55:14 +0000472 * #MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000473 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200474int mbedtls_ctr_drbg_random_with_add( void *p_rng,
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000475 unsigned char *output, size_t output_len,
Paul Bakker1bc9efc2011-12-03 11:29:32 +0000476 const unsigned char *additional, size_t add_len );
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000477
478/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000479 * \brief This function uses CTR_DRBG to generate random data.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000480 *
Gilles Peskine2d8f0692019-10-01 18:31:28 +0200481 * This function automatically reseeds if the reseed counter is exceeded
482 * or prediction resistance is enabled.
483 *
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000484 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000485 * \param p_rng The CTR_DRBG context. This must be a pointer to a
486 * #mbedtls_ctr_drbg_context structure.
487 * \param output The buffer to fill.
Gilles Peskine944bc582019-09-24 14:48:30 +0200488 * \param output_len The length of the buffer in bytes.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000489 *
Rose Zadikc9474eb2018-03-27 10:58:22 +0100490 * \return \c 0 on success.
491 * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
Rose Zadik2f8163d2018-01-25 21:55:14 +0000492 * #MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000493 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200494int mbedtls_ctr_drbg_random( void *p_rng,
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000495 unsigned char *output, size_t output_len );
496
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500497
498#if ! defined(MBEDTLS_DEPRECATED_REMOVED)
499#if defined(MBEDTLS_DEPRECATED_WARNING)
500#define MBEDTLS_DEPRECATED __attribute__((deprecated))
501#else
502#define MBEDTLS_DEPRECATED
503#endif
504/**
505 * \brief This function updates the state of the CTR_DRBG context.
506 *
507 * \deprecated Superseded by mbedtls_ctr_drbg_update_ret()
508 * in 2.16.0.
509 *
510 * \note If \p add_len is greater than
511 * #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT, only the first
512 * #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT Bytes are used.
513 * The remaining Bytes are silently discarded.
514 *
515 * \param ctx The CTR_DRBG context.
516 * \param additional The data to update the state with.
517 * \param add_len Length of \p additional data.
518 */
519MBEDTLS_DEPRECATED void mbedtls_ctr_drbg_update(
520 mbedtls_ctr_drbg_context *ctx,
521 const unsigned char *additional,
522 size_t add_len );
523#undef MBEDTLS_DEPRECATED
524#endif /* !MBEDTLS_DEPRECATED_REMOVED */
525
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200526#if defined(MBEDTLS_FS_IO)
Paul Bakkerfc754a92011-12-05 13:23:51 +0000527/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000528 * \brief This function writes a seed file.
Paul Bakkerfc754a92011-12-05 13:23:51 +0000529 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000530 * \param ctx The CTR_DRBG context.
531 * \param path The name of the file.
Paul Bakkerfc754a92011-12-05 13:23:51 +0000532 *
Rose Zadikc9474eb2018-03-27 10:58:22 +0100533 * \return \c 0 on success.
Rose Zadikf25eb6e2018-04-16 14:51:52 +0100534 * \return #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error.
Gilles Peskineec51dd12019-09-30 15:01:02 +0200535 * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on reseed
Rose Zadik2f8163d2018-01-25 21:55:14 +0000536 * failure.
Paul Bakkerfc754a92011-12-05 13:23:51 +0000537 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200538int mbedtls_ctr_drbg_write_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path );
Paul Bakkerfc754a92011-12-05 13:23:51 +0000539
540/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000541 * \brief This function reads and updates a seed file. The seed
542 * is added to this instance.
Paul Bakkerfc754a92011-12-05 13:23:51 +0000543 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000544 * \param ctx The CTR_DRBG context.
545 * \param path The name of the file.
Paul Bakkerfc754a92011-12-05 13:23:51 +0000546 *
Rose Zadikc9474eb2018-03-27 10:58:22 +0100547 * \return \c 0 on success.
548 * \return #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error.
Gilles Peskineec51dd12019-09-30 15:01:02 +0200549 * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on
550 * reseed failure.
551 * \return #MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG if the existing
552 * seed file is too large.
Paul Bakkerfc754a92011-12-05 13:23:51 +0000553 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200554int mbedtls_ctr_drbg_update_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path );
555#endif /* MBEDTLS_FS_IO */
Paul Bakkerfc754a92011-12-05 13:23:51 +0000556
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500557#if defined(MBEDTLS_SELF_TEST)
558
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000559/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000560 * \brief The CTR_DRBG checkup routine.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000561 *
Rose Zadikc9474eb2018-03-27 10:58:22 +0100562 * \return \c 0 on success.
563 * \return \c 1 on failure.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000564 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200565int mbedtls_ctr_drbg_self_test( int verbose );
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000566
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500567#endif /* MBEDTLS_SELF_TEST */
568
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000569#ifdef __cplusplus
570}
571#endif
572
573#endif /* ctr_drbg.h */