BA / Mbed OS BaBoRo_test2

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.

mbed-os/features/mbedtls/inc/mbedtls/entropy.h@0:02dd72d1d465, 2018-04-24 (annotated)

Committer:
borlanic
Date:
Tue Apr 24 11:45:18 2018 +0000
Revision:
0:02dd72d1d465
BaBoRo_test2 - backup 1

Who changed what in which revision?

UserRevisionLine numberNew contents of line
borlanic 0:02dd72d1d465 1 /**
borlanic 0:02dd72d1d465 2 * \file entropy.h
borlanic 0:02dd72d1d465 3 *
borlanic 0:02dd72d1d465 4 * \brief Entropy accumulator implementation
borlanic 0:02dd72d1d465 5 */
borlanic 0:02dd72d1d465 6 /*
borlanic 0:02dd72d1d465 7 * Copyright (C) 2006-2016, ARM Limited, All Rights Reserved
borlanic 0:02dd72d1d465 8 * SPDX-License-Identifier: Apache-2.0
borlanic 0:02dd72d1d465 9 *
borlanic 0:02dd72d1d465 10 * Licensed under the Apache License, Version 2.0 (the "License"); you may
borlanic 0:02dd72d1d465 11 * not use this file except in compliance with the License.
borlanic 0:02dd72d1d465 12 * You may obtain a copy of the License at
borlanic 0:02dd72d1d465 13 *
borlanic 0:02dd72d1d465 14 * http://www.apache.org/licenses/LICENSE-2.0
borlanic 0:02dd72d1d465 15 *
borlanic 0:02dd72d1d465 16 * Unless required by applicable law or agreed to in writing, software
borlanic 0:02dd72d1d465 17 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
borlanic 0:02dd72d1d465 18 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
borlanic 0:02dd72d1d465 19 * See the License for the specific language governing permissions and
borlanic 0:02dd72d1d465 20 * limitations under the License.
borlanic 0:02dd72d1d465 21 *
borlanic 0:02dd72d1d465 22 * This file is part of mbed TLS (https://tls.mbed.org)
borlanic 0:02dd72d1d465 23 */
borlanic 0:02dd72d1d465 24 #ifndef MBEDTLS_ENTROPY_H
borlanic 0:02dd72d1d465 25 #define MBEDTLS_ENTROPY_H
borlanic 0:02dd72d1d465 26
borlanic 0:02dd72d1d465 27 #if !defined(MBEDTLS_CONFIG_FILE)
borlanic 0:02dd72d1d465 28 #include "config.h"
borlanic 0:02dd72d1d465 29 #else
borlanic 0:02dd72d1d465 30 #include MBEDTLS_CONFIG_FILE
borlanic 0:02dd72d1d465 31 #endif
borlanic 0:02dd72d1d465 32
borlanic 0:02dd72d1d465 33 #include <stddef.h>
borlanic 0:02dd72d1d465 34
borlanic 0:02dd72d1d465 35 #if defined(MBEDTLS_SHA512_C) && !defined(MBEDTLS_ENTROPY_FORCE_SHA256)
borlanic 0:02dd72d1d465 36 #include "sha512.h"
borlanic 0:02dd72d1d465 37 #define MBEDTLS_ENTROPY_SHA512_ACCUMULATOR
borlanic 0:02dd72d1d465 38 #else
borlanic 0:02dd72d1d465 39 #if defined(MBEDTLS_SHA256_C)
borlanic 0:02dd72d1d465 40 #define MBEDTLS_ENTROPY_SHA256_ACCUMULATOR
borlanic 0:02dd72d1d465 41 #include "sha256.h"
borlanic 0:02dd72d1d465 42 #endif
borlanic 0:02dd72d1d465 43 #endif
borlanic 0:02dd72d1d465 44
borlanic 0:02dd72d1d465 45 #if defined(MBEDTLS_THREADING_C)
borlanic 0:02dd72d1d465 46 #include "threading.h"
borlanic 0:02dd72d1d465 47 #endif
borlanic 0:02dd72d1d465 48
borlanic 0:02dd72d1d465 49 #if defined(MBEDTLS_HAVEGE_C)
borlanic 0:02dd72d1d465 50 #include "havege.h"
borlanic 0:02dd72d1d465 51 #endif
borlanic 0:02dd72d1d465 52
borlanic 0:02dd72d1d465 53 #define MBEDTLS_ERR_ENTROPY_SOURCE_FAILED -0x003C /**< Critical entropy source failure. */
borlanic 0:02dd72d1d465 54 #define MBEDTLS_ERR_ENTROPY_MAX_SOURCES -0x003E /**< No more sources can be added. */
borlanic 0:02dd72d1d465 55 #define MBEDTLS_ERR_ENTROPY_NO_SOURCES_DEFINED -0x0040 /**< No sources have been added to poll. */
borlanic 0:02dd72d1d465 56 #define MBEDTLS_ERR_ENTROPY_NO_STRONG_SOURCE -0x003D /**< No strong sources have been added to poll. */
borlanic 0:02dd72d1d465 57 #define MBEDTLS_ERR_ENTROPY_FILE_IO_ERROR -0x003F /**< Read/write error in file. */
borlanic 0:02dd72d1d465 58
borlanic 0:02dd72d1d465 59 /**
borlanic 0:02dd72d1d465 60 * \name SECTION: Module settings
borlanic 0:02dd72d1d465 61 *
borlanic 0:02dd72d1d465 62 * The configuration options you can set for this module are in this section.
borlanic 0:02dd72d1d465 63 * Either change them in config.h or define them on the compiler command line.
borlanic 0:02dd72d1d465 64 * \{
borlanic 0:02dd72d1d465 65 */
borlanic 0:02dd72d1d465 66
borlanic 0:02dd72d1d465 67 #if !defined(MBEDTLS_ENTROPY_MAX_SOURCES)
borlanic 0:02dd72d1d465 68 #define MBEDTLS_ENTROPY_MAX_SOURCES 20 /**< Maximum number of sources supported */
borlanic 0:02dd72d1d465 69 #endif
borlanic 0:02dd72d1d465 70
borlanic 0:02dd72d1d465 71 #if !defined(MBEDTLS_ENTROPY_MAX_GATHER)
borlanic 0:02dd72d1d465 72 #define MBEDTLS_ENTROPY_MAX_GATHER 128 /**< Maximum amount requested from entropy sources */
borlanic 0:02dd72d1d465 73 #endif
borlanic 0:02dd72d1d465 74
borlanic 0:02dd72d1d465 75 /* \} name SECTION: Module settings */
borlanic 0:02dd72d1d465 76
borlanic 0:02dd72d1d465 77 #if defined(MBEDTLS_ENTROPY_SHA512_ACCUMULATOR)
borlanic 0:02dd72d1d465 78 #define MBEDTLS_ENTROPY_BLOCK_SIZE 64 /**< Block size of entropy accumulator (SHA-512) */
borlanic 0:02dd72d1d465 79 #else
borlanic 0:02dd72d1d465 80 #define MBEDTLS_ENTROPY_BLOCK_SIZE 32 /**< Block size of entropy accumulator (SHA-256) */
borlanic 0:02dd72d1d465 81 #endif
borlanic 0:02dd72d1d465 82
borlanic 0:02dd72d1d465 83 #define MBEDTLS_ENTROPY_MAX_SEED_SIZE 1024 /**< Maximum size of seed we read from seed file */
borlanic 0:02dd72d1d465 84 #define MBEDTLS_ENTROPY_SOURCE_MANUAL MBEDTLS_ENTROPY_MAX_SOURCES
borlanic 0:02dd72d1d465 85
borlanic 0:02dd72d1d465 86 #define MBEDTLS_ENTROPY_SOURCE_STRONG 1 /**< Entropy source is strong */
borlanic 0:02dd72d1d465 87 #define MBEDTLS_ENTROPY_SOURCE_WEAK 0 /**< Entropy source is weak */
borlanic 0:02dd72d1d465 88
borlanic 0:02dd72d1d465 89 #ifdef __cplusplus
borlanic 0:02dd72d1d465 90 extern "C" {
borlanic 0:02dd72d1d465 91 #endif
borlanic 0:02dd72d1d465 92
borlanic 0:02dd72d1d465 93 /**
borlanic 0:02dd72d1d465 94 * \brief Entropy poll callback pointer
borlanic 0:02dd72d1d465 95 *
borlanic 0:02dd72d1d465 96 * \param data Callback-specific data pointer
borlanic 0:02dd72d1d465 97 * \param output Data to fill
borlanic 0:02dd72d1d465 98 * \param len Maximum size to provide
borlanic 0:02dd72d1d465 99 * \param olen The actual amount of bytes put into the buffer (Can be 0)
borlanic 0:02dd72d1d465 100 *
borlanic 0:02dd72d1d465 101 * \return 0 if no critical failures occurred,
borlanic 0:02dd72d1d465 102 * MBEDTLS_ERR_ENTROPY_SOURCE_FAILED otherwise
borlanic 0:02dd72d1d465 103 */
borlanic 0:02dd72d1d465 104 typedef int (*mbedtls_entropy_f_source_ptr)(void *data, unsigned char *output, size_t len,
borlanic 0:02dd72d1d465 105 size_t *olen);
borlanic 0:02dd72d1d465 106
borlanic 0:02dd72d1d465 107 /**
borlanic 0:02dd72d1d465 108 * \brief Entropy source state
borlanic 0:02dd72d1d465 109 */
borlanic 0:02dd72d1d465 110 typedef struct
borlanic 0:02dd72d1d465 111 {
borlanic 0:02dd72d1d465 112 mbedtls_entropy_f_source_ptr f_source; /**< The entropy source callback */
borlanic 0:02dd72d1d465 113 void * p_source; /**< The callback data pointer */
borlanic 0:02dd72d1d465 114 size_t size; /**< Amount received in bytes */
borlanic 0:02dd72d1d465 115 size_t threshold; /**< Minimum bytes required before release */
borlanic 0:02dd72d1d465 116 int strong; /**< Is the source strong? */
borlanic 0:02dd72d1d465 117 }
borlanic 0:02dd72d1d465 118 mbedtls_entropy_source_state;
borlanic 0:02dd72d1d465 119
borlanic 0:02dd72d1d465 120 /**
borlanic 0:02dd72d1d465 121 * \brief Entropy context structure
borlanic 0:02dd72d1d465 122 */
borlanic 0:02dd72d1d465 123 typedef struct
borlanic 0:02dd72d1d465 124 {
borlanic 0:02dd72d1d465 125 int accumulator_started;
borlanic 0:02dd72d1d465 126 #if defined(MBEDTLS_ENTROPY_SHA512_ACCUMULATOR)
borlanic 0:02dd72d1d465 127 mbedtls_sha512_context accumulator;
borlanic 0:02dd72d1d465 128 #else
borlanic 0:02dd72d1d465 129 mbedtls_sha256_context accumulator;
borlanic 0:02dd72d1d465 130 #endif
borlanic 0:02dd72d1d465 131 int source_count;
borlanic 0:02dd72d1d465 132 mbedtls_entropy_source_state source[MBEDTLS_ENTROPY_MAX_SOURCES];
borlanic 0:02dd72d1d465 133 #if defined(MBEDTLS_HAVEGE_C)
borlanic 0:02dd72d1d465 134 mbedtls_havege_state havege_data;
borlanic 0:02dd72d1d465 135 #endif
borlanic 0:02dd72d1d465 136 #if defined(MBEDTLS_THREADING_C)
borlanic 0:02dd72d1d465 137 mbedtls_threading_mutex_t mutex; /*!< mutex */
borlanic 0:02dd72d1d465 138 #endif
borlanic 0:02dd72d1d465 139 #if defined(MBEDTLS_ENTROPY_NV_SEED)
borlanic 0:02dd72d1d465 140 int initial_entropy_run;
borlanic 0:02dd72d1d465 141 #endif
borlanic 0:02dd72d1d465 142 }
borlanic 0:02dd72d1d465 143 mbedtls_entropy_context;
borlanic 0:02dd72d1d465 144
borlanic 0:02dd72d1d465 145 /**
borlanic 0:02dd72d1d465 146 * \brief Initialize the context
borlanic 0:02dd72d1d465 147 *
borlanic 0:02dd72d1d465 148 * \param ctx Entropy context to initialize
borlanic 0:02dd72d1d465 149 */
borlanic 0:02dd72d1d465 150 void mbedtls_entropy_init( mbedtls_entropy_context *ctx );
borlanic 0:02dd72d1d465 151
borlanic 0:02dd72d1d465 152 /**
borlanic 0:02dd72d1d465 153 * \brief Free the data in the context
borlanic 0:02dd72d1d465 154 *
borlanic 0:02dd72d1d465 155 * \param ctx Entropy context to free
borlanic 0:02dd72d1d465 156 */
borlanic 0:02dd72d1d465 157 void mbedtls_entropy_free( mbedtls_entropy_context *ctx );
borlanic 0:02dd72d1d465 158
borlanic 0:02dd72d1d465 159 /**
borlanic 0:02dd72d1d465 160 * \brief Adds an entropy source to poll
borlanic 0:02dd72d1d465 161 * (Thread-safe if MBEDTLS_THREADING_C is enabled)
borlanic 0:02dd72d1d465 162 *
borlanic 0:02dd72d1d465 163 * \param ctx Entropy context
borlanic 0:02dd72d1d465 164 * \param f_source Entropy function
borlanic 0:02dd72d1d465 165 * \param p_source Function data
borlanic 0:02dd72d1d465 166 * \param threshold Minimum required from source before entropy is released
borlanic 0:02dd72d1d465 167 * ( with mbedtls_entropy_func() ) (in bytes)
borlanic 0:02dd72d1d465 168 * \param strong MBEDTLS_ENTROPY_SOURCE_STRONG or
borlanic 0:02dd72d1d465 169 * MBEDTSL_ENTROPY_SOURCE_WEAK.
borlanic 0:02dd72d1d465 170 * At least one strong source needs to be added.
borlanic 0:02dd72d1d465 171 * Weaker sources (such as the cycle counter) can be used as
borlanic 0:02dd72d1d465 172 * a complement.
borlanic 0:02dd72d1d465 173 *
borlanic 0:02dd72d1d465 174 * \return 0 if successful or MBEDTLS_ERR_ENTROPY_MAX_SOURCES
borlanic 0:02dd72d1d465 175 */
borlanic 0:02dd72d1d465 176 int mbedtls_entropy_add_source( mbedtls_entropy_context *ctx,
borlanic 0:02dd72d1d465 177 mbedtls_entropy_f_source_ptr f_source, void *p_source,
borlanic 0:02dd72d1d465 178 size_t threshold, int strong );
borlanic 0:02dd72d1d465 179
borlanic 0:02dd72d1d465 180 /**
borlanic 0:02dd72d1d465 181 * \brief Trigger an extra gather poll for the accumulator
borlanic 0:02dd72d1d465 182 * (Thread-safe if MBEDTLS_THREADING_C is enabled)
borlanic 0:02dd72d1d465 183 *
borlanic 0:02dd72d1d465 184 * \param ctx Entropy context
borlanic 0:02dd72d1d465 185 *
borlanic 0:02dd72d1d465 186 * \return 0 if successful, or MBEDTLS_ERR_ENTROPY_SOURCE_FAILED
borlanic 0:02dd72d1d465 187 */
borlanic 0:02dd72d1d465 188 int mbedtls_entropy_gather( mbedtls_entropy_context *ctx );
borlanic 0:02dd72d1d465 189
borlanic 0:02dd72d1d465 190 /**
borlanic 0:02dd72d1d465 191 * \brief Retrieve entropy from the accumulator
borlanic 0:02dd72d1d465 192 * (Maximum length: MBEDTLS_ENTROPY_BLOCK_SIZE)
borlanic 0:02dd72d1d465 193 * (Thread-safe if MBEDTLS_THREADING_C is enabled)
borlanic 0:02dd72d1d465 194 *
borlanic 0:02dd72d1d465 195 * \param data Entropy context
borlanic 0:02dd72d1d465 196 * \param output Buffer to fill
borlanic 0:02dd72d1d465 197 * \param len Number of bytes desired, must be at most MBEDTLS_ENTROPY_BLOCK_SIZE
borlanic 0:02dd72d1d465 198 *
borlanic 0:02dd72d1d465 199 * \return 0 if successful, or MBEDTLS_ERR_ENTROPY_SOURCE_FAILED
borlanic 0:02dd72d1d465 200 */
borlanic 0:02dd72d1d465 201 int mbedtls_entropy_func( void *data, unsigned char *output, size_t len );
borlanic 0:02dd72d1d465 202
borlanic 0:02dd72d1d465 203 /**
borlanic 0:02dd72d1d465 204 * \brief Add data to the accumulator manually
borlanic 0:02dd72d1d465 205 * (Thread-safe if MBEDTLS_THREADING_C is enabled)
borlanic 0:02dd72d1d465 206 *
borlanic 0:02dd72d1d465 207 * \param ctx Entropy context
borlanic 0:02dd72d1d465 208 * \param data Data to add
borlanic 0:02dd72d1d465 209 * \param len Length of data
borlanic 0:02dd72d1d465 210 *
borlanic 0:02dd72d1d465 211 * \return 0 if successful
borlanic 0:02dd72d1d465 212 */
borlanic 0:02dd72d1d465 213 int mbedtls_entropy_update_manual( mbedtls_entropy_context *ctx,
borlanic 0:02dd72d1d465 214 const unsigned char *data, size_t len );
borlanic 0:02dd72d1d465 215
borlanic 0:02dd72d1d465 216 #if defined(MBEDTLS_ENTROPY_NV_SEED)
borlanic 0:02dd72d1d465 217 /**
borlanic 0:02dd72d1d465 218 * \brief Trigger an update of the seed file in NV by using the
borlanic 0:02dd72d1d465 219 * current entropy pool.
borlanic 0:02dd72d1d465 220 *
borlanic 0:02dd72d1d465 221 * \param ctx Entropy context
borlanic 0:02dd72d1d465 222 *
borlanic 0:02dd72d1d465 223 * \return 0 if successful
borlanic 0:02dd72d1d465 224 */
borlanic 0:02dd72d1d465 225 int mbedtls_entropy_update_nv_seed( mbedtls_entropy_context *ctx );
borlanic 0:02dd72d1d465 226 #endif /* MBEDTLS_ENTROPY_NV_SEED */
borlanic 0:02dd72d1d465 227
borlanic 0:02dd72d1d465 228 #if defined(MBEDTLS_FS_IO)
borlanic 0:02dd72d1d465 229 /**
borlanic 0:02dd72d1d465 230 * \brief Write a seed file
borlanic 0:02dd72d1d465 231 *
borlanic 0:02dd72d1d465 232 * \param ctx Entropy context
borlanic 0:02dd72d1d465 233 * \param path Name of the file
borlanic 0:02dd72d1d465 234 *
borlanic 0:02dd72d1d465 235 * \return 0 if successful,
borlanic 0:02dd72d1d465 236 * MBEDTLS_ERR_ENTROPY_FILE_IO_ERROR on file error, or
borlanic 0:02dd72d1d465 237 * MBEDTLS_ERR_ENTROPY_SOURCE_FAILED
borlanic 0:02dd72d1d465 238 */
borlanic 0:02dd72d1d465 239 int mbedtls_entropy_write_seed_file( mbedtls_entropy_context *ctx, const char *path );
borlanic 0:02dd72d1d465 240
borlanic 0:02dd72d1d465 241 /**
borlanic 0:02dd72d1d465 242 * \brief Read and update a seed file. Seed is added to this
borlanic 0:02dd72d1d465 243 * instance. No more than MBEDTLS_ENTROPY_MAX_SEED_SIZE bytes are
borlanic 0:02dd72d1d465 244 * read from the seed file. The rest is ignored.
borlanic 0:02dd72d1d465 245 *
borlanic 0:02dd72d1d465 246 * \param ctx Entropy context
borlanic 0:02dd72d1d465 247 * \param path Name of the file
borlanic 0:02dd72d1d465 248 *
borlanic 0:02dd72d1d465 249 * \return 0 if successful,
borlanic 0:02dd72d1d465 250 * MBEDTLS_ERR_ENTROPY_FILE_IO_ERROR on file error,
borlanic 0:02dd72d1d465 251 * MBEDTLS_ERR_ENTROPY_SOURCE_FAILED
borlanic 0:02dd72d1d465 252 */
borlanic 0:02dd72d1d465 253 int mbedtls_entropy_update_seed_file( mbedtls_entropy_context *ctx, const char *path );
borlanic 0:02dd72d1d465 254 #endif /* MBEDTLS_FS_IO */
borlanic 0:02dd72d1d465 255
borlanic 0:02dd72d1d465 256 #if defined(MBEDTLS_SELF_TEST)
borlanic 0:02dd72d1d465 257 /**
borlanic 0:02dd72d1d465 258 * \brief Checkup routine
borlanic 0:02dd72d1d465 259 *
borlanic 0:02dd72d1d465 260 * This module self-test also calls the entropy self-test,
borlanic 0:02dd72d1d465 261 * mbedtls_entropy_source_self_test();
borlanic 0:02dd72d1d465 262 *
borlanic 0:02dd72d1d465 263 * \return 0 if successful, or 1 if a test failed
borlanic 0:02dd72d1d465 264 */
borlanic 0:02dd72d1d465 265 int mbedtls_entropy_self_test( int verbose );
borlanic 0:02dd72d1d465 266
borlanic 0:02dd72d1d465 267 #if defined(MBEDTLS_ENTROPY_HARDWARE_ALT)
borlanic 0:02dd72d1d465 268 /**
borlanic 0:02dd72d1d465 269 * \brief Checkup routine
borlanic 0:02dd72d1d465 270 *
borlanic 0:02dd72d1d465 271 * Verifies the integrity of the hardware entropy source
borlanic 0:02dd72d1d465 272 * provided by the function 'mbedtls_hardware_poll()'.
borlanic 0:02dd72d1d465 273 *
borlanic 0:02dd72d1d465 274 * Note this is the only hardware entropy source that is known
borlanic 0:02dd72d1d465 275 * at link time, and other entropy sources configured
borlanic 0:02dd72d1d465 276 * dynamically at runtime by the function
borlanic 0:02dd72d1d465 277 * mbedtls_entropy_add_source() will not be tested.
borlanic 0:02dd72d1d465 278 *
borlanic 0:02dd72d1d465 279 * \return 0 if successful, or 1 if a test failed
borlanic 0:02dd72d1d465 280 */
borlanic 0:02dd72d1d465 281 int mbedtls_entropy_source_self_test( int verbose );
borlanic 0:02dd72d1d465 282 #endif /* MBEDTLS_ENTROPY_HARDWARE_ALT */
borlanic 0:02dd72d1d465 283 #endif /* MBEDTLS_SELF_TEST */
borlanic 0:02dd72d1d465 284
borlanic 0:02dd72d1d465 285 #ifdef __cplusplus
borlanic 0:02dd72d1d465 286 }
borlanic 0:02dd72d1d465 287 #endif
borlanic 0:02dd72d1d465 288
borlanic 0:02dd72d1d465 289 #endif /* entropy.h */