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 (default) or AES-128
|
---|
12 | * as the underlying block cipher.
|
---|
13 | *
|
---|
14 | * \warning Using 128-bit keys for CTR_DRBG limits the security of generated
|
---|
15 | * keys and operations that use random values generated to 128-bit security.
|
---|
16 | */
|
---|
17 | /*
|
---|
18 | * Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
|
---|
19 | * SPDX-License-Identifier: Apache-2.0
|
---|
20 | *
|
---|
21 | * Licensed under the Apache License, Version 2.0 (the "License"); you may
|
---|
22 | * not use this file except in compliance with the License.
|
---|
23 | * You may obtain a copy of the License at
|
---|
24 | *
|
---|
25 | * http://www.apache.org/licenses/LICENSE-2.0
|
---|
26 | *
|
---|
27 | * Unless required by applicable law or agreed to in writing, software
|
---|
28 | * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
---|
29 | * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
---|
30 | * See the License for the specific language governing permissions and
|
---|
31 | * limitations under the License.
|
---|
32 | *
|
---|
33 | * This file is part of Mbed TLS (https://tls.mbed.org)
|
---|
34 | */
|
---|
35 |
|
---|
36 | #ifndef MBEDTLS_CTR_DRBG_H
|
---|
37 | #define MBEDTLS_CTR_DRBG_H
|
---|
38 |
|
---|
39 | #if !defined(MBEDTLS_CONFIG_FILE)
|
---|
40 | #include "config.h"
|
---|
41 | #else
|
---|
42 | #include MBEDTLS_CONFIG_FILE
|
---|
43 | #endif
|
---|
44 |
|
---|
45 | #include "aes.h"
|
---|
46 |
|
---|
47 | #if defined(MBEDTLS_THREADING_C)
|
---|
48 | #include "threading.h"
|
---|
49 | #endif
|
---|
50 |
|
---|
51 | #define MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED -0x0034 /**< The entropy source failed. */
|
---|
52 | #define MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG -0x0036 /**< The requested random buffer length is too big. */
|
---|
53 | #define MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG -0x0038 /**< The input (entropy + additional data) is too large. */
|
---|
54 | #define MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR -0x003A /**< Read or write error in file. */
|
---|
55 |
|
---|
56 | #define MBEDTLS_CTR_DRBG_BLOCKSIZE 16 /**< The block size used by the cipher. */
|
---|
57 |
|
---|
58 | #if defined(MBEDTLS_CTR_DRBG_USE_128_BIT_KEY)
|
---|
59 | #define MBEDTLS_CTR_DRBG_KEYSIZE 16 /**< The key size used by the cipher (compile-time choice: 128 bits). */
|
---|
60 | #else
|
---|
61 | #define MBEDTLS_CTR_DRBG_KEYSIZE 32 /**< The key size used by the cipher (compile-time choice: 256 bits). */
|
---|
62 | #endif
|
---|
63 |
|
---|
64 | #define MBEDTLS_CTR_DRBG_KEYBITS ( MBEDTLS_CTR_DRBG_KEYSIZE * 8 ) /**< The key size for the DRBG operation, in bits. */
|
---|
65 | #define MBEDTLS_CTR_DRBG_SEEDLEN ( MBEDTLS_CTR_DRBG_KEYSIZE + MBEDTLS_CTR_DRBG_BLOCKSIZE ) /**< The seed length, calculated as (counter + AES key). */
|
---|
66 |
|
---|
67 | /**
|
---|
68 | * \name SECTION: Module settings
|
---|
69 | *
|
---|
70 | * The configuration options you can set for this module are in this section.
|
---|
71 | * Either change them in config.h or define them using the compiler command
|
---|
72 | * line.
|
---|
73 | * \{
|
---|
74 | */
|
---|
75 |
|
---|
76 | #if !defined(MBEDTLS_CTR_DRBG_ENTROPY_LEN)
|
---|
77 | #if defined(MBEDTLS_SHA512_C) && !defined(MBEDTLS_ENTROPY_FORCE_SHA256)
|
---|
78 | #define MBEDTLS_CTR_DRBG_ENTROPY_LEN 48
|
---|
79 | /**< The amount of entropy used per seed by default:
|
---|
80 | * <ul><li>48 with SHA-512.</li>
|
---|
81 | * <li>32 with SHA-256.</li></ul>
|
---|
82 | */
|
---|
83 | #else
|
---|
84 | #define MBEDTLS_CTR_DRBG_ENTROPY_LEN 32
|
---|
85 | /**< Amount of entropy used per seed by default:
|
---|
86 | * <ul><li>48 with SHA-512.</li>
|
---|
87 | * <li>32 with SHA-256.</li></ul>
|
---|
88 | */
|
---|
89 | #endif
|
---|
90 | #endif
|
---|
91 |
|
---|
92 | #if !defined(MBEDTLS_CTR_DRBG_RESEED_INTERVAL)
|
---|
93 | #define MBEDTLS_CTR_DRBG_RESEED_INTERVAL 10000
|
---|
94 | /**< The interval before reseed is performed by default. */
|
---|
95 | #endif
|
---|
96 |
|
---|
97 | #if !defined(MBEDTLS_CTR_DRBG_MAX_INPUT)
|
---|
98 | #define MBEDTLS_CTR_DRBG_MAX_INPUT 256
|
---|
99 | /**< The maximum number of additional input Bytes. */
|
---|
100 | #endif
|
---|
101 |
|
---|
102 | #if !defined(MBEDTLS_CTR_DRBG_MAX_REQUEST)
|
---|
103 | #define MBEDTLS_CTR_DRBG_MAX_REQUEST 1024
|
---|
104 | /**< The maximum number of requested Bytes per call. */
|
---|
105 | #endif
|
---|
106 |
|
---|
107 | #if !defined(MBEDTLS_CTR_DRBG_MAX_SEED_INPUT)
|
---|
108 | #define MBEDTLS_CTR_DRBG_MAX_SEED_INPUT 384
|
---|
109 | /**< The maximum size of seed or reseed buffer. */
|
---|
110 | #endif
|
---|
111 |
|
---|
112 | /* \} name SECTION: Module settings */
|
---|
113 |
|
---|
114 | #define MBEDTLS_CTR_DRBG_PR_OFF 0
|
---|
115 | /**< Prediction resistance is disabled. */
|
---|
116 | #define MBEDTLS_CTR_DRBG_PR_ON 1
|
---|
117 | /**< Prediction resistance is enabled. */
|
---|
118 |
|
---|
119 | #ifdef __cplusplus
|
---|
120 | extern "C" {
|
---|
121 | #endif
|
---|
122 |
|
---|
123 | /**
|
---|
124 | * \brief The CTR_DRBG context structure.
|
---|
125 | */
|
---|
126 | typedef struct mbedtls_ctr_drbg_context
|
---|
127 | {
|
---|
128 | unsigned char counter[16]; /*!< The counter (V). */
|
---|
129 | int reseed_counter; /*!< The reseed counter. */
|
---|
130 | int prediction_resistance; /*!< This determines whether prediction
|
---|
131 | resistance is enabled, that is
|
---|
132 | whether to systematically reseed before
|
---|
133 | each random generation. */
|
---|
134 | size_t entropy_len; /*!< The amount of entropy grabbed on each
|
---|
135 | seed or reseed operation. */
|
---|
136 | int reseed_interval; /*!< The reseed interval. */
|
---|
137 |
|
---|
138 | mbedtls_aes_context aes_ctx; /*!< The AES context. */
|
---|
139 |
|
---|
140 | /*
|
---|
141 | * Callbacks (Entropy)
|
---|
142 | */
|
---|
143 | int (*f_entropy)(void *, unsigned char *, size_t);
|
---|
144 | /*!< The entropy callback function. */
|
---|
145 |
|
---|
146 | void *p_entropy; /*!< The context for the entropy function. */
|
---|
147 |
|
---|
148 | #if defined(MBEDTLS_THREADING_C)
|
---|
149 | mbedtls_threading_mutex_t mutex;
|
---|
150 | #endif
|
---|
151 | }
|
---|
152 | mbedtls_ctr_drbg_context;
|
---|
153 |
|
---|
154 | /**
|
---|
155 | * \brief This function initializes the CTR_DRBG context,
|
---|
156 | * and prepares it for mbedtls_ctr_drbg_seed()
|
---|
157 | * or mbedtls_ctr_drbg_free().
|
---|
158 | *
|
---|
159 | * \param ctx The CTR_DRBG context to initialize.
|
---|
160 | */
|
---|
161 | void mbedtls_ctr_drbg_init( mbedtls_ctr_drbg_context *ctx );
|
---|
162 |
|
---|
163 | /**
|
---|
164 | * \brief This function seeds and sets up the CTR_DRBG
|
---|
165 | * entropy source for future reseeds.
|
---|
166 | *
|
---|
167 | * \note Personalization data can be provided in addition to the more generic
|
---|
168 | * entropy source, to make this instantiation as unique as possible.
|
---|
169 | *
|
---|
170 | * \param ctx The CTR_DRBG context to seed.
|
---|
171 | * \param f_entropy The entropy callback, taking as arguments the
|
---|
172 | * \p p_entropy context, the buffer to fill, and the
|
---|
173 | length of the buffer.
|
---|
174 | * \param p_entropy The entropy context.
|
---|
175 | * \param custom Personalization data, that is device-specific
|
---|
176 | identifiers. Can be NULL.
|
---|
177 | * \param len The length of the personalization data.
|
---|
178 | *
|
---|
179 | * \return \c 0 on success.
|
---|
180 | * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure.
|
---|
181 | */
|
---|
182 | int mbedtls_ctr_drbg_seed( mbedtls_ctr_drbg_context *ctx,
|
---|
183 | int (*f_entropy)(void *, unsigned char *, size_t),
|
---|
184 | void *p_entropy,
|
---|
185 | const unsigned char *custom,
|
---|
186 | size_t len );
|
---|
187 |
|
---|
188 | /**
|
---|
189 | * \brief This function clears CTR_CRBG context data.
|
---|
190 | *
|
---|
191 | * \param ctx The CTR_DRBG context to clear.
|
---|
192 | */
|
---|
193 | void mbedtls_ctr_drbg_free( mbedtls_ctr_drbg_context *ctx );
|
---|
194 |
|
---|
195 | /**
|
---|
196 | * \brief This function turns prediction resistance on or off.
|
---|
197 | * The default value is off.
|
---|
198 | *
|
---|
199 | * \note If enabled, entropy is gathered at the beginning of
|
---|
200 | * every call to mbedtls_ctr_drbg_random_with_add().
|
---|
201 | * Only use this if your entropy source has sufficient
|
---|
202 | * throughput.
|
---|
203 | *
|
---|
204 | * \param ctx The CTR_DRBG context.
|
---|
205 | * \param resistance #MBEDTLS_CTR_DRBG_PR_ON or #MBEDTLS_CTR_DRBG_PR_OFF.
|
---|
206 | */
|
---|
207 | void mbedtls_ctr_drbg_set_prediction_resistance( mbedtls_ctr_drbg_context *ctx,
|
---|
208 | int resistance );
|
---|
209 |
|
---|
210 | /**
|
---|
211 | * \brief This function sets the amount of entropy grabbed on each
|
---|
212 | * seed or reseed. The default value is
|
---|
213 | * #MBEDTLS_CTR_DRBG_ENTROPY_LEN.
|
---|
214 | *
|
---|
215 | * \param ctx The CTR_DRBG context.
|
---|
216 | * \param len The amount of entropy to grab.
|
---|
217 | */
|
---|
218 | void mbedtls_ctr_drbg_set_entropy_len( mbedtls_ctr_drbg_context *ctx,
|
---|
219 | size_t len );
|
---|
220 |
|
---|
221 | /**
|
---|
222 | * \brief This function sets the reseed interval.
|
---|
223 | * The default value is #MBEDTLS_CTR_DRBG_RESEED_INTERVAL.
|
---|
224 | *
|
---|
225 | * \param ctx The CTR_DRBG context.
|
---|
226 | * \param interval The reseed interval.
|
---|
227 | */
|
---|
228 | void mbedtls_ctr_drbg_set_reseed_interval( mbedtls_ctr_drbg_context *ctx,
|
---|
229 | int interval );
|
---|
230 |
|
---|
231 | /**
|
---|
232 | * \brief This function reseeds the CTR_DRBG context, that is
|
---|
233 | * extracts data from the entropy source.
|
---|
234 | *
|
---|
235 | * \param ctx The CTR_DRBG context.
|
---|
236 | * \param additional Additional data to add to the state. Can be NULL.
|
---|
237 | * \param len The length of the additional data.
|
---|
238 | *
|
---|
239 | * \return \c 0 on success.
|
---|
240 | * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure.
|
---|
241 | */
|
---|
242 | int mbedtls_ctr_drbg_reseed( mbedtls_ctr_drbg_context *ctx,
|
---|
243 | const unsigned char *additional, size_t len );
|
---|
244 |
|
---|
245 | /**
|
---|
246 | * \brief This function updates the state of the CTR_DRBG context.
|
---|
247 | *
|
---|
248 | * \param ctx The CTR_DRBG context.
|
---|
249 | * \param additional The data to update the state with.
|
---|
250 | * \param add_len Length of \p additional in bytes. This must be at
|
---|
251 | * most #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT.
|
---|
252 | *
|
---|
253 | * \return \c 0 on success.
|
---|
254 | * \return #MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG if
|
---|
255 | * \p add_len is more than
|
---|
256 | * #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT.
|
---|
257 | * \return An error from the underlying AES cipher on failure.
|
---|
258 | */
|
---|
259 | int mbedtls_ctr_drbg_update_ret( mbedtls_ctr_drbg_context *ctx,
|
---|
260 | const unsigned char *additional,
|
---|
261 | size_t add_len );
|
---|
262 |
|
---|
263 | /**
|
---|
264 | * \brief This function updates a CTR_DRBG instance with additional
|
---|
265 | * data and uses it to generate random data.
|
---|
266 | *
|
---|
267 | * \note The function automatically reseeds if the reseed counter is exceeded.
|
---|
268 | *
|
---|
269 | * \param p_rng The CTR_DRBG context. This must be a pointer to a
|
---|
270 | * #mbedtls_ctr_drbg_context structure.
|
---|
271 | * \param output The buffer to fill.
|
---|
272 | * \param output_len The length of the buffer.
|
---|
273 | * \param additional Additional data to update. Can be NULL.
|
---|
274 | * \param add_len The length of the additional data.
|
---|
275 | *
|
---|
276 | * \return \c 0 on success.
|
---|
277 | * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
|
---|
278 | * #MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure.
|
---|
279 | */
|
---|
280 | int mbedtls_ctr_drbg_random_with_add( void *p_rng,
|
---|
281 | unsigned char *output, size_t output_len,
|
---|
282 | const unsigned char *additional, size_t add_len );
|
---|
283 |
|
---|
284 | /**
|
---|
285 | * \brief This function uses CTR_DRBG to generate random data.
|
---|
286 | *
|
---|
287 | * \note The function automatically reseeds if the reseed counter is exceeded.
|
---|
288 | *
|
---|
289 | * \param p_rng The CTR_DRBG context. This must be a pointer to a
|
---|
290 | * #mbedtls_ctr_drbg_context structure.
|
---|
291 | * \param output The buffer to fill.
|
---|
292 | * \param output_len The length of the buffer.
|
---|
293 | *
|
---|
294 | * \return \c 0 on success.
|
---|
295 | * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
|
---|
296 | * #MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure.
|
---|
297 | */
|
---|
298 | int mbedtls_ctr_drbg_random( void *p_rng,
|
---|
299 | unsigned char *output, size_t output_len );
|
---|
300 |
|
---|
301 |
|
---|
302 | #if ! defined(MBEDTLS_DEPRECATED_REMOVED)
|
---|
303 | #if defined(MBEDTLS_DEPRECATED_WARNING)
|
---|
304 | #define MBEDTLS_DEPRECATED __attribute__((deprecated))
|
---|
305 | #else
|
---|
306 | #define MBEDTLS_DEPRECATED
|
---|
307 | #endif
|
---|
308 | /**
|
---|
309 | * \brief This function updates the state of the CTR_DRBG context.
|
---|
310 | *
|
---|
311 | * \deprecated Superseded by mbedtls_ctr_drbg_update_ret()
|
---|
312 | * in 2.16.0.
|
---|
313 | *
|
---|
314 | * \note If \p add_len is greater than
|
---|
315 | * #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT, only the first
|
---|
316 | * #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT Bytes are used.
|
---|
317 | * The remaining Bytes are silently discarded.
|
---|
318 | *
|
---|
319 | * \param ctx The CTR_DRBG context.
|
---|
320 | * \param additional The data to update the state with.
|
---|
321 | * \param add_len Length of \p additional data.
|
---|
322 | */
|
---|
323 | MBEDTLS_DEPRECATED void mbedtls_ctr_drbg_update(
|
---|
324 | mbedtls_ctr_drbg_context *ctx,
|
---|
325 | const unsigned char *additional,
|
---|
326 | size_t add_len );
|
---|
327 | #undef MBEDTLS_DEPRECATED
|
---|
328 | #endif /* !MBEDTLS_DEPRECATED_REMOVED */
|
---|
329 |
|
---|
330 | #if defined(MBEDTLS_FS_IO)
|
---|
331 | /**
|
---|
332 | * \brief This function writes a seed file.
|
---|
333 | *
|
---|
334 | * \param ctx The CTR_DRBG context.
|
---|
335 | * \param path The name of the file.
|
---|
336 | *
|
---|
337 | * \return \c 0 on success.
|
---|
338 | * \return #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error.
|
---|
339 | * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on
|
---|
340 | * failure.
|
---|
341 | */
|
---|
342 | int mbedtls_ctr_drbg_write_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path );
|
---|
343 |
|
---|
344 | /**
|
---|
345 | * \brief This function reads and updates a seed file. The seed
|
---|
346 | * is added to this instance.
|
---|
347 | *
|
---|
348 | * \param ctx The CTR_DRBG context.
|
---|
349 | * \param path The name of the file.
|
---|
350 | *
|
---|
351 | * \return \c 0 on success.
|
---|
352 | * \return #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error.
|
---|
353 | * \return #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
|
---|
354 | * #MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG on failure.
|
---|
355 | */
|
---|
356 | int mbedtls_ctr_drbg_update_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path );
|
---|
357 | #endif /* MBEDTLS_FS_IO */
|
---|
358 |
|
---|
359 | #if defined(MBEDTLS_SELF_TEST)
|
---|
360 |
|
---|
361 | /**
|
---|
362 | * \brief The CTR_DRBG checkup routine.
|
---|
363 | *
|
---|
364 | * \return \c 0 on success.
|
---|
365 | * \return \c 1 on failure.
|
---|
366 | */
|
---|
367 | int mbedtls_ctr_drbg_self_test( int verbose );
|
---|
368 |
|
---|
369 | #endif /* MBEDTLS_SELF_TEST */
|
---|
370 |
|
---|
371 | /* Internal functions (do not call directly) */
|
---|
372 | int mbedtls_ctr_drbg_seed_entropy_len( mbedtls_ctr_drbg_context *,
|
---|
373 | int (*)(void *, unsigned char *, size_t), void *,
|
---|
374 | const unsigned char *, size_t, size_t );
|
---|
375 |
|
---|
376 | #ifdef __cplusplus
|
---|
377 | }
|
---|
378 | #endif
|
---|
379 |
|
---|
380 | #endif /* ctr_drbg.h */
|
---|