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