4 * \brief HMAC_DRBG (NIST SP 800-90A)
7 * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
8 * SPDX-License-Identifier: GPL-2.0
10 * This program is free software; you can redistribute it and/or modify
11 * it under the terms of the GNU General Public License as published by
12 * the Free Software Foundation; either version 2 of the License, or
13 * (at your option) any later version.
15 * This program is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 * GNU General Public License for more details.
20 * You should have received a copy of the GNU General Public License along
21 * with this program; if not, write to the Free Software Foundation, Inc.,
22 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
24 * This file is part of mbed TLS (https://tls.mbed.org)
26 #ifndef MBEDTLS_HMAC_DRBG_H
27 #define MBEDTLS_HMAC_DRBG_H
31 #if defined(MBEDTLS_THREADING_C)
32 #include "threading.h"
38 #define MBEDTLS_ERR_HMAC_DRBG_REQUEST_TOO_BIG -0x0003 /**< Too many random requested in single call. */
39 #define MBEDTLS_ERR_HMAC_DRBG_INPUT_TOO_BIG -0x0005 /**< Input too large (Entropy + additional). */
40 #define MBEDTLS_ERR_HMAC_DRBG_FILE_IO_ERROR -0x0007 /**< Read/write error in file. */
41 #define MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED -0x0009 /**< The entropy source failed. */
44 * \name SECTION: Module settings
46 * The configuration options you can set for this module are in this section.
47 * Either change them in config.h or define them on the compiler command line.
51 #if !defined(MBEDTLS_HMAC_DRBG_RESEED_INTERVAL)
52 #define MBEDTLS_HMAC_DRBG_RESEED_INTERVAL 10000 /**< Interval before reseed is performed by default */
55 #if !defined(MBEDTLS_HMAC_DRBG_MAX_INPUT)
56 #define MBEDTLS_HMAC_DRBG_MAX_INPUT 256 /**< Maximum number of additional input bytes */
59 #if !defined(MBEDTLS_HMAC_DRBG_MAX_REQUEST)
60 #define MBEDTLS_HMAC_DRBG_MAX_REQUEST 1024 /**< Maximum number of requested bytes per call */
63 #if !defined(MBEDTLS_HMAC_DRBG_MAX_SEED_INPUT)
64 #define MBEDTLS_HMAC_DRBG_MAX_SEED_INPUT 384 /**< Maximum size of (re)seed buffer */
67 /* \} name SECTION: Module settings */
69 #define MBEDTLS_HMAC_DRBG_PR_OFF 0 /**< No prediction resistance */
70 #define MBEDTLS_HMAC_DRBG_PR_ON 1 /**< Prediction resistance enabled */
81 /* Working state: the key K is not stored explicitely,
82 * but is implied by the HMAC context */
83 mbedtls_md_context_t md_ctx
; /*!< HMAC context (inc. K) */
84 unsigned char V
[MBEDTLS_MD_MAX_SIZE
]; /*!< V in the spec */
85 int reseed_counter
; /*!< reseed counter */
87 /* Administrative state */
88 size_t entropy_len
; /*!< entropy bytes grabbed on each (re)seed */
89 int prediction_resistance
; /*!< enable prediction resistance (Automatic
90 reseed before every random generation) */
91 int reseed_interval
; /*!< reseed interval */
94 int (*f_entropy
)(void *, unsigned char *, size_t); /*!< entropy function */
95 void *p_entropy
; /*!< context for the entropy function */
97 #if defined(MBEDTLS_THREADING_C)
98 mbedtls_threading_mutex_t mutex
;
100 } mbedtls_hmac_drbg_context
;
103 * \brief HMAC_DRBG context initialization
104 * Makes the context ready for mbedtls_hmac_drbg_seed(),
105 * mbedtls_hmac_drbg_seed_buf() or
106 * mbedtls_hmac_drbg_free().
108 * \param ctx HMAC_DRBG context to be initialized
110 void mbedtls_hmac_drbg_init( mbedtls_hmac_drbg_context
*ctx
);
113 * \brief HMAC_DRBG initial seeding
114 * Seed and setup entropy source for future reseeds.
116 * \param ctx HMAC_DRBG context to be seeded
117 * \param md_info MD algorithm to use for HMAC_DRBG
118 * \param f_entropy Entropy callback (p_entropy, buffer to fill, buffer
120 * \param p_entropy Entropy context
121 * \param custom Personalization data (Device specific identifiers)
123 * \param len Length of personalization data
125 * \note The "security strength" as defined by NIST is set to:
126 * 128 bits if md_alg is SHA-1,
127 * 192 bits if md_alg is SHA-224,
128 * 256 bits if md_alg is SHA-256 or higher.
129 * Note that SHA-256 is just as efficient as SHA-224.
131 * \return 0 if successful, or
132 * MBEDTLS_ERR_MD_BAD_INPUT_DATA, or
133 * MBEDTLS_ERR_MD_ALLOC_FAILED, or
134 * MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED.
136 int mbedtls_hmac_drbg_seed( mbedtls_hmac_drbg_context
*ctx
,
137 const mbedtls_md_info_t
* md_info
,
138 int (*f_entropy
)(void *, unsigned char *, size_t),
140 const unsigned char *custom
,
144 * \brief Initilisation of simpified HMAC_DRBG (never reseeds).
145 * (For use with deterministic ECDSA.)
147 * \param ctx HMAC_DRBG context to be initialised
148 * \param md_info MD algorithm to use for HMAC_DRBG
149 * \param data Concatenation of entropy string and additional data
150 * \param data_len Length of data in bytes
152 * \return 0 if successful, or
153 * MBEDTLS_ERR_MD_BAD_INPUT_DATA, or
154 * MBEDTLS_ERR_MD_ALLOC_FAILED.
156 int mbedtls_hmac_drbg_seed_buf( mbedtls_hmac_drbg_context
*ctx
,
157 const mbedtls_md_info_t
* md_info
,
158 const unsigned char *data
, size_t data_len
);
161 * \brief Enable / disable prediction resistance (Default: Off)
163 * Note: If enabled, entropy is used for ctx->entropy_len before each call!
164 * Only use this if you have ample supply of good entropy!
166 * \param ctx HMAC_DRBG context
167 * \param resistance MBEDTLS_HMAC_DRBG_PR_ON or MBEDTLS_HMAC_DRBG_PR_OFF
169 void mbedtls_hmac_drbg_set_prediction_resistance( mbedtls_hmac_drbg_context
*ctx
,
173 * \brief Set the amount of entropy grabbed on each reseed
174 * (Default: given by the security strength, which
175 * depends on the hash used, see \c mbedtls_hmac_drbg_init() )
177 * \param ctx HMAC_DRBG context
178 * \param len Amount of entropy to grab, in bytes
180 void mbedtls_hmac_drbg_set_entropy_len( mbedtls_hmac_drbg_context
*ctx
,
184 * \brief Set the reseed interval
185 * (Default: MBEDTLS_HMAC_DRBG_RESEED_INTERVAL)
187 * \param ctx HMAC_DRBG context
188 * \param interval Reseed interval
190 void mbedtls_hmac_drbg_set_reseed_interval( mbedtls_hmac_drbg_context
*ctx
,
194 * \brief HMAC_DRBG update state
196 * \param ctx HMAC_DRBG context
197 * \param additional Additional data to update state with, or NULL
198 * \param add_len Length of additional data, or 0
200 * \note Additional data is optional, pass NULL and 0 as second
201 * third argument if no additional data is being used.
203 void mbedtls_hmac_drbg_update( mbedtls_hmac_drbg_context
*ctx
,
204 const unsigned char *additional
, size_t add_len
);
207 * \brief HMAC_DRBG reseeding (extracts data from entropy source)
209 * \param ctx HMAC_DRBG context
210 * \param additional Additional data to add to state (Can be NULL)
211 * \param len Length of additional data
213 * \return 0 if successful, or
214 * MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED
216 int mbedtls_hmac_drbg_reseed( mbedtls_hmac_drbg_context
*ctx
,
217 const unsigned char *additional
, size_t len
);
220 * \brief HMAC_DRBG generate random with additional update input
222 * Note: Automatically reseeds if reseed_counter is reached or PR is enabled.
224 * \param p_rng HMAC_DRBG context
225 * \param output Buffer to fill
226 * \param output_len Length of the buffer
227 * \param additional Additional data to update with (can be NULL)
228 * \param add_len Length of additional data (can be 0)
230 * \return 0 if successful, or
231 * MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED, or
232 * MBEDTLS_ERR_HMAC_DRBG_REQUEST_TOO_BIG, or
233 * MBEDTLS_ERR_HMAC_DRBG_INPUT_TOO_BIG.
235 int mbedtls_hmac_drbg_random_with_add( void *p_rng
,
236 unsigned char *output
, size_t output_len
,
237 const unsigned char *additional
,
241 * \brief HMAC_DRBG generate random
243 * Note: Automatically reseeds if reseed_counter is reached or PR is enabled.
245 * \param p_rng HMAC_DRBG context
246 * \param output Buffer to fill
247 * \param out_len Length of the buffer
249 * \return 0 if successful, or
250 * MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED, or
251 * MBEDTLS_ERR_HMAC_DRBG_REQUEST_TOO_BIG
253 int mbedtls_hmac_drbg_random( void *p_rng
, unsigned char *output
, size_t out_len
);
256 * \brief Free an HMAC_DRBG context
258 * \param ctx HMAC_DRBG context to free.
260 void mbedtls_hmac_drbg_free( mbedtls_hmac_drbg_context
*ctx
);
262 #if defined(MBEDTLS_FS_IO)
264 * \brief Write a seed file
266 * \param ctx HMAC_DRBG context
267 * \param path Name of the file
269 * \return 0 if successful, 1 on file error, or
270 * MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED
272 int mbedtls_hmac_drbg_write_seed_file( mbedtls_hmac_drbg_context
*ctx
, const char *path
);
275 * \brief Read and update a seed file. Seed is added to this
278 * \param ctx HMAC_DRBG context
279 * \param path Name of the file
281 * \return 0 if successful, 1 on file error,
282 * MBEDTLS_ERR_HMAC_DRBG_ENTROPY_SOURCE_FAILED or
283 * MBEDTLS_ERR_HMAC_DRBG_INPUT_TOO_BIG
285 int mbedtls_hmac_drbg_update_seed_file( mbedtls_hmac_drbg_context
*ctx
, const char *path
);
286 #endif /* MBEDTLS_FS_IO */
289 #if defined(MBEDTLS_SELF_TEST)
291 * \brief Checkup routine
293 * \return 0 if successful, or 1 if the test failed
295 int mbedtls_hmac_drbg_self_test( int verbose
);
302 #endif /* hmac_drbg.h */