blob: 390059c3b90ff69e6255efe42a4fa7a1294235eb [file] [log] [blame]
Paul Bakker0e04d0e2011-11-27 14:46:59 +00001/**
2 * \file ctr_drbg.h
3 *
Gilles Peskine25e19452019-10-02 18:54:20 +02004 * \brief The CTR_DRBG pseudorandom generator.
5 *
6 * 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 *
Gilles Peskineeb99c102019-10-02 18:56:17 +020011 * The Mbed TLS implementation of CTR_DRBG uses AES-256
Gilles Peskinedff36822019-10-03 15:10:21 +020012 * as the underlying block cipher, with a derivation function.
13 * The initial seeding grabs #MBEDTLS_CTR_DRBG_ENTROPY_LEN bytes of entropy.
14 * See the documentation of mbedtls_ctr_drbg_seed() for more details.
15 *
16 * Based on NIST SP 800-90A §10.2.1 table 3 and NIST SP 800-57 part 1 table 2,
17 * here are the security strengths achieved in typical configuration:
Gilles Peskineeb99c102019-10-02 18:56:17 +020018 * - 256 bits under the default configuration of the library,
19 * with #MBEDTLS_CTR_DRBG_ENTROPY_LEN set to 48 or more.
20 * - 256 bits if #MBEDTLS_CTR_DRBG_ENTROPY_LEN is set
21 * to 32 or more and the DRBG is initialized with an explicit
22 * nonce in the \c custom parameter to mbedtls_ctr_drbg_seed().
23 * - 128 bits if #MBEDTLS_CTR_DRBG_ENTROPY_LEN is
24 * between 24 and 47 and the DRBG is not initialized with an explicit
25 * nonce (see mbedtls_ctr_drbg_seed()).
26 *
27 * Note that the value of #MBEDTLS_CTR_DRBG_ENTROPY_LEN defaults to:
Gilles Peskinef0b3dcb2019-10-03 14:28:17 +020028 * - \c 48 if the module \c MBEDTLS_SHA512_C is enabled and the symbol
29 * \c MBEDTLS_ENTROPY_FORCE_SHA256 is not enabled at compile time.
Gilles Peskineeb99c102019-10-02 18:56:17 +020030 * This is the default configuration of the library.
Gilles Peskinef0b3dcb2019-10-03 14:28:17 +020031 * - \c 32 if the module \c MBEDTLS_SHA512_C is disabled at compile time.
32 * - \c 32 if \c MBEDTLS_ENTROPY_FORCE_SHA256 is enabled at compile time.
Darryl Greena40a1012018-01-05 15:33:17 +000033 */
34/*
Gilles Peskine25e19452019-10-02 18:54:20 +020035 * Copyright (C) 2006-2019, Arm Limited (or its affiliates), All Rights Reserved
Bence Szépkúti4e9f7122020-06-05 13:02:18 +020036 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
37 *
38 * This file is provided under the Apache License 2.0, or the
39 * GNU General Public License v2.0 or later.
40 *
41 * **********
42 * Apache License 2.0:
Manuel Pégourié-Gonnard37ff1402015-09-04 14:21:07 +020043 *
44 * Licensed under the Apache License, Version 2.0 (the "License"); you may
45 * not use this file except in compliance with the License.
46 * You may obtain a copy of the License at
47 *
48 * http://www.apache.org/licenses/LICENSE-2.0
49 *
50 * Unless required by applicable law or agreed to in writing, software
51 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
52 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
53 * See the License for the specific language governing permissions and
54 * limitations under the License.
Paul Bakker0e04d0e2011-11-27 14:46:59 +000055 *
Bence Szépkúti4e9f7122020-06-05 13:02:18 +020056 * **********
57 *
58 * **********
59 * GNU General Public License v2.0 or later:
60 *
61 * This program is free software; you can redistribute it and/or modify
62 * it under the terms of the GNU General Public License as published by
63 * the Free Software Foundation; either version 2 of the License, or
64 * (at your option) any later version.
65 *
66 * This program is distributed in the hope that it will be useful,
67 * but WITHOUT ANY WARRANTY; without even the implied warranty of
68 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
69 * GNU General Public License for more details.
70 *
71 * You should have received a copy of the GNU General Public License along
72 * with this program; if not, write to the Free Software Foundation, Inc.,
73 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
74 *
75 * **********
76 *
Rose Zadik2f8163d2018-01-25 21:55:14 +000077 * This file is part of Mbed TLS (https://tls.mbed.org)
Paul Bakker0e04d0e2011-11-27 14:46:59 +000078 */
Rose Zadik2f8163d2018-01-25 21:55:14 +000079
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020080#ifndef MBEDTLS_CTR_DRBG_H
81#define MBEDTLS_CTR_DRBG_H
Paul Bakker0e04d0e2011-11-27 14:46:59 +000082
Ron Eldor0559c662018-02-14 16:02:41 +020083#if !defined(MBEDTLS_CONFIG_FILE)
84#include "config.h"
85#else
86#include MBEDTLS_CONFIG_FILE
87#endif
88
Paul Bakker0e04d0e2011-11-27 14:46:59 +000089#include "aes.h"
90
Manuel Pégourié-Gonnard0a4fb092015-05-07 12:50:31 +010091#if defined(MBEDTLS_THREADING_C)
Ron Eldordf9b93e2017-05-14 16:17:33 +030092#include "threading.h"
Manuel Pégourié-Gonnard0a4fb092015-05-07 12:50:31 +010093#endif
94
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020095#define MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED -0x0034 /**< The entropy source failed. */
Rose Zadik2f8163d2018-01-25 21:55:14 +000096#define MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG -0x0036 /**< The requested random buffer length is too big. */
97#define MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG -0x0038 /**< The input (entropy + additional data) is too large. */
98#define MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR -0x003A /**< Read or write error in file. */
Paul Bakker0e04d0e2011-11-27 14:46:59 +000099
Rose Zadik2f8163d2018-01-25 21:55:14 +0000100#define MBEDTLS_CTR_DRBG_BLOCKSIZE 16 /**< The block size used by the cipher. */
101#define MBEDTLS_CTR_DRBG_KEYSIZE 32 /**< The key size used by the cipher. */
102#define MBEDTLS_CTR_DRBG_KEYBITS ( MBEDTLS_CTR_DRBG_KEYSIZE * 8 ) /**< The key size for the DRBG operation, in bits. */
103#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 +0200104
Paul Bakker088c5c52014-04-25 11:11:10 +0200105/**
106 * \name SECTION: Module settings
107 *
108 * The configuration options you can set for this module are in this section.
Rose Zadik2f8163d2018-01-25 21:55:14 +0000109 * Either change them in config.h or define them using the compiler command
110 * line.
Paul Bakker088c5c52014-04-25 11:11:10 +0200111 * \{
112 */
113
Gilles Peskinedff36822019-10-03 15:10:21 +0200114/** \def MBEDTLS_CTR_DRBG_ENTROPY_LEN
115 *
116 * \brief The amount of entropy used per seed by default, in bytes.
117 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200118#if !defined(MBEDTLS_CTR_DRBG_ENTROPY_LEN)
119#if defined(MBEDTLS_SHA512_C) && !defined(MBEDTLS_ENTROPY_FORCE_SHA256)
Gilles Peskinedff36822019-10-03 15:10:21 +0200120/** This is 48 bytes because the entropy module uses SHA-512
Gilles Peskinef0b3dcb2019-10-03 14:28:17 +0200121 * (\c MBEDTLS_ENTROPY_FORCE_SHA256 is not set).
Gilles Peskineeb99c102019-10-02 18:56:17 +0200122 */
Rose Zadik2f8163d2018-01-25 21:55:14 +0000123#define MBEDTLS_CTR_DRBG_ENTROPY_LEN 48
Gilles Peskinedff36822019-10-03 15:10:21 +0200124
125#else /* defined(MBEDTLS_SHA512_C) && !defined(MBEDTLS_ENTROPY_FORCE_SHA256) */
126
127/** This is 32 bytes because the entropy module uses SHA-256
Gilles Peskinef0b3dcb2019-10-03 14:28:17 +0200128 * (the SHA512 module is disabled or
129 * \c MBEDTLS_ENTROPY_FORCE_SHA256 is enabled).
Gilles Peskineeb99c102019-10-02 18:56:17 +0200130 *
Gilles Peskinedff36822019-10-03 15:10:21 +0200131 * \warning To achieve a 256-bit security strength, you must pass a nonce
132 * to mbedtls_ctr_drbg_seed().
Rose Zadik2f8163d2018-01-25 21:55:14 +0000133 */
Gilles Peskineeb99c102019-10-02 18:56:17 +0200134#define MBEDTLS_CTR_DRBG_ENTROPY_LEN 32
Gilles Peskinedff36822019-10-03 15:10:21 +0200135#endif /* defined(MBEDTLS_SHA512_C) && !defined(MBEDTLS_ENTROPY_FORCE_SHA256) */
136#endif /* !defined(MBEDTLS_CTR_DRBG_ENTROPY_LEN) */
Paul Bakker088c5c52014-04-25 11:11:10 +0200137
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200138#if !defined(MBEDTLS_CTR_DRBG_RESEED_INTERVAL)
Rose Zadik2f8163d2018-01-25 21:55:14 +0000139#define MBEDTLS_CTR_DRBG_RESEED_INTERVAL 10000
140/**< The interval before reseed is performed by default. */
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_INPUT)
Rose Zadik2f8163d2018-01-25 21:55:14 +0000144#define MBEDTLS_CTR_DRBG_MAX_INPUT 256
145/**< The maximum number of additional input Bytes. */
Paul Bakker088c5c52014-04-25 11:11:10 +0200146#endif
147
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200148#if !defined(MBEDTLS_CTR_DRBG_MAX_REQUEST)
Rose Zadik2f8163d2018-01-25 21:55:14 +0000149#define MBEDTLS_CTR_DRBG_MAX_REQUEST 1024
150/**< The maximum number of requested Bytes per call. */
Paul Bakker088c5c52014-04-25 11:11:10 +0200151#endif
152
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200153#if !defined(MBEDTLS_CTR_DRBG_MAX_SEED_INPUT)
Rose Zadik2f8163d2018-01-25 21:55:14 +0000154#define MBEDTLS_CTR_DRBG_MAX_SEED_INPUT 384
Gilles Peskine25e19452019-10-02 18:54:20 +0200155/**< The maximum size of seed or reseed buffer in bytes. */
Paul Bakker088c5c52014-04-25 11:11:10 +0200156#endif
157
158/* \} name SECTION: Module settings */
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000159
Rose Zadik2f8163d2018-01-25 21:55:14 +0000160#define MBEDTLS_CTR_DRBG_PR_OFF 0
161/**< Prediction resistance is disabled. */
162#define MBEDTLS_CTR_DRBG_PR_ON 1
163/**< Prediction resistance is enabled. */
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000164
165#ifdef __cplusplus
166extern "C" {
167#endif
168
169/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000170 * \brief The CTR_DRBG context structure.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000171 */
172typedef struct
173{
Rose Zadik2f8163d2018-01-25 21:55:14 +0000174 unsigned char counter[16]; /*!< The counter (V). */
175 int reseed_counter; /*!< The reseed counter. */
176 int prediction_resistance; /*!< This determines whether prediction
177 resistance is enabled, that is
178 whether to systematically reseed before
179 each random generation. */
180 size_t entropy_len; /*!< The amount of entropy grabbed on each
181 seed or reseed operation. */
182 int reseed_interval; /*!< The reseed interval. */
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000183
Rose Zadik2f8163d2018-01-25 21:55:14 +0000184 mbedtls_aes_context aes_ctx; /*!< The AES context. */
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000185
186 /*
187 * Callbacks (Entropy)
188 */
189 int (*f_entropy)(void *, unsigned char *, size_t);
Rose Zadik2f8163d2018-01-25 21:55:14 +0000190 /*!< The entropy callback function. */
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000191
Rose Zadik2f8163d2018-01-25 21:55:14 +0000192 void *p_entropy; /*!< The context for the entropy function. */
Manuel Pégourié-Gonnard0a4fb092015-05-07 12:50:31 +0100193
194#if defined(MBEDTLS_THREADING_C)
195 mbedtls_threading_mutex_t mutex;
196#endif
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000197}
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200198mbedtls_ctr_drbg_context;
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000199
200/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000201 * \brief This function initializes the CTR_DRBG context,
202 * and prepares it for mbedtls_ctr_drbg_seed()
203 * or mbedtls_ctr_drbg_free().
Manuel Pégourié-Gonnard8d128ef2015-04-28 22:38:08 +0200204 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000205 * \param ctx The CTR_DRBG context to initialize.
Manuel Pégourié-Gonnard8d128ef2015-04-28 22:38:08 +0200206 */
207void mbedtls_ctr_drbg_init( mbedtls_ctr_drbg_context *ctx );
208
209/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000210 * \brief This function seeds and sets up the CTR_DRBG
211 * entropy source for future reseeds.
Paul Bakker9af723c2014-05-01 13:03:14 +0200212 *
Gilles Peskineb9cfe582019-10-02 19:00:57 +0200213 * A typical choice for the \p f_entropy and \p p_entropy parameters is
214 * to use the entropy module:
215 * - \p f_entropy is mbedtls_entropy_func();
216 * - \p p_entropy is an instance of ::mbedtls_entropy_context initialized
217 * with mbedtls_entropy_init() (which registers the platform's default
218 * entropy sources).
219 *
Gilles Peskineb729e1b2019-10-04 12:15:55 +0200220 * The entropy length is #MBEDTLS_CTR_DRBG_ENTROPY_LEN by default.
221 * You can override it by calling mbedtls_ctr_drbg_set_entropy_len().
Gilles Peskineb9cfe582019-10-02 19:00:57 +0200222 *
Gilles Peskine25e19452019-10-02 18:54:20 +0200223 * You can provide a personalization string in addition to the
224 * entropy source, to make this instantiation as unique as possible.
225 *
Gilles Peskineeb99c102019-10-02 18:56:17 +0200226 * \note The _seed_material_ value passed to the derivation
227 * function in the CTR_DRBG Instantiate Process
228 * described in NIST SP 800-90A §10.2.1.3.2
229 * is the concatenation of the string obtained from
230 * calling \p f_entropy and the \p custom string.
231 * The origin of the nonce depends on the value of
232 * the entropy length relative to the security strength.
Gilles Peskineeb99c102019-10-02 18:56:17 +0200233 * - If the entropy length is at least 1.5 times the
234 * security strength then the nonce is taken from the
235 * string obtained with \p f_entropy.
236 * - If the entropy length is less than the security
237 * strength, then the nonce is taken from \p custom.
238 * In this case, for compliance with SP 800-90A,
239 * you must pass a unique value of \p custom at
240 * each invocation. See SP 800-90A §8.6.7 for more
241 * details.
Gilles Peskinedff36822019-10-03 15:10:21 +0200242 */
243#if MBEDTLS_CTR_DRBG_ENTROPY_LEN < MBEDTLS_CTR_DRBG_KEYSIZE * 3 / 2
244/** \warning When #MBEDTLS_CTR_DRBG_ENTROPY_LEN is less than
245 * 48, to achieve a 256-bit security strength,
246 * you must pass a value of \p custom that is a nonce:
247 * this value must never be repeated in subsequent
248 * runs of the same application or on a different
249 * device.
250 */
251#endif
252/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000253 * \param ctx The CTR_DRBG context to seed.
Gilles Peskine4c575c02019-10-28 17:33:07 +0100254 * It must have been initialized with
255 * mbedtls_ctr_drbg_init().
256 * After a successful call to mbedtls_ctr_drbg_seed(),
257 * you may not call mbedtls_ctr_drbg_seed() again on
258 * the same context unless you call
259 * mbedtls_ctr_drbg_free() and mbedtls_ctr_drbg_init()
260 * again first.
Rose Zadik2f8163d2018-01-25 21:55:14 +0000261 * \param f_entropy The entropy callback, taking as arguments the
262 * \p p_entropy context, the buffer to fill, and the
Gilles Peskine25e19452019-10-02 18:54:20 +0200263 * length of the buffer.
Gilles Peskineb729e1b2019-10-04 12:15:55 +0200264 * \p f_entropy is always called with a buffer size
265 * equal to the entropy length.
Gilles Peskine25e19452019-10-02 18:54:20 +0200266 * \param p_entropy The entropy context to pass to \p f_entropy.
267 * \param custom The personalization string.
268 * This can be \c NULL, in which case the personalization
269 * string is empty regardless of the value of \p len.
270 * \param len The length of the personalization string.
271 * This must be at most
Gilles Peskine2abefef2019-10-03 15:13:08 +0200272 * #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT
273 * - #MBEDTLS_CTR_DRBG_ENTROPY_LEN.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000274 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000275 * \return \c 0 on success, or
276 * #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000277 */
Manuel Pégourié-Gonnard8d128ef2015-04-28 22:38:08 +0200278int mbedtls_ctr_drbg_seed( mbedtls_ctr_drbg_context *ctx,
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000279 int (*f_entropy)(void *, unsigned char *, size_t),
280 void *p_entropy,
Paul Bakker1bc9efc2011-12-03 11:29:32 +0000281 const unsigned char *custom,
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000282 size_t len );
283
284/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000285 * \brief This function clears CTR_CRBG context data.
Paul Bakkerfff03662014-06-18 16:21:25 +0200286 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000287 * \param ctx The CTR_DRBG context to clear.
Paul Bakkerfff03662014-06-18 16:21:25 +0200288 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200289void mbedtls_ctr_drbg_free( mbedtls_ctr_drbg_context *ctx );
Paul Bakkerfff03662014-06-18 16:21:25 +0200290
291/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000292 * \brief This function turns prediction resistance on or off.
293 * The default value is off.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000294 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000295 * \note If enabled, entropy is gathered at the beginning of
Gilles Peskine25e19452019-10-02 18:54:20 +0200296 * every call to mbedtls_ctr_drbg_random_with_add()
297 * or mbedtls_ctr_drbg_random().
Rose Zadik2f8163d2018-01-25 21:55:14 +0000298 * Only use this if your entropy source has sufficient
299 * throughput.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000300 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000301 * \param ctx The CTR_DRBG context.
302 * \param resistance #MBEDTLS_CTR_DRBG_PR_ON or #MBEDTLS_CTR_DRBG_PR_OFF.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000303 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200304void mbedtls_ctr_drbg_set_prediction_resistance( mbedtls_ctr_drbg_context *ctx,
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000305 int resistance );
306
307/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000308 * \brief This function sets the amount of entropy grabbed on each
Gilles Peskineb729e1b2019-10-04 12:15:55 +0200309 * seed or reseed.
Gilles Peskineeb99c102019-10-02 18:56:17 +0200310 *
311 * The default value is #MBEDTLS_CTR_DRBG_ENTROPY_LEN.
312 *
Gilles Peskinedff36822019-10-03 15:10:21 +0200313 * \note The security strength of CTR_DRBG is bounded by the
314 * entropy length. Thus \p len must be at least
315 * 32 (in bytes) to achieve a 256-bit strength.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000316 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000317 * \param ctx The CTR_DRBG context.
Gilles Peskine25e19452019-10-02 18:54:20 +0200318 * \param len The amount of entropy to grab, in bytes.
319 * This must be at most #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000320 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200321void mbedtls_ctr_drbg_set_entropy_len( mbedtls_ctr_drbg_context *ctx,
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000322 size_t len );
323
324/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000325 * \brief This function sets the reseed interval.
Gilles Peskine25e19452019-10-02 18:54:20 +0200326 *
327 * The reseed interval is the number of calls to mbedtls_ctr_drbg_random()
328 * or mbedtls_ctr_drbg_random_with_add() after which the entropy function
329 * is called again.
330 *
331 * The default value is #MBEDTLS_CTR_DRBG_RESEED_INTERVAL.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000332 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000333 * \param ctx The CTR_DRBG context.
334 * \param interval The reseed interval.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000335 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200336void mbedtls_ctr_drbg_set_reseed_interval( mbedtls_ctr_drbg_context *ctx,
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000337 int interval );
338
339/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000340 * \brief This function reseeds the CTR_DRBG context, that is
341 * extracts data from the entropy source.
Paul Bakker9af723c2014-05-01 13:03:14 +0200342 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000343 * \param ctx The CTR_DRBG context.
Gilles Peskine25e19452019-10-02 18:54:20 +0200344 * \param additional Additional data to add to the state. Can be \c NULL.
Rose Zadik2f8163d2018-01-25 21:55:14 +0000345 * \param len The length of the additional data.
Gilles Peskine25e19452019-10-02 18:54:20 +0200346 * This must be less than
347 * #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT - \c entropy_len
348 * where \c entropy_len is the entropy length
349 * configured for the context.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000350 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000351 * \return \c 0 on success, or
352 * #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000353 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200354int mbedtls_ctr_drbg_reseed( mbedtls_ctr_drbg_context *ctx,
Paul Bakker1bc9efc2011-12-03 11:29:32 +0000355 const unsigned char *additional, size_t len );
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000356
357/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000358 * \brief This function updates the state of the CTR_DRBG context.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000359 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000360 * \param ctx The CTR_DRBG context.
Gilles Peskine25e19452019-10-02 18:54:20 +0200361 * \param additional The data to update the state with. This must not be
362 * \c NULL unless \p add_len is \c 0.
Gilles Peskine9ce29722018-09-11 16:41:54 +0200363 * \param add_len Length of \p additional in bytes. This must be at
364 * most #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT.
Manuel Pégourié-Gonnard5cb4b312014-11-25 17:41:50 +0100365 *
Gilles Peskine9ce29722018-09-11 16:41:54 +0200366 * \return \c 0 on success.
367 * \return #MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG if
368 * \p add_len is more than
369 * #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT.
370 * \return An error from the underlying AES cipher on failure.
371 */
372int mbedtls_ctr_drbg_update_ret( mbedtls_ctr_drbg_context *ctx,
373 const unsigned char *additional,
374 size_t add_len );
375
376/**
377 * \brief This function updates the state of the CTR_DRBG context.
378 *
379 * \warning This function cannot report errors. You should use
380 * mbedtls_ctr_drbg_update_ret() instead.
381 *
382 * \note If \p add_len is greater than
383 * #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT, only the first
384 * #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT Bytes are used.
385 * The remaining Bytes are silently discarded.
386 *
387 * \param ctx The CTR_DRBG context.
Gilles Peskine25e19452019-10-02 18:54:20 +0200388 * \param additional The data to update the state with. This must not be
389 * \c NULL unless \p add_len is \c 0.
390 * \param add_len Length of \p additional data. This must be at
391 * most #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000392 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200393void mbedtls_ctr_drbg_update( mbedtls_ctr_drbg_context *ctx,
Gilles Peskine9ce29722018-09-11 16:41:54 +0200394 const unsigned char *additional,
395 size_t add_len );
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000396
397/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000398 * \brief This function updates a CTR_DRBG instance with additional
399 * data and uses it to generate random data.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000400 *
Gilles Peskine25e19452019-10-02 18:54:20 +0200401 * This function automatically reseeds if the reseed counter is exceeded
402 * or prediction resistance is enabled.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000403 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000404 * \param p_rng The CTR_DRBG context. This must be a pointer to a
405 * #mbedtls_ctr_drbg_context structure.
406 * \param output The buffer to fill.
Gilles Peskine25e19452019-10-02 18:54:20 +0200407 * \param output_len The length of the buffer in bytes.
408 * \param additional Additional data to update. Can be \c NULL, in which
409 * case the additional data is empty regardless of
410 * the value of \p add_len.
411 * \param add_len The length of the additional data
412 * if \p additional is not \c NULL.
413 * This must be less than #MBEDTLS_CTR_DRBG_MAX_INPUT
414 * and less than
415 * #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT - \c entropy_len
416 * where \c entropy_len is the entropy length
417 * configured for the context.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000418 *
Gilles Peskine25e19452019-10-02 18:54:20 +0200419 * \return \c 0 on success.
420 * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
Rose Zadik2f8163d2018-01-25 21:55:14 +0000421 * #MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000422 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200423int mbedtls_ctr_drbg_random_with_add( void *p_rng,
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000424 unsigned char *output, size_t output_len,
Paul Bakker1bc9efc2011-12-03 11:29:32 +0000425 const unsigned char *additional, size_t add_len );
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000426
427/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000428 * \brief This function uses CTR_DRBG to generate random data.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000429 *
Gilles Peskine25e19452019-10-02 18:54:20 +0200430 * This function automatically reseeds if the reseed counter is exceeded
431 * or prediction resistance is enabled.
432 *
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000433 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000434 * \param p_rng The CTR_DRBG context. This must be a pointer to a
435 * #mbedtls_ctr_drbg_context structure.
436 * \param output The buffer to fill.
Gilles Peskine25e19452019-10-02 18:54:20 +0200437 * \param output_len The length of the buffer in bytes.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000438 *
Gilles Peskine25e19452019-10-02 18:54:20 +0200439 * \return \c 0 on success.
440 * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
Rose Zadik2f8163d2018-01-25 21:55:14 +0000441 * #MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000442 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200443int mbedtls_ctr_drbg_random( void *p_rng,
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000444 unsigned char *output, size_t output_len );
445
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200446#if defined(MBEDTLS_FS_IO)
Paul Bakkerfc754a92011-12-05 13:23:51 +0000447/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000448 * \brief This function writes a seed file.
Paul Bakkerfc754a92011-12-05 13:23:51 +0000449 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000450 * \param ctx The CTR_DRBG context.
451 * \param path The name of the file.
Paul Bakkerfc754a92011-12-05 13:23:51 +0000452 *
Gilles Peskine25e19452019-10-02 18:54:20 +0200453 * \return \c 0 on success.
454 * \return #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error.
455 * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on reseed
Rose Zadik2f8163d2018-01-25 21:55:14 +0000456 * failure.
Paul Bakkerfc754a92011-12-05 13:23:51 +0000457 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200458int mbedtls_ctr_drbg_write_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path );
Paul Bakkerfc754a92011-12-05 13:23:51 +0000459
460/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000461 * \brief This function reads and updates a seed file. The seed
462 * is added to this instance.
Paul Bakkerfc754a92011-12-05 13:23:51 +0000463 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000464 * \param ctx The CTR_DRBG context.
465 * \param path The name of the file.
Paul Bakkerfc754a92011-12-05 13:23:51 +0000466 *
Gilles Peskine25e19452019-10-02 18:54:20 +0200467 * \return \c 0 on success.
468 * \return #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error.
469 * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on
470 * reseed failure.
471 * \return #MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG if the existing
472 * seed file is too large.
Paul Bakkerfc754a92011-12-05 13:23:51 +0000473 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200474int mbedtls_ctr_drbg_update_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path );
475#endif /* MBEDTLS_FS_IO */
Paul Bakkerfc754a92011-12-05 13:23:51 +0000476
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000477/**
Rose Zadik2f8163d2018-01-25 21:55:14 +0000478 * \brief The CTR_DRBG checkup routine.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000479 *
Rose Zadik2f8163d2018-01-25 21:55:14 +0000480 * \return \c 0 on success, or \c 1 on failure.
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000481 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200482int mbedtls_ctr_drbg_self_test( int verbose );
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000483
Paul Bakker534f82c2013-06-25 16:47:55 +0200484/* Internal functions (do not call directly) */
Manuel Pégourié-Gonnard8d128ef2015-04-28 22:38:08 +0200485int mbedtls_ctr_drbg_seed_entropy_len( mbedtls_ctr_drbg_context *,
Paul Bakkerb9e4e2c2014-05-01 14:18:25 +0200486 int (*)(void *, unsigned char *, size_t), void *,
487 const unsigned char *, size_t, size_t );
Paul Bakker534f82c2013-06-25 16:47:55 +0200488
Paul Bakker0e04d0e2011-11-27 14:46:59 +0000489#ifdef __cplusplus
490}
491#endif
492
493#endif /* ctr_drbg.h */