Doug Anson / mbedTLSLibrary

mbed TLS library

Dependents:   HTTPClient-SSL WS_SERVER

include/polarssl/entropy.h@0:137634ff4186, 2015-06-11 (annotated)

Committer:
ansond
Date:
Thu Jun 11 03:27:03 2015 +0000
Revision:
0:137634ff4186
initial commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
ansond 0:137634ff4186 1 /**
ansond 0:137634ff4186 2 * \file entropy.h
ansond 0:137634ff4186 3 *
ansond 0:137634ff4186 4 * \brief Entropy accumulator implementation
ansond 0:137634ff4186 5 *
ansond 0:137634ff4186 6 * Copyright (C) 2006-2014, ARM Limited, All Rights Reserved
ansond 0:137634ff4186 7 *
ansond 0:137634ff4186 8 * This file is part of mbed TLS (https://tls.mbed.org)
ansond 0:137634ff4186 9 *
ansond 0:137634ff4186 10 * This program is free software; you can redistribute it and/or modify
ansond 0:137634ff4186 11 * it under the terms of the GNU General Public License as published by
ansond 0:137634ff4186 12 * the Free Software Foundation; either version 2 of the License, or
ansond 0:137634ff4186 13 * (at your option) any later version.
ansond 0:137634ff4186 14 *
ansond 0:137634ff4186 15 * This program is distributed in the hope that it will be useful,
ansond 0:137634ff4186 16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
ansond 0:137634ff4186 17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
ansond 0:137634ff4186 18 * GNU General Public License for more details.
ansond 0:137634ff4186 19 *
ansond 0:137634ff4186 20 * You should have received a copy of the GNU General Public License along
ansond 0:137634ff4186 21 * with this program; if not, write to the Free Software Foundation, Inc.,
ansond 0:137634ff4186 22 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
ansond 0:137634ff4186 23 */
ansond 0:137634ff4186 24 #ifndef POLARSSL_ENTROPY_H
ansond 0:137634ff4186 25 #define POLARSSL_ENTROPY_H
ansond 0:137634ff4186 26
ansond 0:137634ff4186 27 #if !defined(POLARSSL_CONFIG_FILE)
ansond 0:137634ff4186 28 #include "config.h"
ansond 0:137634ff4186 29 #else
ansond 0:137634ff4186 30 #include POLARSSL_CONFIG_FILE
ansond 0:137634ff4186 31 #endif
ansond 0:137634ff4186 32
ansond 0:137634ff4186 33 #include <stddef.h>
ansond 0:137634ff4186 34
ansond 0:137634ff4186 35 #if defined(POLARSSL_SHA512_C) && !defined(POLARSSL_ENTROPY_FORCE_SHA256)
ansond 0:137634ff4186 36 #include "sha512.h"
ansond 0:137634ff4186 37 #define POLARSSL_ENTROPY_SHA512_ACCUMULATOR
ansond 0:137634ff4186 38 #else
ansond 0:137634ff4186 39 #if defined(POLARSSL_SHA256_C)
ansond 0:137634ff4186 40 #define POLARSSL_ENTROPY_SHA256_ACCUMULATOR
ansond 0:137634ff4186 41 #include "sha256.h"
ansond 0:137634ff4186 42 #endif
ansond 0:137634ff4186 43 #endif
ansond 0:137634ff4186 44
ansond 0:137634ff4186 45 #if defined(POLARSSL_THREADING_C)
ansond 0:137634ff4186 46 #include "threading.h"
ansond 0:137634ff4186 47 #endif
ansond 0:137634ff4186 48
ansond 0:137634ff4186 49 #if defined(POLARSSL_HAVEGE_C)
ansond 0:137634ff4186 50 #include "havege.h"
ansond 0:137634ff4186 51 #endif
ansond 0:137634ff4186 52
ansond 0:137634ff4186 53 #define POLARSSL_ERR_ENTROPY_SOURCE_FAILED -0x003C /**< Critical entropy source failure. */
ansond 0:137634ff4186 54 #define POLARSSL_ERR_ENTROPY_MAX_SOURCES -0x003E /**< No more sources can be added. */
ansond 0:137634ff4186 55 #define POLARSSL_ERR_ENTROPY_NO_SOURCES_DEFINED -0x0040 /**< No sources have been added to poll. */
ansond 0:137634ff4186 56 #define POLARSSL_ERR_ENTROPY_FILE_IO_ERROR -0x0058 /**< Read/write error in file. */
ansond 0:137634ff4186 57
ansond 0:137634ff4186 58 /**
ansond 0:137634ff4186 59 * \name SECTION: Module settings
ansond 0:137634ff4186 60 *
ansond 0:137634ff4186 61 * The configuration options you can set for this module are in this section.
ansond 0:137634ff4186 62 * Either change them in config.h or define them on the compiler command line.
ansond 0:137634ff4186 63 * \{
ansond 0:137634ff4186 64 */
ansond 0:137634ff4186 65
ansond 0:137634ff4186 66 #if !defined(ENTROPY_MAX_SOURCES)
ansond 0:137634ff4186 67 #define ENTROPY_MAX_SOURCES 20 /**< Maximum number of sources supported */
ansond 0:137634ff4186 68 #endif
ansond 0:137634ff4186 69
ansond 0:137634ff4186 70 #if !defined(ENTROPY_MAX_GATHER)
ansond 0:137634ff4186 71 #define ENTROPY_MAX_GATHER 128 /**< Maximum amount requested from entropy sources */
ansond 0:137634ff4186 72 #endif
ansond 0:137634ff4186 73
ansond 0:137634ff4186 74 /* \} name SECTION: Module settings */
ansond 0:137634ff4186 75
ansond 0:137634ff4186 76 #if defined(POLARSSL_ENTROPY_SHA512_ACCUMULATOR)
ansond 0:137634ff4186 77 #define ENTROPY_BLOCK_SIZE 64 /**< Block size of entropy accumulator (SHA-512) */
ansond 0:137634ff4186 78 #else
ansond 0:137634ff4186 79 #define ENTROPY_BLOCK_SIZE 32 /**< Block size of entropy accumulator (SHA-256) */
ansond 0:137634ff4186 80 #endif
ansond 0:137634ff4186 81
ansond 0:137634ff4186 82 #define ENTROPY_MAX_SEED_SIZE 1024 /**< Maximum size of seed we read from seed file */
ansond 0:137634ff4186 83 #define ENTROPY_SOURCE_MANUAL ENTROPY_MAX_SOURCES
ansond 0:137634ff4186 84
ansond 0:137634ff4186 85 #ifdef __cplusplus
ansond 0:137634ff4186 86 extern "C" {
ansond 0:137634ff4186 87 #endif
ansond 0:137634ff4186 88
ansond 0:137634ff4186 89 /**
ansond 0:137634ff4186 90 * \brief Entropy poll callback pointer
ansond 0:137634ff4186 91 *
ansond 0:137634ff4186 92 * \param data Callback-specific data pointer
ansond 0:137634ff4186 93 * \param output Data to fill
ansond 0:137634ff4186 94 * \param len Maximum size to provide
ansond 0:137634ff4186 95 * \param olen The actual amount of bytes put into the buffer (Can be 0)
ansond 0:137634ff4186 96 *
ansond 0:137634ff4186 97 * \return 0 if no critical failures occurred,
ansond 0:137634ff4186 98 * POLARSSL_ERR_ENTROPY_SOURCE_FAILED otherwise
ansond 0:137634ff4186 99 */
ansond 0:137634ff4186 100 typedef int (*f_source_ptr)(void *data, unsigned char *output, size_t len,
ansond 0:137634ff4186 101 size_t *olen);
ansond 0:137634ff4186 102
ansond 0:137634ff4186 103 /**
ansond 0:137634ff4186 104 * \brief Entropy source state
ansond 0:137634ff4186 105 */
ansond 0:137634ff4186 106 typedef struct
ansond 0:137634ff4186 107 {
ansond 0:137634ff4186 108 f_source_ptr f_source; /**< The entropy source callback */
ansond 0:137634ff4186 109 void * p_source; /**< The callback data pointer */
ansond 0:137634ff4186 110 size_t size; /**< Amount received */
ansond 0:137634ff4186 111 size_t threshold; /**< Minimum level required before release */
ansond 0:137634ff4186 112 }
ansond 0:137634ff4186 113 source_state;
ansond 0:137634ff4186 114
ansond 0:137634ff4186 115 /**
ansond 0:137634ff4186 116 * \brief Entropy context structure
ansond 0:137634ff4186 117 */
ansond 0:137634ff4186 118 typedef struct
ansond 0:137634ff4186 119 {
ansond 0:137634ff4186 120 #if defined(POLARSSL_ENTROPY_SHA512_ACCUMULATOR)
ansond 0:137634ff4186 121 sha512_context accumulator;
ansond 0:137634ff4186 122 #else
ansond 0:137634ff4186 123 sha256_context accumulator;
ansond 0:137634ff4186 124 #endif
ansond 0:137634ff4186 125 int source_count;
ansond 0:137634ff4186 126 source_state source[ENTROPY_MAX_SOURCES];
ansond 0:137634ff4186 127 #if defined(POLARSSL_HAVEGE_C)
ansond 0:137634ff4186 128 havege_state havege_data;
ansond 0:137634ff4186 129 #endif
ansond 0:137634ff4186 130 #if defined(POLARSSL_THREADING_C)
ansond 0:137634ff4186 131 threading_mutex_t mutex; /*!< mutex */
ansond 0:137634ff4186 132 #endif
ansond 0:137634ff4186 133 }
ansond 0:137634ff4186 134 entropy_context;
ansond 0:137634ff4186 135
ansond 0:137634ff4186 136 /**
ansond 0:137634ff4186 137 * \brief Initialize the context
ansond 0:137634ff4186 138 *
ansond 0:137634ff4186 139 * \param ctx Entropy context to initialize
ansond 0:137634ff4186 140 */
ansond 0:137634ff4186 141 void entropy_init( entropy_context *ctx );
ansond 0:137634ff4186 142
ansond 0:137634ff4186 143 /**
ansond 0:137634ff4186 144 * \brief Free the data in the context
ansond 0:137634ff4186 145 *
ansond 0:137634ff4186 146 * \param ctx Entropy context to free
ansond 0:137634ff4186 147 */
ansond 0:137634ff4186 148 void entropy_free( entropy_context *ctx );
ansond 0:137634ff4186 149
ansond 0:137634ff4186 150 /**
ansond 0:137634ff4186 151 * \brief Adds an entropy source to poll
ansond 0:137634ff4186 152 * (Thread-safe if POLARSSL_THREADING_C is enabled)
ansond 0:137634ff4186 153 *
ansond 0:137634ff4186 154 * \param ctx Entropy context
ansond 0:137634ff4186 155 * \param f_source Entropy function
ansond 0:137634ff4186 156 * \param p_source Function data
ansond 0:137634ff4186 157 * \param threshold Minimum required from source before entropy is released
ansond 0:137634ff4186 158 * ( with entropy_func() )
ansond 0:137634ff4186 159 *
ansond 0:137634ff4186 160 * \return 0 if successful or POLARSSL_ERR_ENTROPY_MAX_SOURCES
ansond 0:137634ff4186 161 */
ansond 0:137634ff4186 162 int entropy_add_source( entropy_context *ctx,
ansond 0:137634ff4186 163 f_source_ptr f_source, void *p_source,
ansond 0:137634ff4186 164 size_t threshold );
ansond 0:137634ff4186 165
ansond 0:137634ff4186 166 /**
ansond 0:137634ff4186 167 * \brief Trigger an extra gather poll for the accumulator
ansond 0:137634ff4186 168 * (Thread-safe if POLARSSL_THREADING_C is enabled)
ansond 0:137634ff4186 169 *
ansond 0:137634ff4186 170 * \param ctx Entropy context
ansond 0:137634ff4186 171 *
ansond 0:137634ff4186 172 * \return 0 if successful, or POLARSSL_ERR_ENTROPY_SOURCE_FAILED
ansond 0:137634ff4186 173 */
ansond 0:137634ff4186 174 int entropy_gather( entropy_context *ctx );
ansond 0:137634ff4186 175
ansond 0:137634ff4186 176 /**
ansond 0:137634ff4186 177 * \brief Retrieve entropy from the accumulator
ansond 0:137634ff4186 178 * (Maximum length: ENTROPY_BLOCK_SIZE)
ansond 0:137634ff4186 179 * (Thread-safe if POLARSSL_THREADING_C is enabled)
ansond 0:137634ff4186 180 *
ansond 0:137634ff4186 181 * \param data Entropy context
ansond 0:137634ff4186 182 * \param output Buffer to fill
ansond 0:137634ff4186 183 * \param len Number of bytes desired, must be at most ENTROPY_BLOCK_SIZE
ansond 0:137634ff4186 184 *
ansond 0:137634ff4186 185 * \return 0 if successful, or POLARSSL_ERR_ENTROPY_SOURCE_FAILED
ansond 0:137634ff4186 186 */
ansond 0:137634ff4186 187 int entropy_func( void *data, unsigned char *output, size_t len );
ansond 0:137634ff4186 188
ansond 0:137634ff4186 189 /**
ansond 0:137634ff4186 190 * \brief Add data to the accumulator manually
ansond 0:137634ff4186 191 * (Thread-safe if POLARSSL_THREADING_C is enabled)
ansond 0:137634ff4186 192 *
ansond 0:137634ff4186 193 * \param ctx Entropy context
ansond 0:137634ff4186 194 * \param data Data to add
ansond 0:137634ff4186 195 * \param len Length of data
ansond 0:137634ff4186 196 *
ansond 0:137634ff4186 197 * \return 0 if successful
ansond 0:137634ff4186 198 */
ansond 0:137634ff4186 199 int entropy_update_manual( entropy_context *ctx,
ansond 0:137634ff4186 200 const unsigned char *data, size_t len );
ansond 0:137634ff4186 201
ansond 0:137634ff4186 202 #if defined(POLARSSL_FS_IO)
ansond 0:137634ff4186 203 /**
ansond 0:137634ff4186 204 * \brief Write a seed file
ansond 0:137634ff4186 205 *
ansond 0:137634ff4186 206 * \param ctx Entropy context
ansond 0:137634ff4186 207 * \param path Name of the file
ansond 0:137634ff4186 208 *
ansond 0:137634ff4186 209 * \return 0 if successful,
ansond 0:137634ff4186 210 * POLARSSL_ERR_ENTROPY_FILE_IO_ERROR on file error, or
ansond 0:137634ff4186 211 * POLARSSL_ERR_ENTROPY_SOURCE_FAILED
ansond 0:137634ff4186 212 */
ansond 0:137634ff4186 213 int entropy_write_seed_file( entropy_context *ctx, const char *path );
ansond 0:137634ff4186 214
ansond 0:137634ff4186 215 /**
ansond 0:137634ff4186 216 * \brief Read and update a seed file. Seed is added to this
ansond 0:137634ff4186 217 * instance. No more than ENTROPY_MAX_SEED_SIZE bytes are
ansond 0:137634ff4186 218 * read from the seed file. The rest is ignored.
ansond 0:137634ff4186 219 *
ansond 0:137634ff4186 220 * \param ctx Entropy context
ansond 0:137634ff4186 221 * \param path Name of the file
ansond 0:137634ff4186 222 *
ansond 0:137634ff4186 223 * \return 0 if successful,
ansond 0:137634ff4186 224 * POLARSSL_ERR_ENTROPY_FILE_IO_ERROR on file error,
ansond 0:137634ff4186 225 * POLARSSL_ERR_ENTROPY_SOURCE_FAILED
ansond 0:137634ff4186 226 */
ansond 0:137634ff4186 227 int entropy_update_seed_file( entropy_context *ctx, const char *path );
ansond 0:137634ff4186 228 #endif /* POLARSSL_FS_IO */
ansond 0:137634ff4186 229
ansond 0:137634ff4186 230 #if defined(POLARSSL_SELF_TEST)
ansond 0:137634ff4186 231 /**
ansond 0:137634ff4186 232 * \brief Checkup routine
ansond 0:137634ff4186 233 *
ansond 0:137634ff4186 234 * \return 0 if successful, or 1 if a test failed
ansond 0:137634ff4186 235 */
ansond 0:137634ff4186 236 int entropy_self_test( int verbose );
ansond 0:137634ff4186 237 #endif /* POLARSSL_SELF_TEST */
ansond 0:137634ff4186 238
ansond 0:137634ff4186 239 #ifdef __cplusplus
ansond 0:137634ff4186 240 }
ansond 0:137634ff4186 241 #endif
ansond 0:137634ff4186 242
ansond 0:137634ff4186 243 #endif /* entropy.h */
ansond 0:137634ff4186 244