mbedtls/private/entropy.h

0001 /**
0002  * \file entropy.h
0003  *
0004  * \brief Entropy accumulator implementation
0005  */
0006 /*
0007  *  Copyright The Mbed TLS Contributors
0008  *  SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
0009  */
0010 #ifndef MBEDTLS_ENTROPY_H
0011 #define MBEDTLS_ENTROPY_H
0012 #include "mbedtls/private_access.h"
0013 #include "mbedtls/psa_util.h"
0014
0015 #include "tf-psa-crypto/build_info.h"
0016
0017 #include <stddef.h>
0018
0019 #include "mbedtls/md.h"
0020
0021 #define MBEDTLS_ENTROPY_BLOCK_SIZE PSA_HASH_LENGTH(MBEDTLS_PSA_CRYPTO_RNG_HASH)
0022 /* For MBEDTLS_ENTROPY_MD convert PSA_ALG_SHA_256/512 -> MBEDTLS_MD_SHA256/512 */
0023 #define MBEDTLS_ENTROPY_MD (mbedtls_md_type_from_psa_alg(MBEDTLS_PSA_CRYPTO_RNG_HASH))
0024
0025 #if defined(MBEDTLS_THREADING_C)
0026 #include "mbedtls/threading.h"
0027 #endif
0028
0029
0030 /** Critical entropy source failure. */
0031 #define MBEDTLS_ERR_ENTROPY_SOURCE_FAILED PSA_ERROR_INSUFFICIENT_ENTROPY
0032 /** No more sources can be added. */
0033 #define MBEDTLS_ERR_ENTROPY_MAX_SOURCES                   -0x003E
0034 /** No sources have been added to poll. */
0035 #define MBEDTLS_ERR_ENTROPY_NO_SOURCES_DEFINED            -0x0040
0036 /** No strong sources have been added to poll. */
0037 #define MBEDTLS_ERR_ENTROPY_NO_STRONG_SOURCE              -0x003D
0038 /** Read/write error in file. */
0039 #define MBEDTLS_ERR_ENTROPY_FILE_IO_ERROR                 -0x003F
0040
0041 /**
0042  * \name SECTION: Module settings
0043  *
0044  * The configuration options you can set for this module are in this section.
0045  * Either change them in mbedtls_config.h or define them on the compiler command line.
0046  * \{
0047  */
0048
0049 #define MBEDTLS_ENTROPY_MAX_SOURCES     4       /**< Maximum number of sources supported. Should be just 2 eventually. */
0050 #define MBEDTLS_ENTROPY_MAX_GATHER      128     /**< Maximum amount requested from entropy sources */
0051
0052 /** \} name SECTION: Module settings */
0053
0054 #define MBEDTLS_ENTROPY_MAX_SEED_SIZE   1024    /**< Maximum size of seed we read from seed file */
0055 #define MBEDTLS_ENTROPY_SOURCE_MANUAL   MBEDTLS_ENTROPY_MAX_SOURCES
0056
0057 #define MBEDTLS_ENTROPY_SOURCE_STRONG   1       /**< Entropy source is strong   */
0058 #define MBEDTLS_ENTROPY_SOURCE_WEAK     0       /**< Entropy source is weak     */
0059
0060 #ifdef __cplusplus
0061 extern "C" {
0062 #endif
0063
0064 /**
0065  * \brief           Entropy poll callback pointer
0066  *
0067  * \param data      Callback-specific data pointer
0068  * \param output    Data to fill
0069  * \param len       Maximum size to provide
0070  * \param olen      The actual amount of bytes put into the buffer (Can be 0)
0071  *
0072  * \return          0 if no critical failures occurred,
0073  *                  MBEDTLS_ERR_ENTROPY_SOURCE_FAILED otherwise
0074  */
0075 typedef int (*mbedtls_entropy_f_source_ptr)(void *data, unsigned char *output, size_t len,
0076                                             size_t *olen);
0077
0078 /**
0079  * \brief           Entropy source state
0080  */
0081 typedef struct mbedtls_entropy_source_state {
0082     mbedtls_entropy_f_source_ptr    MBEDTLS_PRIVATE(f_source);   /**< The entropy source callback */
0083     void *MBEDTLS_PRIVATE(p_source);             /**< The callback data pointer */
0084     size_t          MBEDTLS_PRIVATE(size);       /**< Amount received in bytes */
0085     size_t          MBEDTLS_PRIVATE(threshold);  /**< Minimum bytes required before release */
0086     int             MBEDTLS_PRIVATE(strong);     /**< Is the source strong? */
0087 }
0088 mbedtls_entropy_source_state;
0089
0090 /**
0091  * \brief           Entropy context structure
0092  */
0093 typedef struct mbedtls_entropy_context {
0094     mbedtls_md_context_t  MBEDTLS_PRIVATE(accumulator);
0095     int MBEDTLS_PRIVATE(accumulator_started); /* 0 after init.
0096                                                * 1 after the first update.
0097                                                * -1 after free. */
0098     int             MBEDTLS_PRIVATE(source_count); /* Number of entries used in source. */
0099     mbedtls_entropy_source_state    MBEDTLS_PRIVATE(source)[MBEDTLS_ENTROPY_MAX_SOURCES];
0100 #if defined(MBEDTLS_THREADING_C)
0101     mbedtls_threading_mutex_t MBEDTLS_PRIVATE(mutex);    /*!< mutex                  */
0102 #endif
0103 #if defined(MBEDTLS_ENTROPY_NV_SEED)
0104     int MBEDTLS_PRIVATE(initial_entropy_run);
0105 #endif
0106 }
0107 mbedtls_entropy_context;
0108
0109 /**
0110  * \brief           Initialize the context
0111  *
0112  * \param ctx       Entropy context to initialize
0113  */
0114 void mbedtls_entropy_init(mbedtls_entropy_context *ctx);
0115
0116 /**
0117  * \brief           Free the data in the context
0118  *
0119  * \param ctx       Entropy context to free
0120  */
0121 void mbedtls_entropy_free(mbedtls_entropy_context *ctx);
0122
0123 /**
0124  * \brief           Adds an entropy source to poll
0125  *                  (Thread-safe if MBEDTLS_THREADING_C is enabled)
0126  *
0127  * \param ctx       Entropy context
0128  * \param f_source  Entropy function
0129  * \param p_source  Function data
0130  * \param threshold Minimum required from source before entropy is released
0131  *                  ( with mbedtls_entropy_func() ) (in bytes)
0132  * \param strong    MBEDTLS_ENTROPY_SOURCE_STRONG or
0133  *                  MBEDTLS_ENTROPY_SOURCE_WEAK.
0134  *                  At least one strong source needs to be added.
0135  *                  Weaker sources (such as the cycle counter) can be used as
0136  *                  a complement.
0137  *
0138  * \return          0 if successful or MBEDTLS_ERR_ENTROPY_MAX_SOURCES
0139  */
0140 int mbedtls_entropy_add_source(mbedtls_entropy_context *ctx,
0141                                mbedtls_entropy_f_source_ptr f_source, void *p_source,
0142                                size_t threshold, int strong);
0143
0144 /**
0145  * \brief           Trigger an extra gather poll for the accumulator
0146  *                  (Thread-safe if MBEDTLS_THREADING_C is enabled)
0147  *
0148  * \param ctx       Entropy context
0149  *
0150  * \return          0 if successful, or MBEDTLS_ERR_ENTROPY_SOURCE_FAILED
0151  */
0152 int mbedtls_entropy_gather(mbedtls_entropy_context *ctx);
0153
0154 /**
0155  * \brief           Retrieve entropy from the accumulator
0156  *                  (Maximum length: MBEDTLS_ENTROPY_BLOCK_SIZE)
0157  *                  (Thread-safe if MBEDTLS_THREADING_C is enabled)
0158  *
0159  * \param data      Entropy context
0160  * \param output    Buffer to fill
0161  * \param len       Number of bytes desired, must be at most MBEDTLS_ENTROPY_BLOCK_SIZE
0162  *
0163  * \return          0 if successful, or MBEDTLS_ERR_ENTROPY_SOURCE_FAILED
0164  */
0165 int mbedtls_entropy_func(void *data, unsigned char *output, size_t len);
0166
0167 /**
0168  * \brief           Add data to the accumulator manually
0169  *                  (Thread-safe if MBEDTLS_THREADING_C is enabled)
0170  *
0171  * \param ctx       Entropy context
0172  * \param data      Data to add
0173  * \param len       Length of data
0174  *
0175  * \return          0 if successful
0176  */
0177 int mbedtls_entropy_update_manual(mbedtls_entropy_context *ctx,
0178                                   const unsigned char *data, size_t len);
0179
0180 #if defined(MBEDTLS_ENTROPY_NV_SEED)
0181 /**
0182  * \brief           Trigger an update of the seed file in NV by using the
0183  *                  current entropy pool.
0184  *
0185  * \param ctx       Entropy context
0186  *
0187  * \return          0 if successful
0188  */
0189 int mbedtls_entropy_update_nv_seed(mbedtls_entropy_context *ctx);
0190 #endif /* MBEDTLS_ENTROPY_NV_SEED */
0191
0192 #if defined(MBEDTLS_FS_IO)
0193 /**
0194  * \brief               Write a seed file
0195  *
0196  * \param ctx           Entropy context
0197  * \param path          Name of the file
0198  *
0199  * \return              0 if successful,
0200  *                      MBEDTLS_ERR_ENTROPY_FILE_IO_ERROR on file error, or
0201  *                      MBEDTLS_ERR_ENTROPY_SOURCE_FAILED
0202  */
0203 int mbedtls_entropy_write_seed_file(mbedtls_entropy_context *ctx, const char *path);
0204
0205 /**
0206  * \brief               Read and update a seed file. Seed is added to this
0207  *                      instance. No more than MBEDTLS_ENTROPY_MAX_SEED_SIZE bytes are
0208  *                      read from the seed file. The rest is ignored.
0209  *
0210  * \param ctx           Entropy context
0211  * \param path          Name of the file
0212  *
0213  * \return              0 if successful,
0214  *                      MBEDTLS_ERR_ENTROPY_FILE_IO_ERROR on file error,
0215  *                      MBEDTLS_ERR_ENTROPY_SOURCE_FAILED
0216  */
0217 int mbedtls_entropy_update_seed_file(mbedtls_entropy_context *ctx, const char *path);
0218 #endif /* MBEDTLS_FS_IO */
0219
0220 #if defined(MBEDTLS_SELF_TEST)
0221 /**
0222  * \brief          Checkup routine
0223  *
0224  *                 This module self-test also calls the entropy self-test,
0225  *                 mbedtls_entropy_source_self_test();
0226  *
0227  * \return         0 if successful, or 1 if a test failed
0228  */
0229 int mbedtls_entropy_self_test(int verbose);
0230
0231 #if defined(MBEDTLS_PSA_DRIVER_GET_ENTROPY)
0232 /**
0233  * \brief          Checkup routine
0234  *
0235  *                 Verifies the integrity of the hardware entropy source
0236  *                 provided by the function 'mbedtls_hardware_poll()'.
0237  *
0238  *                 Note this is the only hardware entropy source that is known
0239  *                 at link time, and other entropy sources configured
0240  *                 dynamically at runtime by the function
0241  *                 mbedtls_entropy_add_source() will not be tested.
0242  *
0243  * \return         0 if successful, or 1 if a test failed
0244  */
0245 int mbedtls_entropy_source_self_test(int verbose);
0246 #endif /* MBEDTLS_PSA_DRIVER_GET_ENTROPY */
0247 #endif /* MBEDTLS_SELF_TEST */
0248
0249 #ifdef __cplusplus
0250 }
0251 #endif
0252
0253 #endif /* entropy.h */