common/mbedtls/entropy.h

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