blob: 4f8d1315c7bad46c285b2bbabdb3ca3623d394fd [file] [log] [blame]
Paul Bakker0e04d0e2011-11-27 14:46:59 +00001/**
2 * \file ctr_drbg.h
3 *
Rose Zadikc9474eb2018-03-27 10:58:22 +01004 * \brief This file contains CTR_DRBG definitions and functions.
5 *
Rose Zadikf25eb6e2018-04-16 14:51:52 +01006 * CTR_DRBG is a standardized way of building a PRNG from a block-cipher
7 * in counter mode operation, as defined in <em>NIST SP 800-90A:
8 * Recommendation for Random Number Generation Using Deterministic Random
9 * Bit Generators</em>.
Rose Zadik2f8163d2018-01-25 21:55:14 +000010 *
Nir Sonnenscheineb73f7a2018-07-30 17:46:49 +030011 * The Mbed TLS implementation of CTR_DRBG uses AES-256 (default) or AES-128
Gilles Peskine1eb7ba72019-09-24 14:48:53 +020012 * as the underlying block cipher, with a derivation function. The security
13 * strength is:
14 * - 256 bits under the default configuration of the library, with AES-256
15 * (`MBEDTLS_CTR_DRBG_USE_128_BIT_KEY` not set) and
16 * with #MBEDTLS_CTR_DRBG_ENTROPY_LEN set to 48 or more.
17 * - 256 bits if AES-256 is used, #MBEDTLS_CTR_DRBG_ENTROPY_LEN is set
Gilles Peskine3354f752019-09-25 20:22:24 +020018 * to 32 or more, and the DRBG is initialized with an explicit
Gilles Peskine4284bec2019-09-26 14:54:42 +020019 * nonce in the \c custom parameter to mbedtls_ctr_drbg_seed().
Gilles Peskine1eb7ba72019-09-24 14:48:53 +020020 * - 128 bits if AES-256 is used but #MBEDTLS_CTR_DRBG_ENTROPY_LEN is
21 * between 24 and 47 and the DRBG is not initialized with an explicit
22 * nonce (see mbedtls_ctr_drbg_seed()).
23 * - 128 bits if AES-128 is used (`MBEDTLS_CTR_DRBG_USE_128_BIT_KEY` set)
24 * and #MBEDTLS_CTR_DRBG_ENTROPY_LEN is set to 24 or more (which is
25 * always the case unless it is explicitly set to a different value
26 * in `config.h`).
Gilles Peskine8cec70a2019-10-02 18:23:38 +020027 *
28 * Note that the value of #MBEDTLS_CTR_DRBG_ENTROPY_LEN defaults to:
29 * - \c 48 if the module #MBEDTLS_SHA512_C is enabled and the symbol
30 * #MBEDTLS_ENTROPY_FORCE_SHA256 is not enabled at compile time.
31 * This is the default configuration of the library.
32 * - \c 32 if the module #MBEDTLS_SHA512_C is disabled at compile time.
33 * - \c 32 if #MBEDTLS_ENTROPY_FORCE_SHA256 is enabled at compile time.
Darryl Greena40a1012018-01-05 15:33:17 +000034 */
35/*
Gilles Peskine6b2c50c2019-09-24 14:40:40 +020036 * Copyright (C) 2006-2019, Arm Limited (or its affiliates), All Rights Reserved
Manuel Pégourié-Gonnard37ff1402015-09-04 14:21:07 +020037 * SPDX-License-Identifier: Apache-2.0
38 *
39 * Licensed under the Apache License, Version 2.0 (the "License"); you may
40 * not use this file except in compliance with the License.
41 * You may obtain a copy of the License at
42 *
43 * http://www.apache.org/licenses/LICENSE-2.0
44 *
45 * Unless required by applicable law or agreed to in writing, software
46 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
47 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
48 * See the License for the specific language governing permissions and
49 * limitations under the License.
Paul Bakker0e04d0e2011-11-27 14:46:59 +000050 *
Rose Zadik2f8163d2018-01-25 21:55:14 +000051 * This file is part of Mbed TLS (https://tls.mbed.org)
Paul Bakker0e04d0e2011-11-27 14:46:59 +000052 */
Rose Zadik2f8163d2018-01-25 21:55:14 +000053
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020054#ifndef MBEDTLS_CTR_DRBG_H
55#define MBEDTLS_CTR_DRBG_H
Paul Bakker0e04d0e2011-11-27 14:46:59 +000056
Ron Eldor8b0cf2e2018-02-14 16:02:41 +020057#if !defined(MBEDTLS_CONFIG_FILE)
58#include "config.h"
59#else
60#include MBEDTLS_CONFIG_FILE
61#endif
62
Paul Bakker0e04d0e2011-11-27 14:46:59 +000063#include "aes.h"
64
Manuel Pégourié-Gonnard0a4fb092015-05-07 12:50:31 +010065#if defined(MBEDTLS_THREADING_C)
Ron Eldor6fd941f2017-05-14 16:17:33 +030066#include "threading.h"
Manuel Pégourié-Gonnard0a4fb092015-05-07 12:50:31 +010067#endif
68
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020069#define MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED -0x0034 /**< The entropy source failed. */
Rose Zadik2f8163d2018-01-25 21:55:14 +000070#define MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG -0x0036 /**< The requested random buffer length is too big. */
71#define MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG -0x0038 /**< The input (entropy + additional data) is too large. */
72#define MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR -0x003A /**< Read or write error in file. */
Paul Bakker0e04d0e2011-11-27 14:46:59 +000073
Rose Zadik2f8163d2018-01-25 21:55:14 +000074#define MBEDTLS_CTR_DRBG_BLOCKSIZE 16 /**< The block size used by the cipher. */
Nir Sonnenscheince266e42018-08-29 10:11:46 +030075
Nir Sonnenschein43e4ff02018-09-03 14:15:46 +030076#if defined(MBEDTLS_CTR_DRBG_USE_128_BIT_KEY)
Gilles Peskine6b2c50c2019-09-24 14:40:40 +020077#define MBEDTLS_CTR_DRBG_KEYSIZE 16
78/**< The key size in bytes used by the cipher.
79 *
80 * Compile-time choice: 16 bytes (128 bits)
81 * because #MBEDTLS_CTR_DRBG_USE_128_BIT_KEY is set.
82 */
Nir Sonnenscheineb73f7a2018-07-30 17:46:49 +030083#else
Gilles Peskine6b2c50c2019-09-24 14:40:40 +020084#define MBEDTLS_CTR_DRBG_KEYSIZE 32
85/**< The key size in bytes used by the cipher.
86 *
87 * Compile-time choice: 32 bytes (256 bits)
88 * because `MBEDTLS_CTR_DRBG_USE_128_BIT_KEY` is not set.
89 */
Nir Sonnenscheina4588d42018-07-30 16:59:36 +030090#endif
Nir Sonnenschein43e4ff02018-09-03 14:15:46 +030091
Rose Zadik2f8163d2018-01-25 21:55:14 +000092#define MBEDTLS_CTR_DRBG_KEYBITS ( MBEDTLS_CTR_DRBG_KEYSIZE * 8 ) /**< The key size for the DRBG operation, in bits. */
93#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 +020094
Paul Bakker088c5c52014-04-25 11:11:10 +020095/**
96 * \name SECTION: Module settings
97 *
98 * The configuration options you can set for this module are in this section.
Rose Zadik2f8163d2018-01-25 21:55:14 +000099 * Either change them in config.h or define them using the compiler command
100 * line.
Paul Bakker088c5c52014-04-25 11:11:10 +0200101 * \{
102 */
103
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200104#if !defined(MBEDTLS_CTR_DRBG_ENTROPY_LEN)
105#if defined(MBEDTLS_SHA512_C) && !defined(MBEDTLS_ENTROPY_FORCE_SHA256)
Gilles Peskine6b2c50c2019-09-24 14:40:40 +0200106/** The amount of entropy used per seed by default.
107 *
108 * This is 48 bytes because the entropy module uses SHA-512
Gilles Peskine8cec70a2019-10-02 18:23:38 +0200109 * #MBEDTLS_ENTROPY_FORCE_SHA256 is not set).
Gilles Peskine6b2c50c2019-09-24 14:40:40 +0200110 *
111 * \note See mbedtls_ctr_drbg_set_entropy_len() regarding what values are
112 * acceptable.
113 */
Rose Zadik2f8163d2018-01-25 21:55:14 +0000114#define MBEDTLS_CTR_DRBG_ENTROPY_LEN 48
Paul Bakkerfb08fd22013-08-27 15:06:26 +0200115#else
Gilles Peskine6b2c50c2019-09-24 14:40:40 +0200116/** The amount of entropy used per seed by default.
117 *
118 * This is 32 bytes because the entropy module uses SHA-256
Gilles Peskine8cec70a2019-10-02 18:23:38 +0200119 * (the SHA512 module is disabled or #MBEDTLS_ENTROPY_FORCE_SHA256 is set).
Gilles Peskine6b2c50c2019-09-24 14:40:40 +0200120 *
121 * \note See mbedtls_ctr_drbg_set_entropy_len() regarding what values are
122 * acceptable.
Rose Zadik2f8163d2018-01-25 21:55:14 +0000123 */
Gilles Peskine6b2c50c2019-09-24 14:40:40 +0200124#define MBEDTLS_CTR_DRBG_ENTROPY_LEN 32
Paul Bakkerfb08fd22013-08-27 15:06:26 +0200125#endif
Paul Bakker088c5c52014-04-25 11:11:10 +0200126#endif
127
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200128#if !defined(MBEDTLS_CTR_DRBG_RESEED_INTERVAL)
Rose Zadik2f8163d2018-01-25 21:55:14 +0000129#define MBEDTLS_CTR_DRBG_RESEED_INTERVAL 10000
130/**< The interval before reseed is performed by default. */
Paul Bakker088c5c52014-04-25 11:11:10 +0200131#endif
132
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200133#if !defined(MBEDTLS_CTR_DRBG_MAX_INPUT)
Rose Zadik2f8163d2018-01-25 21:55:14 +0000134#define MBEDTLS_CTR_DRBG_MAX_INPUT 256
135/**< The maximum number of additional input Bytes. */
Paul Bakker088c5c52014-04-25 11:11:10 +0200136#endif
137
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200138#if !defined(MBEDTLS_CTR_DRBG_MAX_REQUEST)
Rose Zadik2f8163d2018-01-25 21:55:14 +0000139#define MBEDTLS_CTR_DRBG_MAX_REQUEST 1024
140/**< The maximum number of requested Bytes per call. */
Paul Bakker088c5c52014-04-25 11:11:10 +0200141#endif
142
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200143#if !defined(MBEDTLS_CTR_DRBG_MAX_SEED_INPUT)
Rose Zadik2f8163d2018-01-25 21:55:14 +0000144#define MBEDTLS_CTR_DRBG_MAX_SEED_INPUT 384
Gilles Peskine6b2c50c2019-09-24 14:40:40 +0200145/**< The maximum size of seed or reseed buffer in bytes. */
Paul Bakker088c5c52014-04-25 11:11:10 +0200146#endif
147
148/* \} name SECTION: Module settings */
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000149
Rose Zadik2f8163d2018-01-25 21:55:14 +0000150#define MBEDTLS_CTR_DRBG_PR_OFF 0
151/**< Prediction resistance is disabled. */
152#define MBEDTLS_CTR_DRBG_PR_ON 1
153/**< Prediction resistance is enabled. */
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000154
155#ifdef __cplusplus
156extern "C" {
157#endif
158
159/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000160 * \brief The CTR_DRBG context structure.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000161 */
Dawid Drozd428cc522018-07-24 10:02:47 +0200162typedef struct mbedtls_ctr_drbg_context
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000163{
Rose Zadik2f8163d2018-01-25 21:55:14 +0000164 unsigned char counter[16]; /*!< The counter (V). */
165 int reseed_counter; /*!< The reseed counter. */
166 int prediction_resistance; /*!< This determines whether prediction
167 resistance is enabled, that is
168 whether to systematically reseed before
169 each random generation. */
170 size_t entropy_len; /*!< The amount of entropy grabbed on each
171 seed or reseed operation. */
172 int reseed_interval; /*!< The reseed interval. */
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000173
Rose Zadik2f8163d2018-01-25 21:55:14 +0000174 mbedtls_aes_context aes_ctx; /*!< The AES context. */
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000175
176 /*
177 * Callbacks (Entropy)
178 */
179 int (*f_entropy)(void *, unsigned char *, size_t);
Rose Zadik2f8163d2018-01-25 21:55:14 +0000180 /*!< The entropy callback function. */
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000181
Rose Zadik2f8163d2018-01-25 21:55:14 +0000182 void *p_entropy; /*!< The context for the entropy function. */
Manuel Pégourié-Gonnard0a4fb092015-05-07 12:50:31 +0100183
184#if defined(MBEDTLS_THREADING_C)
185 mbedtls_threading_mutex_t mutex;
186#endif
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000187}
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200188mbedtls_ctr_drbg_context;
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000189
190/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000191 * \brief This function initializes the CTR_DRBG context,
192 * and prepares it for mbedtls_ctr_drbg_seed()
193 * or mbedtls_ctr_drbg_free().
Manuel Pégourié-Gonnard8d128ef2015-04-28 22:38:08 +0200194 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000195 * \param ctx The CTR_DRBG context to initialize.
Manuel Pégourié-Gonnard8d128ef2015-04-28 22:38:08 +0200196 */
197void mbedtls_ctr_drbg_init( mbedtls_ctr_drbg_context *ctx );
198
199/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000200 * \brief This function seeds and sets up the CTR_DRBG
201 * entropy source for future reseeds.
Paul Bakker9af723c2014-05-01 13:03:14 +0200202 *
Gilles Peskine1eb7ba72019-09-24 14:48:53 +0200203 * A typical choice for the \p f_entropy and \p p_entropy parameters is
204 * to use the entropy module:
205 * - \p f_entropy is mbedtls_entropy_func();
206 * - \p p_entropy is an instance of ::mbedtls_entropy_context initialized
207 * with mbedtls_entropy_init() (which registers the platform's default
208 * entropy sources).
209 *
Gilles Peskine0bf49eb2019-09-30 15:01:02 +0200210 * \p f_entropy is always called with a buffer size equal to the entropy
211 * length described in the documentation of mbedtls_ctr_drbg_set_entropy_len().
212 *
Gilles Peskine9fb45182019-10-01 18:39:45 +0200213 * You can provide a personalization string in addition to the
Gilles Peskine1eb7ba72019-09-24 14:48:53 +0200214 * entropy source, to make this instantiation as unique as possible.
215 *
216 * \note The _seed_material_ value passed to the derivation
217 * function in the CTR_DRBG Instantiate Process
218 * described in NIST SP 800-90A §10.2.1.3.2
219 * is the concatenation of the string obtained from
220 * calling \p f_entropy and the \p custom string.
221 * The origin of the nonce depends on the value of
222 * the entropy length relative to the security strength.
223 * See the documentation of
224 * mbedtls_ctr_drbg_set_entropy_len() for information
225 * about the entropy length.
226 * - If the entropy length is at least 1.5 times the
227 * security strength then the nonce is taken from the
228 * string obtained with \p f_entropy.
229 * - If the entropy length is less than the security
230 * strength, then the nonce is taken from \p custom.
231 * In this case, for compliance with SP 800-90A,
232 * you must pass a unique value of \p custom at
233 * each invocation. See SP 800-90A §8.6.7 for more
234 * details.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000235 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000236 * \param ctx The CTR_DRBG context to seed.
237 * \param f_entropy The entropy callback, taking as arguments the
238 * \p p_entropy context, the buffer to fill, and the
Gilles Peskine6b2c50c2019-09-24 14:40:40 +0200239 * length of the buffer.
Gilles Peskine0bf49eb2019-09-30 15:01:02 +0200240 * \param p_entropy The entropy context to pass to \p f_entropy.
Gilles Peskine9fb45182019-10-01 18:39:45 +0200241 * \param custom The personalization string.
242 * This can be \c NULL, in which case the personalization
243 * string is empty regardless of the value of \p len.
244 * \param len The length of the personalization string.
Gilles Peskine80b3f4b2019-09-24 14:48:30 +0200245 * This must be at most
246 * #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT / 2.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000247 *
Rose Zadikc9474eb2018-03-27 10:58:22 +0100248 * \return \c 0 on success.
249 * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000250 */
Manuel Pégourié-Gonnard8d128ef2015-04-28 22:38:08 +0200251int mbedtls_ctr_drbg_seed( mbedtls_ctr_drbg_context *ctx,
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000252 int (*f_entropy)(void *, unsigned char *, size_t),
253 void *p_entropy,
Paul Bakker1bc9efc2011-12-03 11:29:32 +0000254 const unsigned char *custom,
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000255 size_t len );
256
257/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000258 * \brief This function clears CTR_CRBG context data.
Paul Bakkerfff03662014-06-18 16:21:25 +0200259 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000260 * \param ctx The CTR_DRBG context to clear.
Paul Bakkerfff03662014-06-18 16:21:25 +0200261 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200262void mbedtls_ctr_drbg_free( mbedtls_ctr_drbg_context *ctx );
Paul Bakkerfff03662014-06-18 16:21:25 +0200263
264/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000265 * \brief This function turns prediction resistance on or off.
266 * The default value is off.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000267 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000268 * \note If enabled, entropy is gathered at the beginning of
Gilles Peskine0bf49eb2019-09-30 15:01:02 +0200269 * every call to mbedtls_ctr_drbg_random_with_add()
270 * or mbedtls_ctr_drbg_random().
Rose Zadik2f8163d2018-01-25 21:55:14 +0000271 * Only use this if your entropy source has sufficient
272 * throughput.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000273 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000274 * \param ctx The CTR_DRBG context.
275 * \param resistance #MBEDTLS_CTR_DRBG_PR_ON or #MBEDTLS_CTR_DRBG_PR_OFF.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000276 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200277void mbedtls_ctr_drbg_set_prediction_resistance( mbedtls_ctr_drbg_context *ctx,
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000278 int resistance );
279
280/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000281 * \brief This function sets the amount of entropy grabbed on each
Gilles Peskine0bf49eb2019-09-30 15:01:02 +0200282 * seed or reseed.
283 *
284 * The default value is #MBEDTLS_CTR_DRBG_ENTROPY_LEN.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000285 *
Gilles Peskine1eb7ba72019-09-24 14:48:53 +0200286 * \note For compliance with NIST SP 800-90A, the entropy length
Gilles Peskinec85dcb32019-09-25 20:22:40 +0200287 * (\p len bytes = \p len * 8 bits)
288 * must be at least the security strength.
289 * Furthermore, if the entropy input is used to provide
290 * the nonce, the entropy length must be 1.5 times
291 * the security strength.
292 * Per NIST SP 800-57A table 2, the achievable security
293 * strength is 128 bits if using AES-128 and
294 * 256 bits if using AES-256.
295 * Therefore, to provide full security,
296 * the entropy input must be at least:
297 * - 24 bytes if using AES-128 and the \p custom
298 * argument to mbedtls_ctr_drbg_seed() may repeat
299 * (for example because it is empty, or more generally
300 * constant);
301 * - 48 bytes if using AES-256 and the \p custom
302 * argument to mbedtls_ctr_drbg_seed() may repeat
303 * (for example because it is empty, or more generally
304 * constant);
305 * - 16 bytes if using AES-128 and the \p custom
306 * argument to mbedtls_ctr_drbg_seed() includes
307 * a nonce;
308 * - 32 bytes if using AES-256 and the \p custom
309 * argument to mbedtls_ctr_drbg_seed() includes
310 * a nonce.
Gilles Peskine1eb7ba72019-09-24 14:48:53 +0200311 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000312 * \param ctx The CTR_DRBG context.
Gilles Peskine6b2c50c2019-09-24 14:40:40 +0200313 * \param len The amount of entropy to grab, in bytes.
Gilles Peskine80b3f4b2019-09-24 14:48:30 +0200314 * This must be at most #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000315 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200316void mbedtls_ctr_drbg_set_entropy_len( mbedtls_ctr_drbg_context *ctx,
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000317 size_t len );
318
319/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000320 * \brief This function sets the reseed interval.
Gilles Peskine0bf49eb2019-09-30 15:01:02 +0200321 *
322 * The reseed interval is the number of calls to mbedtls_ctr_drbg_random()
323 * or mbedtls_ctr_drbg_random_with_add() after which the entropy function
324 * is called again.
325 *
326 * The default value is #MBEDTLS_CTR_DRBG_RESEED_INTERVAL.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000327 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000328 * \param ctx The CTR_DRBG context.
329 * \param interval The reseed interval.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000330 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200331void mbedtls_ctr_drbg_set_reseed_interval( mbedtls_ctr_drbg_context *ctx,
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000332 int interval );
333
334/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000335 * \brief This function reseeds the CTR_DRBG context, that is
336 * extracts data from the entropy source.
Paul Bakker9af723c2014-05-01 13:03:14 +0200337 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000338 * \param ctx The CTR_DRBG context.
Gilles Peskine759c91d2019-10-01 18:30:02 +0200339 * \param additional Additional data to add to the state. Can be \c NULL.
Rose Zadik2f8163d2018-01-25 21:55:14 +0000340 * \param len The length of the additional data.
Gilles Peskine80b3f4b2019-09-24 14:48:30 +0200341 * This must be less than
342 * #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT - \c entropy_len
343 * where \c entropy_len is the entropy length
344 * configured for the context.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000345 *
Rose Zadikc9474eb2018-03-27 10:58:22 +0100346 * \return \c 0 on success.
347 * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000348 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200349int mbedtls_ctr_drbg_reseed( mbedtls_ctr_drbg_context *ctx,
Paul Bakker1bc9efc2011-12-03 11:29:32 +0000350 const unsigned char *additional, size_t len );
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000351
352/**
Rose Zadikc9474eb2018-03-27 10:58:22 +0100353 * \brief This function updates the state of the CTR_DRBG context.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000354 *
Rose Zadikc9474eb2018-03-27 10:58:22 +0100355 * \param ctx The CTR_DRBG context.
Gilles Peskine6b2c50c2019-09-24 14:40:40 +0200356 * \param additional The data to update the state with. This must not be
Gilles Peskine759c91d2019-10-01 18:30:02 +0200357 * \c NULL unless \p add_len is \c 0.
Gilles Peskinec4a80172018-09-12 19:15:53 +0200358 * \param add_len Length of \p additional in bytes. This must be at
359 * most #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT.
Rose Zadikc9474eb2018-03-27 10:58:22 +0100360 *
Gilles Peskined9199932018-09-11 16:41:54 +0200361 * \return \c 0 on success.
Gilles Peskinec4a80172018-09-12 19:15:53 +0200362 * \return #MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG if
363 * \p add_len is more than
364 * #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT.
Gilles Peskined9199932018-09-11 16:41:54 +0200365 * \return An error from the underlying AES cipher on failure.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000366 */
Gilles Peskined9199932018-09-11 16:41:54 +0200367int mbedtls_ctr_drbg_update_ret( mbedtls_ctr_drbg_context *ctx,
368 const unsigned char *additional,
369 size_t add_len );
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000370
371/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000372 * \brief This function updates a CTR_DRBG instance with additional
373 * data and uses it to generate random data.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000374 *
Gilles Peskine3f9c9732019-10-01 18:31:28 +0200375 * This function automatically reseeds if the reseed counter is exceeded
376 * or prediction resistance is enabled.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000377 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000378 * \param p_rng The CTR_DRBG context. This must be a pointer to a
379 * #mbedtls_ctr_drbg_context structure.
380 * \param output The buffer to fill.
Gilles Peskine0bf49eb2019-09-30 15:01:02 +0200381 * \param output_len The length of the buffer in bytes.
Gilles Peskine759c91d2019-10-01 18:30:02 +0200382 * \param additional Additional data to update. Can be \c NULL, in which
Gilles Peskine6b2c50c2019-09-24 14:40:40 +0200383 * case the additional data is empty regardless of
384 * the value of \p add_len.
385 * \param add_len The length of the additional data
Gilles Peskine759c91d2019-10-01 18:30:02 +0200386 * if \p additional is not \c NULL.
Gilles Peskine80b3f4b2019-09-24 14:48:30 +0200387 * This must be less than #MBEDTLS_CTR_DRBG_MAX_INPUT
388 * and less than
389 * #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT - \c entropy_len
390 * where \c entropy_len is the entropy length
391 * configured for the context.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000392 *
Rose Zadikc9474eb2018-03-27 10:58:22 +0100393 * \return \c 0 on success.
394 * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
Rose Zadik2f8163d2018-01-25 21:55:14 +0000395 * #MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000396 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200397int mbedtls_ctr_drbg_random_with_add( void *p_rng,
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000398 unsigned char *output, size_t output_len,
Paul Bakker1bc9efc2011-12-03 11:29:32 +0000399 const unsigned char *additional, size_t add_len );
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000400
401/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000402 * \brief This function uses CTR_DRBG to generate random data.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000403 *
Gilles Peskine3f9c9732019-10-01 18:31:28 +0200404 * This function automatically reseeds if the reseed counter is exceeded
405 * or prediction resistance is enabled.
406 *
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000407 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000408 * \param p_rng The CTR_DRBG context. This must be a pointer to a
409 * #mbedtls_ctr_drbg_context structure.
410 * \param output The buffer to fill.
411 * \param output_len The length of the buffer.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000412 *
Rose Zadikc9474eb2018-03-27 10:58:22 +0100413 * \return \c 0 on success.
414 * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
Rose Zadik2f8163d2018-01-25 21:55:14 +0000415 * #MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000416 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200417int mbedtls_ctr_drbg_random( void *p_rng,
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000418 unsigned char *output, size_t output_len );
419
Gilles Peskined9199932018-09-11 16:41:54 +0200420
421#if ! defined(MBEDTLS_DEPRECATED_REMOVED)
422#if defined(MBEDTLS_DEPRECATED_WARNING)
423#define MBEDTLS_DEPRECATED __attribute__((deprecated))
424#else
425#define MBEDTLS_DEPRECATED
426#endif
427/**
428 * \brief This function updates the state of the CTR_DRBG context.
429 *
430 * \deprecated Superseded by mbedtls_ctr_drbg_update_ret()
431 * in 2.16.0.
432 *
433 * \note If \p add_len is greater than
434 * #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT, only the first
435 * #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT Bytes are used.
436 * The remaining Bytes are silently discarded.
437 *
438 * \param ctx The CTR_DRBG context.
439 * \param additional The data to update the state with.
440 * \param add_len Length of \p additional data.
441 */
442MBEDTLS_DEPRECATED void mbedtls_ctr_drbg_update(
443 mbedtls_ctr_drbg_context *ctx,
444 const unsigned char *additional,
445 size_t add_len );
446#undef MBEDTLS_DEPRECATED
447#endif /* !MBEDTLS_DEPRECATED_REMOVED */
448
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200449#if defined(MBEDTLS_FS_IO)
Paul Bakkerfc754a92011-12-05 13:23:51 +0000450/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000451 * \brief This function writes a seed file.
Paul Bakkerfc754a92011-12-05 13:23:51 +0000452 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000453 * \param ctx The CTR_DRBG context.
454 * \param path The name of the file.
Paul Bakkerfc754a92011-12-05 13:23:51 +0000455 *
Rose Zadikc9474eb2018-03-27 10:58:22 +0100456 * \return \c 0 on success.
Rose Zadikf25eb6e2018-04-16 14:51:52 +0100457 * \return #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error.
Gilles Peskine0bf49eb2019-09-30 15:01:02 +0200458 * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on reseed
Rose Zadik2f8163d2018-01-25 21:55:14 +0000459 * failure.
Paul Bakkerfc754a92011-12-05 13:23:51 +0000460 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200461int mbedtls_ctr_drbg_write_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path );
Paul Bakkerfc754a92011-12-05 13:23:51 +0000462
463/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000464 * \brief This function reads and updates a seed file. The seed
465 * is added to this instance.
Paul Bakkerfc754a92011-12-05 13:23:51 +0000466 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000467 * \param ctx The CTR_DRBG context.
468 * \param path The name of the file.
Paul Bakkerfc754a92011-12-05 13:23:51 +0000469 *
Rose Zadikc9474eb2018-03-27 10:58:22 +0100470 * \return \c 0 on success.
471 * \return #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error.
Gilles Peskine0bf49eb2019-09-30 15:01:02 +0200472 * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on
473 * reseed failure.
474 * \return #MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG if the existing
475 * seed file is too large.
Paul Bakkerfc754a92011-12-05 13:23:51 +0000476 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200477int mbedtls_ctr_drbg_update_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path );
478#endif /* MBEDTLS_FS_IO */
Paul Bakkerfc754a92011-12-05 13:23:51 +0000479
Ron Eldorfa8f6352017-06-20 15:48:46 +0300480#if defined(MBEDTLS_SELF_TEST)
481
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000482/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000483 * \brief The CTR_DRBG checkup routine.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000484 *
Rose Zadikc9474eb2018-03-27 10:58:22 +0100485 * \return \c 0 on success.
486 * \return \c 1 on failure.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000487 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200488int mbedtls_ctr_drbg_self_test( int verbose );
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000489
Ron Eldorfa8f6352017-06-20 15:48:46 +0300490#endif /* MBEDTLS_SELF_TEST */
491
Paul Bakker534f82c2013-06-25 16:47:55 +0200492/* Internal functions (do not call directly) */
Manuel Pégourié-Gonnard8d128ef2015-04-28 22:38:08 +0200493int mbedtls_ctr_drbg_seed_entropy_len( mbedtls_ctr_drbg_context *,
Paul Bakkerb9e4e2c2014-05-01 14:18:25 +0200494 int (*)(void *, unsigned char *, size_t), void *,
495 const unsigned char *, size_t, size_t );
Paul Bakker534f82c2013-06-25 16:47:55 +0200496
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000497#ifdef __cplusplus
498}
499#endif
500
501#endif /* ctr_drbg.h */