source: azure_iot_hub_mbedtls/trunk/mbedtls-2.16.1/include/mbedtls/ctr_drbg.h@ 398

Last change on this file since 398 was 398, checked in by coas-nagasima, 5 years ago

mbedTLS版Azure IoT Hub接続サンプルのソースコードを追加
  • Property svn:eol-style set to native
  • Property svn:mime-type set to text/x-chdr;charset=UTF-8
File size: 13.9 KB
Line 
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
120extern "C" {
121#endif
122
123/**
124 * \brief The CTR_DRBG context structure.
125 */
126typedef 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}
152mbedtls_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 */
161void 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 */
182int 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 */
193void 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 */
207void 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 */
218void 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 */
228void 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 */
242int 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 */
259int 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 */
280int 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 */
298int 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 */
323MBEDTLS_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 */
342int 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 */
356int 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 */
367int mbedtls_ctr_drbg_self_test( int verbose );
368
369#endif /* MBEDTLS_SELF_TEST */
370
371/* Internal functions (do not call directly) */
372int 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 */
Note: See TracBrowser for help on using the repository browser.