git.zerfleddert.de Git - proxmark3-svn/blob

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 /*

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 */

35 #ifndef MBEDTLS_CTR_DRBG_H

36 #define MBEDTLS_CTR_DRBG_H

38 #include "aes.h"

40 #if defined(MBEDTLS_THREADING_C)

41 #include "threading.h"

42 #endif

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. */

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). */

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 */

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

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

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

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

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

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

107 extern "C" {

108 #endif

109

110 /**

111 * \brief The CTR_DRBG context structure.

112 */

113 typedef struct mbedtls_ctr_drbg_context

114 {

     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 */

     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 }

139 mbedtls_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 */

 void 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 */

 int mbedtls_ctr_drbg_seed( mbedtls_ctr_drbg_context *ctx,

                    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 */

 void 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 */

 void 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 */

 void 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 */

 void 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 */

 int mbedtls_ctr_drbg_reseed( mbedtls_ctr_drbg_context *ctx,

                      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 */

 void mbedtls_ctr_drbg_update( mbedtls_ctr_drbg_context *ctx,

                       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 */

 int mbedtls_ctr_drbg_random_with_add( void *p_rng,

                               unsigned char *output, size_t output_len,

                               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 */

 int mbedtls_ctr_drbg_random( void *p_rng,

                      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 */

 int 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 */

 int 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 */

 int mbedtls_ctr_drbg_self_test( int verbose );

322

323 /* Internal functions (do not call directly) */

324 int mbedtls_ctr_drbg_seed_entropy_len( mbedtls_ctr_drbg_context *,

                                int (*)(void *, unsigned char *, size_t), void *,

                                const unsigned char *, size_t, size_t );

327

328 #ifdef __cplusplus

329 }

330 #endif

331

332 #endif /* ctr_drbg.h */