Daiki Kato / mbed-os-lychee

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Dependents:   mbed-os-example-blinky-gr-lychee GR-Boads_Camera_sample GR-Boards_Audio_Recoder GR-Boads_Camera_DisplayApp ... more

features/mbedtls/inc/mbedtls/ctr_drbg.h@0:f782d9c66c49, 2018-02-02 (annotated)

Committer:
dkato
Date:
Fri Feb 02 05:42:23 2018 +0000
Revision:
0:f782d9c66c49
mbed-os for GR-LYCHEE

Who changed what in which revision?

UserRevisionLine numberNew contents of line
dkato 0:f782d9c66c49 1 /**
dkato 0:f782d9c66c49 2 * \file ctr_drbg.h
dkato 0:f782d9c66c49 3 *
dkato 0:f782d9c66c49 4 * \brief CTR_DRBG based on AES-256 (NIST SP 800-90)
dkato 0:f782d9c66c49 5 *
dkato 0:f782d9c66c49 6 * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
dkato 0:f782d9c66c49 7 * SPDX-License-Identifier: Apache-2.0
dkato 0:f782d9c66c49 8 *
dkato 0:f782d9c66c49 9 * Licensed under the Apache License, Version 2.0 (the "License"); you may
dkato 0:f782d9c66c49 10 * not use this file except in compliance with the License.
dkato 0:f782d9c66c49 11 * You may obtain a copy of the License at
dkato 0:f782d9c66c49 12 *
dkato 0:f782d9c66c49 13 * http://www.apache.org/licenses/LICENSE-2.0
dkato 0:f782d9c66c49 14 *
dkato 0:f782d9c66c49 15 * Unless required by applicable law or agreed to in writing, software
dkato 0:f782d9c66c49 16 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
dkato 0:f782d9c66c49 17 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
dkato 0:f782d9c66c49 18 * See the License for the specific language governing permissions and
dkato 0:f782d9c66c49 19 * limitations under the License.
dkato 0:f782d9c66c49 20 *
dkato 0:f782d9c66c49 21 * This file is part of mbed TLS (https://tls.mbed.org)
dkato 0:f782d9c66c49 22 */
dkato 0:f782d9c66c49 23 #ifndef MBEDTLS_CTR_DRBG_H
dkato 0:f782d9c66c49 24 #define MBEDTLS_CTR_DRBG_H
dkato 0:f782d9c66c49 25
dkato 0:f782d9c66c49 26 #include "aes.h"
dkato 0:f782d9c66c49 27
dkato 0:f782d9c66c49 28 #if defined(MBEDTLS_THREADING_C)
dkato 0:f782d9c66c49 29 #include "mbedtls/threading.h"
dkato 0:f782d9c66c49 30 #endif
dkato 0:f782d9c66c49 31
dkato 0:f782d9c66c49 32 #define MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED -0x0034 /**< The entropy source failed. */
dkato 0:f782d9c66c49 33 #define MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG -0x0036 /**< Too many random requested in single call. */
dkato 0:f782d9c66c49 34 #define MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG -0x0038 /**< Input too large (Entropy + additional). */
dkato 0:f782d9c66c49 35 #define MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR -0x003A /**< Read/write error in file. */
dkato 0:f782d9c66c49 36
dkato 0:f782d9c66c49 37 #define MBEDTLS_CTR_DRBG_BLOCKSIZE 16 /**< Block size used by the cipher */
dkato 0:f782d9c66c49 38 #define MBEDTLS_CTR_DRBG_KEYSIZE 32 /**< Key size used by the cipher */
dkato 0:f782d9c66c49 39 #define MBEDTLS_CTR_DRBG_KEYBITS ( MBEDTLS_CTR_DRBG_KEYSIZE * 8 )
dkato 0:f782d9c66c49 40 #define MBEDTLS_CTR_DRBG_SEEDLEN ( MBEDTLS_CTR_DRBG_KEYSIZE + MBEDTLS_CTR_DRBG_BLOCKSIZE )
dkato 0:f782d9c66c49 41 /**< The seed length (counter + AES key) */
dkato 0:f782d9c66c49 42
dkato 0:f782d9c66c49 43 /**
dkato 0:f782d9c66c49 44 * \name SECTION: Module settings
dkato 0:f782d9c66c49 45 *
dkato 0:f782d9c66c49 46 * The configuration options you can set for this module are in this section.
dkato 0:f782d9c66c49 47 * Either change them in config.h or define them on the compiler command line.
dkato 0:f782d9c66c49 48 * \{
dkato 0:f782d9c66c49 49 */
dkato 0:f782d9c66c49 50
dkato 0:f782d9c66c49 51 #if !defined(MBEDTLS_CTR_DRBG_ENTROPY_LEN)
dkato 0:f782d9c66c49 52 #if defined(MBEDTLS_SHA512_C) && !defined(MBEDTLS_ENTROPY_FORCE_SHA256)
dkato 0:f782d9c66c49 53 #define MBEDTLS_CTR_DRBG_ENTROPY_LEN 48 /**< Amount of entropy used per seed by default (48 with SHA-512, 32 with SHA-256) */
dkato 0:f782d9c66c49 54 #else
dkato 0:f782d9c66c49 55 #define MBEDTLS_CTR_DRBG_ENTROPY_LEN 32 /**< Amount of entropy used per seed by default (48 with SHA-512, 32 with SHA-256) */
dkato 0:f782d9c66c49 56 #endif
dkato 0:f782d9c66c49 57 #endif
dkato 0:f782d9c66c49 58
dkato 0:f782d9c66c49 59 #if !defined(MBEDTLS_CTR_DRBG_RESEED_INTERVAL)
dkato 0:f782d9c66c49 60 #define MBEDTLS_CTR_DRBG_RESEED_INTERVAL 10000 /**< Interval before reseed is performed by default */
dkato 0:f782d9c66c49 61 #endif
dkato 0:f782d9c66c49 62
dkato 0:f782d9c66c49 63 #if !defined(MBEDTLS_CTR_DRBG_MAX_INPUT)
dkato 0:f782d9c66c49 64 #define MBEDTLS_CTR_DRBG_MAX_INPUT 256 /**< Maximum number of additional input bytes */
dkato 0:f782d9c66c49 65 #endif
dkato 0:f782d9c66c49 66
dkato 0:f782d9c66c49 67 #if !defined(MBEDTLS_CTR_DRBG_MAX_REQUEST)
dkato 0:f782d9c66c49 68 #define MBEDTLS_CTR_DRBG_MAX_REQUEST 1024 /**< Maximum number of requested bytes per call */
dkato 0:f782d9c66c49 69 #endif
dkato 0:f782d9c66c49 70
dkato 0:f782d9c66c49 71 #if !defined(MBEDTLS_CTR_DRBG_MAX_SEED_INPUT)
dkato 0:f782d9c66c49 72 #define MBEDTLS_CTR_DRBG_MAX_SEED_INPUT 384 /**< Maximum size of (re)seed buffer */
dkato 0:f782d9c66c49 73 #endif
dkato 0:f782d9c66c49 74
dkato 0:f782d9c66c49 75 /* \} name SECTION: Module settings */
dkato 0:f782d9c66c49 76
dkato 0:f782d9c66c49 77 #define MBEDTLS_CTR_DRBG_PR_OFF 0 /**< No prediction resistance */
dkato 0:f782d9c66c49 78 #define MBEDTLS_CTR_DRBG_PR_ON 1 /**< Prediction resistance enabled */
dkato 0:f782d9c66c49 79
dkato 0:f782d9c66c49 80 #ifdef __cplusplus
dkato 0:f782d9c66c49 81 extern "C" {
dkato 0:f782d9c66c49 82 #endif
dkato 0:f782d9c66c49 83
dkato 0:f782d9c66c49 84 /**
dkato 0:f782d9c66c49 85 * \brief CTR_DRBG context structure
dkato 0:f782d9c66c49 86 */
dkato 0:f782d9c66c49 87 typedef struct
dkato 0:f782d9c66c49 88 {
dkato 0:f782d9c66c49 89 unsigned char counter[16]; /*!< counter (V) */
dkato 0:f782d9c66c49 90 int reseed_counter; /*!< reseed counter */
dkato 0:f782d9c66c49 91 int prediction_resistance; /*!< enable prediction resistance (Automatic
dkato 0:f782d9c66c49 92 reseed before every random generation) */
dkato 0:f782d9c66c49 93 size_t entropy_len; /*!< amount of entropy grabbed on each
dkato 0:f782d9c66c49 94 (re)seed */
dkato 0:f782d9c66c49 95 int reseed_interval; /*!< reseed interval */
dkato 0:f782d9c66c49 96
dkato 0:f782d9c66c49 97 mbedtls_aes_context aes_ctx; /*!< AES context */
dkato 0:f782d9c66c49 98
dkato 0:f782d9c66c49 99 /*
dkato 0:f782d9c66c49 100 * Callbacks (Entropy)
dkato 0:f782d9c66c49 101 */
dkato 0:f782d9c66c49 102 int (*f_entropy)(void *, unsigned char *, size_t);
dkato 0:f782d9c66c49 103
dkato 0:f782d9c66c49 104 void *p_entropy; /*!< context for the entropy function */
dkato 0:f782d9c66c49 105
dkato 0:f782d9c66c49 106 #if defined(MBEDTLS_THREADING_C)
dkato 0:f782d9c66c49 107 mbedtls_threading_mutex_t mutex;
dkato 0:f782d9c66c49 108 #endif
dkato 0:f782d9c66c49 109 }
dkato 0:f782d9c66c49 110 mbedtls_ctr_drbg_context;
dkato 0:f782d9c66c49 111
dkato 0:f782d9c66c49 112 /**
dkato 0:f782d9c66c49 113 * \brief CTR_DRBG context initialization
dkato 0:f782d9c66c49 114 * Makes the context ready for mbedtls_ctr_drbg_seed() or
dkato 0:f782d9c66c49 115 * mbedtls_ctr_drbg_free().
dkato 0:f782d9c66c49 116 *
dkato 0:f782d9c66c49 117 * \param ctx CTR_DRBG context to be initialized
dkato 0:f782d9c66c49 118 */
dkato 0:f782d9c66c49 119 void mbedtls_ctr_drbg_init( mbedtls_ctr_drbg_context *ctx );
dkato 0:f782d9c66c49 120
dkato 0:f782d9c66c49 121 /**
dkato 0:f782d9c66c49 122 * \brief CTR_DRBG initial seeding
dkato 0:f782d9c66c49 123 * Seed and setup entropy source for future reseeds.
dkato 0:f782d9c66c49 124 *
dkato 0:f782d9c66c49 125 * Note: Personalization data can be provided in addition to the more generic
dkato 0:f782d9c66c49 126 * entropy source to make this instantiation as unique as possible.
dkato 0:f782d9c66c49 127 *
dkato 0:f782d9c66c49 128 * \param ctx CTR_DRBG context to be seeded
dkato 0:f782d9c66c49 129 * \param f_entropy Entropy callback (p_entropy, buffer to fill, buffer
dkato 0:f782d9c66c49 130 * length)
dkato 0:f782d9c66c49 131 * \param p_entropy Entropy context
dkato 0:f782d9c66c49 132 * \param custom Personalization data (Device specific identifiers)
dkato 0:f782d9c66c49 133 * (Can be NULL)
dkato 0:f782d9c66c49 134 * \param len Length of personalization data
dkato 0:f782d9c66c49 135 *
dkato 0:f782d9c66c49 136 * \return 0 if successful, or
dkato 0:f782d9c66c49 137 * MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED
dkato 0:f782d9c66c49 138 */
dkato 0:f782d9c66c49 139 int mbedtls_ctr_drbg_seed( mbedtls_ctr_drbg_context *ctx,
dkato 0:f782d9c66c49 140 int (*f_entropy)(void *, unsigned char *, size_t),
dkato 0:f782d9c66c49 141 void *p_entropy,
dkato 0:f782d9c66c49 142 const unsigned char *custom,
dkato 0:f782d9c66c49 143 size_t len );
dkato 0:f782d9c66c49 144
dkato 0:f782d9c66c49 145 /**
dkato 0:f782d9c66c49 146 * \brief Clear CTR_CRBG context data
dkato 0:f782d9c66c49 147 *
dkato 0:f782d9c66c49 148 * \param ctx CTR_DRBG context to clear
dkato 0:f782d9c66c49 149 */
dkato 0:f782d9c66c49 150 void mbedtls_ctr_drbg_free( mbedtls_ctr_drbg_context *ctx );
dkato 0:f782d9c66c49 151
dkato 0:f782d9c66c49 152 /**
dkato 0:f782d9c66c49 153 * \brief Enable / disable prediction resistance (Default: Off)
dkato 0:f782d9c66c49 154 *
dkato 0:f782d9c66c49 155 * Note: If enabled, entropy is used for ctx->entropy_len before each call!
dkato 0:f782d9c66c49 156 * Only use this if you have ample supply of good entropy!
dkato 0:f782d9c66c49 157 *
dkato 0:f782d9c66c49 158 * \param ctx CTR_DRBG context
dkato 0:f782d9c66c49 159 * \param resistance MBEDTLS_CTR_DRBG_PR_ON or MBEDTLS_CTR_DRBG_PR_OFF
dkato 0:f782d9c66c49 160 */
dkato 0:f782d9c66c49 161 void mbedtls_ctr_drbg_set_prediction_resistance( mbedtls_ctr_drbg_context *ctx,
dkato 0:f782d9c66c49 162 int resistance );
dkato 0:f782d9c66c49 163
dkato 0:f782d9c66c49 164 /**
dkato 0:f782d9c66c49 165 * \brief Set the amount of entropy grabbed on each (re)seed
dkato 0:f782d9c66c49 166 * (Default: MBEDTLS_CTR_DRBG_ENTROPY_LEN)
dkato 0:f782d9c66c49 167 *
dkato 0:f782d9c66c49 168 * \param ctx CTR_DRBG context
dkato 0:f782d9c66c49 169 * \param len Amount of entropy to grab
dkato 0:f782d9c66c49 170 */
dkato 0:f782d9c66c49 171 void mbedtls_ctr_drbg_set_entropy_len( mbedtls_ctr_drbg_context *ctx,
dkato 0:f782d9c66c49 172 size_t len );
dkato 0:f782d9c66c49 173
dkato 0:f782d9c66c49 174 /**
dkato 0:f782d9c66c49 175 * \brief Set the reseed interval
dkato 0:f782d9c66c49 176 * (Default: MBEDTLS_CTR_DRBG_RESEED_INTERVAL)
dkato 0:f782d9c66c49 177 *
dkato 0:f782d9c66c49 178 * \param ctx CTR_DRBG context
dkato 0:f782d9c66c49 179 * \param interval Reseed interval
dkato 0:f782d9c66c49 180 */
dkato 0:f782d9c66c49 181 void mbedtls_ctr_drbg_set_reseed_interval( mbedtls_ctr_drbg_context *ctx,
dkato 0:f782d9c66c49 182 int interval );
dkato 0:f782d9c66c49 183
dkato 0:f782d9c66c49 184 /**
dkato 0:f782d9c66c49 185 * \brief CTR_DRBG reseeding (extracts data from entropy source)
dkato 0:f782d9c66c49 186 *
dkato 0:f782d9c66c49 187 * \param ctx CTR_DRBG context
dkato 0:f782d9c66c49 188 * \param additional Additional data to add to state (Can be NULL)
dkato 0:f782d9c66c49 189 * \param len Length of additional data
dkato 0:f782d9c66c49 190 *
dkato 0:f782d9c66c49 191 * \return 0 if successful, or
dkato 0:f782d9c66c49 192 * MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED
dkato 0:f782d9c66c49 193 */
dkato 0:f782d9c66c49 194 int mbedtls_ctr_drbg_reseed( mbedtls_ctr_drbg_context *ctx,
dkato 0:f782d9c66c49 195 const unsigned char *additional, size_t len );
dkato 0:f782d9c66c49 196
dkato 0:f782d9c66c49 197 /**
dkato 0:f782d9c66c49 198 * \brief CTR_DRBG update state
dkato 0:f782d9c66c49 199 *
dkato 0:f782d9c66c49 200 * \param ctx CTR_DRBG context
dkato 0:f782d9c66c49 201 * \param additional Additional data to update state with
dkato 0:f782d9c66c49 202 * \param add_len Length of additional data
dkato 0:f782d9c66c49 203 *
dkato 0:f782d9c66c49 204 * \note If add_len is greater than MBEDTLS_CTR_DRBG_MAX_SEED_INPUT,
dkato 0:f782d9c66c49 205 * only the first MBEDTLS_CTR_DRBG_MAX_SEED_INPUT bytes are used,
dkato 0:f782d9c66c49 206 * the remaining ones are silently discarded.
dkato 0:f782d9c66c49 207 */
dkato 0:f782d9c66c49 208 void mbedtls_ctr_drbg_update( mbedtls_ctr_drbg_context *ctx,
dkato 0:f782d9c66c49 209 const unsigned char *additional, size_t add_len );
dkato 0:f782d9c66c49 210
dkato 0:f782d9c66c49 211 /**
dkato 0:f782d9c66c49 212 * \brief CTR_DRBG generate random with additional update input
dkato 0:f782d9c66c49 213 *
dkato 0:f782d9c66c49 214 * Note: Automatically reseeds if reseed_counter is reached.
dkato 0:f782d9c66c49 215 *
dkato 0:f782d9c66c49 216 * \param p_rng CTR_DRBG context
dkato 0:f782d9c66c49 217 * \param output Buffer to fill
dkato 0:f782d9c66c49 218 * \param output_len Length of the buffer
dkato 0:f782d9c66c49 219 * \param additional Additional data to update with (Can be NULL)
dkato 0:f782d9c66c49 220 * \param add_len Length of additional data
dkato 0:f782d9c66c49 221 *
dkato 0:f782d9c66c49 222 * \return 0 if successful, or
dkato 0:f782d9c66c49 223 * MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED, or
dkato 0:f782d9c66c49 224 * MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG
dkato 0:f782d9c66c49 225 */
dkato 0:f782d9c66c49 226 int mbedtls_ctr_drbg_random_with_add( void *p_rng,
dkato 0:f782d9c66c49 227 unsigned char *output, size_t output_len,
dkato 0:f782d9c66c49 228 const unsigned char *additional, size_t add_len );
dkato 0:f782d9c66c49 229
dkato 0:f782d9c66c49 230 /**
dkato 0:f782d9c66c49 231 * \brief CTR_DRBG generate random
dkato 0:f782d9c66c49 232 *
dkato 0:f782d9c66c49 233 * Note: Automatically reseeds if reseed_counter is reached.
dkato 0:f782d9c66c49 234 *
dkato 0:f782d9c66c49 235 * \param p_rng CTR_DRBG context
dkato 0:f782d9c66c49 236 * \param output Buffer to fill
dkato 0:f782d9c66c49 237 * \param output_len Length of the buffer
dkato 0:f782d9c66c49 238 *
dkato 0:f782d9c66c49 239 * \return 0 if successful, or
dkato 0:f782d9c66c49 240 * MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED, or
dkato 0:f782d9c66c49 241 * MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG
dkato 0:f782d9c66c49 242 */
dkato 0:f782d9c66c49 243 int mbedtls_ctr_drbg_random( void *p_rng,
dkato 0:f782d9c66c49 244 unsigned char *output, size_t output_len );
dkato 0:f782d9c66c49 245
dkato 0:f782d9c66c49 246 #if defined(MBEDTLS_FS_IO)
dkato 0:f782d9c66c49 247 /**
dkato 0:f782d9c66c49 248 * \brief Write a seed file
dkato 0:f782d9c66c49 249 *
dkato 0:f782d9c66c49 250 * \param ctx CTR_DRBG context
dkato 0:f782d9c66c49 251 * \param path Name of the file
dkato 0:f782d9c66c49 252 *
dkato 0:f782d9c66c49 253 * \return 0 if successful,
dkato 0:f782d9c66c49 254 * MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error, or
dkato 0:f782d9c66c49 255 * MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED
dkato 0:f782d9c66c49 256 */
dkato 0:f782d9c66c49 257 int mbedtls_ctr_drbg_write_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path );
dkato 0:f782d9c66c49 258
dkato 0:f782d9c66c49 259 /**
dkato 0:f782d9c66c49 260 * \brief Read and update a seed file. Seed is added to this
dkato 0:f782d9c66c49 261 * instance
dkato 0:f782d9c66c49 262 *
dkato 0:f782d9c66c49 263 * \param ctx CTR_DRBG context
dkato 0:f782d9c66c49 264 * \param path Name of the file
dkato 0:f782d9c66c49 265 *
dkato 0:f782d9c66c49 266 * \return 0 if successful,
dkato 0:f782d9c66c49 267 * MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error,
dkato 0:f782d9c66c49 268 * MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
dkato 0:f782d9c66c49 269 * MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG
dkato 0:f782d9c66c49 270 */
dkato 0:f782d9c66c49 271 int mbedtls_ctr_drbg_update_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path );
dkato 0:f782d9c66c49 272 #endif /* MBEDTLS_FS_IO */
dkato 0:f782d9c66c49 273
dkato 0:f782d9c66c49 274 /**
dkato 0:f782d9c66c49 275 * \brief Checkup routine
dkato 0:f782d9c66c49 276 *
dkato 0:f782d9c66c49 277 * \return 0 if successful, or 1 if the test failed
dkato 0:f782d9c66c49 278 */
dkato 0:f782d9c66c49 279 int mbedtls_ctr_drbg_self_test( int verbose );
dkato 0:f782d9c66c49 280
dkato 0:f782d9c66c49 281 /* Internal functions (do not call directly) */
dkato 0:f782d9c66c49 282 int mbedtls_ctr_drbg_seed_entropy_len( mbedtls_ctr_drbg_context *,
dkato 0:f782d9c66c49 283 int (*)(void *, unsigned char *, size_t), void *,
dkato 0:f782d9c66c49 284 const unsigned char *, size_t, size_t );
dkato 0:f782d9c66c49 285
dkato 0:f782d9c66c49 286 #ifdef __cplusplus
dkato 0:f782d9c66c49 287 }
dkato 0:f782d9c66c49 288 #endif
dkato 0:f782d9c66c49 289
dkato 0:f782d9c66c49 290 #endif /* ctr_drbg.h */