]> git.zerfleddert.de Git - proxmark3-svn/blame - common/mbedtls/ctr_drbg.h
Merge pull request #969 from pwpiwi/gcc10_fixes
[proxmark3-svn] / common / mbedtls / ctr_drbg.h
CommitLineData
700d8687
OM
1/**
2 * \file ctr_drbg.h
3 *
4 * \brief This file contains CTR_DRBG definitions and functions.
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>.
10 *
11 * The Mbed TLS implementation of CTR_DRBG uses AES-256 as the underlying
12 * block cipher.
13 */
14/*
15 * Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
16 * SPDX-License-Identifier: GPL-2.0
17 *
18 * This program is free software; you can redistribute it and/or modify
19 * it under the terms of the GNU General Public License as published by
20 * the Free Software Foundation; either version 2 of the License, or
21 * (at your option) any later version.
22 *
23 * This program is distributed in the hope that it will be useful,
24 * but WITHOUT ANY WARRANTY; without even the implied warranty of
25 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
26 * GNU General Public License for more details.
27 *
28 * You should have received a copy of the GNU General Public License along
29 * with this program; if not, write to the Free Software Foundation, Inc.,
30 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
31 *
32 * This file is part of Mbed TLS (https://tls.mbed.org)
33 */
34
35#ifndef MBEDTLS_CTR_DRBG_H
36#define MBEDTLS_CTR_DRBG_H
37
38#include "aes.h"
39
40#if defined(MBEDTLS_THREADING_C)
41#include "threading.h"
42#endif
43
44#define MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED -0x0034 /**< The entropy source failed. */
45#define MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG -0x0036 /**< The requested random buffer length is too big. */
46#define MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG -0x0038 /**< The input (entropy + additional data) is too large. */
47#define MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR -0x003A /**< Read or write error in file. */
48
49#define MBEDTLS_CTR_DRBG_BLOCKSIZE 16 /**< The block size used by the cipher. */
50#define MBEDTLS_CTR_DRBG_KEYSIZE 32 /**< The key size used by the cipher. */
51#define MBEDTLS_CTR_DRBG_KEYBITS ( MBEDTLS_CTR_DRBG_KEYSIZE * 8 ) /**< The key size for the DRBG operation, in bits. */
52#define MBEDTLS_CTR_DRBG_SEEDLEN ( MBEDTLS_CTR_DRBG_KEYSIZE + MBEDTLS_CTR_DRBG_BLOCKSIZE ) /**< The seed length, calculated as (counter + AES key). */
53
54/**
55 * \name SECTION: Module settings
56 *
57 * The configuration options you can set for this module are in this section.
58 * Either change them in config.h or define them using the compiler command
59 * line.
60 * \{
61 */
62
63#if !defined(MBEDTLS_CTR_DRBG_ENTROPY_LEN)
64#if defined(MBEDTLS_SHA512_C) && !defined(MBEDTLS_ENTROPY_FORCE_SHA256)
65#define MBEDTLS_CTR_DRBG_ENTROPY_LEN 48
66/**< The amount of entropy used per seed by default:
67 * <ul><li>48 with SHA-512.</li>
68 * <li>32 with SHA-256.</li></ul>
69 */
70#else
71#define MBEDTLS_CTR_DRBG_ENTROPY_LEN 32
72/**< Amount of entropy used per seed by default:
73 * <ul><li>48 with SHA-512.</li>
74 * <li>32 with SHA-256.</li></ul>
75 */
76#endif
77#endif
78
79#if !defined(MBEDTLS_CTR_DRBG_RESEED_INTERVAL)
80#define MBEDTLS_CTR_DRBG_RESEED_INTERVAL 10000
81/**< The interval before reseed is performed by default. */
82#endif
83
84#if !defined(MBEDTLS_CTR_DRBG_MAX_INPUT)
85#define MBEDTLS_CTR_DRBG_MAX_INPUT 256
86/**< The maximum number of additional input Bytes. */
87#endif
88
89#if !defined(MBEDTLS_CTR_DRBG_MAX_REQUEST)
90#define MBEDTLS_CTR_DRBG_MAX_REQUEST 1024
91/**< The maximum number of requested Bytes per call. */
92#endif
93
94#if !defined(MBEDTLS_CTR_DRBG_MAX_SEED_INPUT)
95#define MBEDTLS_CTR_DRBG_MAX_SEED_INPUT 384
96/**< The maximum size of seed or reseed buffer. */
97#endif
98
99/* \} name SECTION: Module settings */
100
101#define MBEDTLS_CTR_DRBG_PR_OFF 0
102/**< Prediction resistance is disabled. */
103#define MBEDTLS_CTR_DRBG_PR_ON 1
104/**< Prediction resistance is enabled. */
105
106#ifdef __cplusplus
107extern "C" {
108#endif
109
110/**
111 * \brief The CTR_DRBG context structure.
112 */
113typedef struct mbedtls_ctr_drbg_context
114{
115 unsigned char counter[16]; /*!< The counter (V). */
116 int reseed_counter; /*!< The reseed counter. */
117 int prediction_resistance; /*!< This determines whether prediction
118 resistance is enabled, that is
119 whether to systematically reseed before
120 each random generation. */
121 size_t entropy_len; /*!< The amount of entropy grabbed on each
122 seed or reseed operation. */
123 int reseed_interval; /*!< The reseed interval. */
124
125 mbedtls_aes_context aes_ctx; /*!< The AES context. */
126
127 /*
128 * Callbacks (Entropy)
129 */
130 int (*f_entropy)(void *, unsigned char *, size_t);
131 /*!< The entropy callback function. */
132
133 void *p_entropy; /*!< The context for the entropy function. */
134
135#if defined(MBEDTLS_THREADING_C)
136 mbedtls_threading_mutex_t mutex;
137#endif
138}
139mbedtls_ctr_drbg_context;
140
141/**
142 * \brief This function initializes the CTR_DRBG context,
143 * and prepares it for mbedtls_ctr_drbg_seed()
144 * or mbedtls_ctr_drbg_free().
145 *
146 * \param ctx The CTR_DRBG context to initialize.
147 */
148void mbedtls_ctr_drbg_init( mbedtls_ctr_drbg_context *ctx );
149
150/**
151 * \brief This function seeds and sets up the CTR_DRBG
152 * entropy source for future reseeds.
153 *
154 * \note Personalization data can be provided in addition to the more generic
155 * entropy source, to make this instantiation as unique as possible.
156 *
157 * \param ctx The CTR_DRBG context to seed.
158 * \param f_entropy The entropy callback, taking as arguments the
159 * \p p_entropy context, the buffer to fill, and the
160 length of the buffer.
161 * \param p_entropy The entropy context.
162 * \param custom Personalization data, that is device-specific
163 identifiers. Can be NULL.
164 * \param len The length of the personalization data.
165 *
166 * \return \c 0 on success.
167 * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure.
168 */
169int mbedtls_ctr_drbg_seed( mbedtls_ctr_drbg_context *ctx,
170 int (*f_entropy)(void *, unsigned char *, size_t),
171 void *p_entropy,
172 const unsigned char *custom,
173 size_t len );
174
175/**
176 * \brief This function clears CTR_CRBG context data.
177 *
178 * \param ctx The CTR_DRBG context to clear.
179 */
180void mbedtls_ctr_drbg_free( mbedtls_ctr_drbg_context *ctx );
181
182/**
183 * \brief This function turns prediction resistance on or off.
184 * The default value is off.
185 *
186 * \note If enabled, entropy is gathered at the beginning of
187 * every call to mbedtls_ctr_drbg_random_with_add().
188 * Only use this if your entropy source has sufficient
189 * throughput.
190 *
191 * \param ctx The CTR_DRBG context.
192 * \param resistance #MBEDTLS_CTR_DRBG_PR_ON or #MBEDTLS_CTR_DRBG_PR_OFF.
193 */
194void mbedtls_ctr_drbg_set_prediction_resistance( mbedtls_ctr_drbg_context *ctx,
195 int resistance );
196
197/**
198 * \brief This function sets the amount of entropy grabbed on each
199 * seed or reseed. The default value is
200 * #MBEDTLS_CTR_DRBG_ENTROPY_LEN.
201 *
202 * \param ctx The CTR_DRBG context.
203 * \param len The amount of entropy to grab.
204 */
205void mbedtls_ctr_drbg_set_entropy_len( mbedtls_ctr_drbg_context *ctx,
206 size_t len );
207
208/**
209 * \brief This function sets the reseed interval.
210 * The default value is #MBEDTLS_CTR_DRBG_RESEED_INTERVAL.
211 *
212 * \param ctx The CTR_DRBG context.
213 * \param interval The reseed interval.
214 */
215void mbedtls_ctr_drbg_set_reseed_interval( mbedtls_ctr_drbg_context *ctx,
216 int interval );
217
218/**
219 * \brief This function reseeds the CTR_DRBG context, that is
220 * extracts data from the entropy source.
221 *
222 * \param ctx The CTR_DRBG context.
223 * \param additional Additional data to add to the state. Can be NULL.
224 * \param len The length of the additional data.
225 *
226 * \return \c 0 on success.
227 * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure.
228 */
229int mbedtls_ctr_drbg_reseed( mbedtls_ctr_drbg_context *ctx,
230 const unsigned char *additional, size_t len );
231
232/**
233 * \brief This function updates the state of the CTR_DRBG context.
234 *
235 * \note If \p add_len is greater than
236 * #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT, only the first
237 * #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT Bytes are used.
238 * The remaining Bytes are silently discarded.
239 *
240 * \param ctx The CTR_DRBG context.
241 * \param additional The data to update the state with.
242 * \param add_len Length of \p additional data.
243 *
244 */
245void mbedtls_ctr_drbg_update( mbedtls_ctr_drbg_context *ctx,
246 const unsigned char *additional, size_t add_len );
247
248/**
249 * \brief This function updates a CTR_DRBG instance with additional
250 * data and uses it to generate random data.
251 *
252 * \note The function automatically reseeds if the reseed counter is exceeded.
253 *
254 * \param p_rng The CTR_DRBG context. This must be a pointer to a
255 * #mbedtls_ctr_drbg_context structure.
256 * \param output The buffer to fill.
257 * \param output_len The length of the buffer.
258 * \param additional Additional data to update. Can be NULL.
259 * \param add_len The length of the additional data.
260 *
261 * \return \c 0 on success.
262 * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
263 * #MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure.
264 */
265int mbedtls_ctr_drbg_random_with_add( void *p_rng,
266 unsigned char *output, size_t output_len,
267 const unsigned char *additional, size_t add_len );
268
269/**
270 * \brief This function uses CTR_DRBG to generate random data.
271 *
272 * \note The function automatically reseeds if the reseed counter is exceeded.
273 *
274 * \param p_rng The CTR_DRBG context. This must be a pointer to a
275 * #mbedtls_ctr_drbg_context structure.
276 * \param output The buffer to fill.
277 * \param output_len The length of the buffer.
278 *
279 * \return \c 0 on success.
280 * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
281 * #MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure.
282 */
283int mbedtls_ctr_drbg_random( void *p_rng,
284 unsigned char *output, size_t output_len );
285
286#if defined(MBEDTLS_FS_IO)
287/**
288 * \brief This function writes a seed file.
289 *
290 * \param ctx The CTR_DRBG context.
291 * \param path The name of the file.
292 *
293 * \return \c 0 on success.
294 * \return #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error.
295 * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on
296 * failure.
297 */
298int mbedtls_ctr_drbg_write_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path );
299
300/**
301 * \brief This function reads and updates a seed file. The seed
302 * is added to this instance.
303 *
304 * \param ctx The CTR_DRBG context.
305 * \param path The name of the file.
306 *
307 * \return \c 0 on success.
308 * \return #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error.
309 * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
310 * #MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG on failure.
311 */
312int mbedtls_ctr_drbg_update_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path );
313#endif /* MBEDTLS_FS_IO */
314
315/**
316 * \brief The CTR_DRBG checkup routine.
317 *
318 * \return \c 0 on success.
319 * \return \c 1 on failure.
320 */
321int mbedtls_ctr_drbg_self_test( int verbose );
322
323/* Internal functions (do not call directly) */
324int mbedtls_ctr_drbg_seed_entropy_len( mbedtls_ctr_drbg_context *,
325 int (*)(void *, unsigned char *, size_t), void *,
326 const unsigned char *, size_t, size_t );
327
328#ifdef __cplusplus
329}
330#endif
331
332#endif /* ctr_drbg.h */
Impressum, Datenschutz