Maxim nexpaq / nexpaq_dev

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.

features/mbedtls/inc/mbedtls/entropy.h@0:6c56fb4bc5f0, 2016-11-04 (annotated)

Committer:
nexpaq
Date:
Fri Nov 04 20:27:58 2016 +0000
Revision:
0:6c56fb4bc5f0
Moving to library for sharing updates

Who changed what in which revision?

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