git.sur5r.net Git - freertos/blob - FreeRTOS-Labs/Source/mbedtls/include/mbedtls/entropy.h

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