reactos/sdk/include/reactos/libs/mbedtls/entropy.h

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