source: azure_iot_hub_mbedtls/trunk/mbedtls-2.16.1/include/mbedtls/hmac_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: 11.9 KB
Line 
1/**
2 * \file hmac_drbg.h
3 *
4 * \brief HMAC_DRBG (NIST SP 800-90A)
5 */
6/*
7 * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
8 * SPDX-License-Identifier: Apache-2.0
9 *
10 * Licensed under the Apache License, Version 2.0 (the "License"); you may
11 * not use this file except in compliance with the License.
12 * You may obtain a copy of the License at
13 *
14 * http://www.apache.org/licenses/LICENSE-2.0
15 *
16 * Unless required by applicable law or agreed to in writing, software
17 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
18 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19 * See the License for the specific language governing permissions and
20 * limitations under the License.
21 *
22 * This file is part of mbed TLS (https://tls.mbed.org)
23 */
24#ifndef MBEDTLS_HMAC_DRBG_H
25#define MBEDTLS_HMAC_DRBG_H
26
27#if !defined(MBEDTLS_CONFIG_FILE)
28#include "config.h"
29#else
30#include MBEDTLS_CONFIG_FILE
31#endif
32
33#include "md.h"
34
35#if defined(MBEDTLS_THREADING_C)
36#include "threading.h"
37#endif
38
39/*
40 * Error codes
41 */
42#define MBEDTLS_ERR_HMAC_DRBG_REQUEST_TOO_BIG -0x0003 /**< Too many random requested in single call. */
43#define MBEDTLS_ERR_HMAC_DRBG_INPUT_TOO_BIG -0x0005 /**< Input too large (Entropy + additional). */
44#define MBEDTLS_ERR_HMAC_DRBG_FILE_IO_ERROR -0x0007 /**< Read/write error in file. */
45#define MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED -0x0009 /**< The entropy source failed. */
46
47/**
48 * \name SECTION: Module settings
49 *
50 * The configuration options you can set for this module are in this section.
51 * Either change them in config.h or define them on the compiler command line.
52 * \{
53 */
54
55#if !defined(MBEDTLS_HMAC_DRBG_RESEED_INTERVAL)
56#define MBEDTLS_HMAC_DRBG_RESEED_INTERVAL 10000 /**< Interval before reseed is performed by default */
57#endif
58
59#if !defined(MBEDTLS_HMAC_DRBG_MAX_INPUT)
60#define MBEDTLS_HMAC_DRBG_MAX_INPUT 256 /**< Maximum number of additional input bytes */
61#endif
62
63#if !defined(MBEDTLS_HMAC_DRBG_MAX_REQUEST)
64#define MBEDTLS_HMAC_DRBG_MAX_REQUEST 1024 /**< Maximum number of requested bytes per call */
65#endif
66
67#if !defined(MBEDTLS_HMAC_DRBG_MAX_SEED_INPUT)
68#define MBEDTLS_HMAC_DRBG_MAX_SEED_INPUT 384 /**< Maximum size of (re)seed buffer */
69#endif
70
71/* \} name SECTION: Module settings */
72
73#define MBEDTLS_HMAC_DRBG_PR_OFF 0 /**< No prediction resistance */
74#define MBEDTLS_HMAC_DRBG_PR_ON 1 /**< Prediction resistance enabled */
75
76#ifdef __cplusplus
77extern "C" {
78#endif
79
80/**
81 * HMAC_DRBG context.
82 */
83typedef struct mbedtls_hmac_drbg_context
84{
85 /* Working state: the key K is not stored explicitely,
86 * but is implied by the HMAC context */
87 mbedtls_md_context_t md_ctx; /*!< HMAC context (inc. K) */
88 unsigned char V[MBEDTLS_MD_MAX_SIZE]; /*!< V in the spec */
89 int reseed_counter; /*!< reseed counter */
90
91 /* Administrative state */
92 size_t entropy_len; /*!< entropy bytes grabbed on each (re)seed */
93 int prediction_resistance; /*!< enable prediction resistance (Automatic
94 reseed before every random generation) */
95 int reseed_interval; /*!< reseed interval */
96
97 /* Callbacks */
98 int (*f_entropy)(void *, unsigned char *, size_t); /*!< entropy function */
99 void *p_entropy; /*!< context for the entropy function */
100
101#if defined(MBEDTLS_THREADING_C)
102 mbedtls_threading_mutex_t mutex;
103#endif
104} mbedtls_hmac_drbg_context;
105
106/**
107 * \brief HMAC_DRBG context initialization
108 * Makes the context ready for mbedtls_hmac_drbg_seed(),
109 * mbedtls_hmac_drbg_seed_buf() or
110 * mbedtls_hmac_drbg_free().
111 *
112 * \param ctx HMAC_DRBG context to be initialized
113 */
114void mbedtls_hmac_drbg_init( mbedtls_hmac_drbg_context *ctx );
115
116/**
117 * \brief HMAC_DRBG initial seeding
118 * Seed and setup entropy source for future reseeds.
119 *
120 * \param ctx HMAC_DRBG context to be seeded
121 * \param md_info MD algorithm to use for HMAC_DRBG
122 * \param f_entropy Entropy callback (p_entropy, buffer to fill, buffer
123 * length)
124 * \param p_entropy Entropy context
125 * \param custom Personalization data (Device specific identifiers)
126 * (Can be NULL)
127 * \param len Length of personalization data
128 *
129 * \note The "security strength" as defined by NIST is set to:
130 * 128 bits if md_alg is SHA-1,
131 * 192 bits if md_alg is SHA-224,
132 * 256 bits if md_alg is SHA-256 or higher.
133 * Note that SHA-256 is just as efficient as SHA-224.
134 *
135 * \return 0 if successful, or
136 * MBEDTLS_ERR_MD_BAD_INPUT_DATA, or
137 * MBEDTLS_ERR_MD_ALLOC_FAILED, or
138 * MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED.
139 */
140int mbedtls_hmac_drbg_seed( mbedtls_hmac_drbg_context *ctx,
141 const mbedtls_md_info_t * md_info,
142 int (*f_entropy)(void *, unsigned char *, size_t),
143 void *p_entropy,
144 const unsigned char *custom,
145 size_t len );
146
147/**
148 * \brief Initilisation of simpified HMAC_DRBG (never reseeds).
149 * (For use with deterministic ECDSA.)
150 *
151 * \param ctx HMAC_DRBG context to be initialised
152 * \param md_info MD algorithm to use for HMAC_DRBG
153 * \param data Concatenation of entropy string and additional data
154 * \param data_len Length of data in bytes
155 *
156 * \return 0 if successful, or
157 * MBEDTLS_ERR_MD_BAD_INPUT_DATA, or
158 * MBEDTLS_ERR_MD_ALLOC_FAILED.
159 */
160int mbedtls_hmac_drbg_seed_buf( mbedtls_hmac_drbg_context *ctx,
161 const mbedtls_md_info_t * md_info,
162 const unsigned char *data, size_t data_len );
163
164/**
165 * \brief Enable / disable prediction resistance (Default: Off)
166 *
167 * Note: If enabled, entropy is used for ctx->entropy_len before each call!
168 * Only use this if you have ample supply of good entropy!
169 *
170 * \param ctx HMAC_DRBG context
171 * \param resistance MBEDTLS_HMAC_DRBG_PR_ON or MBEDTLS_HMAC_DRBG_PR_OFF
172 */
173void mbedtls_hmac_drbg_set_prediction_resistance( mbedtls_hmac_drbg_context *ctx,
174 int resistance );
175
176/**
177 * \brief Set the amount of entropy grabbed on each reseed
178 * (Default: given by the security strength, which
179 * depends on the hash used, see \c mbedtls_hmac_drbg_init() )
180 *
181 * \param ctx HMAC_DRBG context
182 * \param len Amount of entropy to grab, in bytes
183 */
184void mbedtls_hmac_drbg_set_entropy_len( mbedtls_hmac_drbg_context *ctx,
185 size_t len );
186
187/**
188 * \brief Set the reseed interval
189 * (Default: MBEDTLS_HMAC_DRBG_RESEED_INTERVAL)
190 *
191 * \param ctx HMAC_DRBG context
192 * \param interval Reseed interval
193 */
194void mbedtls_hmac_drbg_set_reseed_interval( mbedtls_hmac_drbg_context *ctx,
195 int interval );
196
197/**
198 * \brief HMAC_DRBG update state
199 *
200 * \param ctx HMAC_DRBG context
201 * \param additional Additional data to update state with, or NULL
202 * \param add_len Length of additional data, or 0
203 *
204 * \return \c 0 on success, or an error from the underlying
205 * hash calculation.
206 *
207 * \note Additional data is optional, pass NULL and 0 as second
208 * third argument if no additional data is being used.
209 */
210int mbedtls_hmac_drbg_update_ret( mbedtls_hmac_drbg_context *ctx,
211 const unsigned char *additional, size_t add_len );
212
213/**
214 * \brief HMAC_DRBG reseeding (extracts data from entropy source)
215 *
216 * \param ctx HMAC_DRBG context
217 * \param additional Additional data to add to state (Can be NULL)
218 * \param len Length of additional data
219 *
220 * \return 0 if successful, or
221 * MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED
222 */
223int mbedtls_hmac_drbg_reseed( mbedtls_hmac_drbg_context *ctx,
224 const unsigned char *additional, size_t len );
225
226/**
227 * \brief HMAC_DRBG generate random with additional update input
228 *
229 * Note: Automatically reseeds if reseed_counter is reached or PR is enabled.
230 *
231 * \param p_rng HMAC_DRBG context
232 * \param output Buffer to fill
233 * \param output_len Length of the buffer
234 * \param additional Additional data to update with (can be NULL)
235 * \param add_len Length of additional data (can be 0)
236 *
237 * \return 0 if successful, or
238 * MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED, or
239 * MBEDTLS_ERR_HMAC_DRBG_REQUEST_TOO_BIG, or
240 * MBEDTLS_ERR_HMAC_DRBG_INPUT_TOO_BIG.
241 */
242int mbedtls_hmac_drbg_random_with_add( void *p_rng,
243 unsigned char *output, size_t output_len,
244 const unsigned char *additional,
245 size_t add_len );
246
247/**
248 * \brief HMAC_DRBG generate random
249 *
250 * Note: Automatically reseeds if reseed_counter is reached or PR is enabled.
251 *
252 * \param p_rng HMAC_DRBG context
253 * \param output Buffer to fill
254 * \param out_len Length of the buffer
255 *
256 * \return 0 if successful, or
257 * MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED, or
258 * MBEDTLS_ERR_HMAC_DRBG_REQUEST_TOO_BIG
259 */
260int mbedtls_hmac_drbg_random( void *p_rng, unsigned char *output, size_t out_len );
261
262/**
263 * \brief Free an HMAC_DRBG context
264 *
265 * \param ctx HMAC_DRBG context to free.
266 */
267void mbedtls_hmac_drbg_free( mbedtls_hmac_drbg_context *ctx );
268
269#if ! defined(MBEDTLS_DEPRECATED_REMOVED)
270#if defined(MBEDTLS_DEPRECATED_WARNING)
271#define MBEDTLS_DEPRECATED __attribute__((deprecated))
272#else
273#define MBEDTLS_DEPRECATED
274#endif
275/**
276 * \brief HMAC_DRBG update state
277 *
278 * \deprecated Superseded by mbedtls_hmac_drbg_update_ret()
279 * in 2.16.0.
280 *
281 * \param ctx HMAC_DRBG context
282 * \param additional Additional data to update state with, or NULL
283 * \param add_len Length of additional data, or 0
284 *
285 * \note Additional data is optional, pass NULL and 0 as second
286 * third argument if no additional data is being used.
287 */
288MBEDTLS_DEPRECATED void mbedtls_hmac_drbg_update(
289 mbedtls_hmac_drbg_context *ctx,
290 const unsigned char *additional, size_t add_len );
291#undef MBEDTLS_DEPRECATED
292#endif /* !MBEDTLS_DEPRECATED_REMOVED */
293
294#if defined(MBEDTLS_FS_IO)
295/**
296 * \brief Write a seed file
297 *
298 * \param ctx HMAC_DRBG context
299 * \param path Name of the file
300 *
301 * \return 0 if successful, 1 on file error, or
302 * MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED
303 */
304int mbedtls_hmac_drbg_write_seed_file( mbedtls_hmac_drbg_context *ctx, const char *path );
305
306/**
307 * \brief Read and update a seed file. Seed is added to this
308 * instance
309 *
310 * \param ctx HMAC_DRBG context
311 * \param path Name of the file
312 *
313 * \return 0 if successful, 1 on file error,
314 * MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED or
315 * MBEDTLS_ERR_HMAC_DRBG_INPUT_TOO_BIG
316 */
317int mbedtls_hmac_drbg_update_seed_file( mbedtls_hmac_drbg_context *ctx, const char *path );
318#endif /* MBEDTLS_FS_IO */
319
320
321#if defined(MBEDTLS_SELF_TEST)
322/**
323 * \brief Checkup routine
324 *
325 * \return 0 if successful, or 1 if the test failed
326 */
327int mbedtls_hmac_drbg_self_test( int verbose );
328#endif
329
330#ifdef __cplusplus
331}
332#endif
333
334#endif /* hmac_drbg.h */
Note: See TracBrowser for help on using the repository browser.