1 /**
2  * \file entropy.h
3  *
4  * \brief Entropy accumulator implementation
5  */
6 /*
7  *  Copyright The Mbed TLS Contributors
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 #ifndef MBEDTLS_ENTROPY_H
23 #define MBEDTLS_ENTROPY_H
24 
25 #if !defined(MBEDTLS_CONFIG_FILE)
26 #include "mbedtls/config.h"
27 #else
28 #include MBEDTLS_CONFIG_FILE
29 #endif
30 
31 #include <stddef.h>
32 
33 #if defined(MBEDTLS_SHA512_C) && !defined(MBEDTLS_ENTROPY_FORCE_SHA256)
34 #include "mbedtls/sha512.h"
35 #define MBEDTLS_ENTROPY_SHA512_ACCUMULATOR
36 #else
37 #if defined(MBEDTLS_SHA256_C)
38 #define MBEDTLS_ENTROPY_SHA256_ACCUMULATOR
39 #include "mbedtls/sha256.h"
40 #endif
41 #endif
42 
43 #if defined(MBEDTLS_THREADING_C)
44 #include "mbedtls/threading.h"
45 #endif
46 
47 #if defined(MBEDTLS_HAVEGE_C)
48 #include "mbedtls/havege.h"
49 #endif
50 
51 #define MBEDTLS_ERR_ENTROPY_SOURCE_FAILED                 -0x003C  /**< Critical entropy source failure. */
52 #define MBEDTLS_ERR_ENTROPY_MAX_SOURCES                   -0x003E  /**< No more sources can be added. */
53 #define MBEDTLS_ERR_ENTROPY_NO_SOURCES_DEFINED            -0x0040  /**< No sources have been added to poll. */
54 #define MBEDTLS_ERR_ENTROPY_NO_STRONG_SOURCE              -0x003D  /**< No strong sources have been added to poll. */
55 #define MBEDTLS_ERR_ENTROPY_FILE_IO_ERROR                 -0x003F  /**< Read/write error in file. */
56 
57 /**
58  * \name SECTION: Module settings
59  *
60  * The configuration options you can set for this module are in this section.
61  * Either change them in config.h or define them on the compiler command line.
62  * \{
63  */
64 
65 #if !defined(MBEDTLS_ENTROPY_MAX_SOURCES)
66 #define MBEDTLS_ENTROPY_MAX_SOURCES     20      /**< Maximum number of sources supported */
67 #endif
68 
69 #if !defined(MBEDTLS_ENTROPY_MAX_GATHER)
70 #define MBEDTLS_ENTROPY_MAX_GATHER      128     /**< Maximum amount requested from entropy sources */
71 #endif
72 
73 /* \} name SECTION: Module settings */
74 
75 #if defined(MBEDTLS_ENTROPY_SHA512_ACCUMULATOR)
76 #define MBEDTLS_ENTROPY_BLOCK_SIZE      64      /**< Block size of entropy accumulator (SHA-512) */
77 #else
78 #define MBEDTLS_ENTROPY_BLOCK_SIZE      32      /**< Block size of entropy accumulator (SHA-256) */
79 #endif
80 
81 #define MBEDTLS_ENTROPY_MAX_SEED_SIZE   1024    /**< Maximum size of seed we read from seed file */
82 #define MBEDTLS_ENTROPY_SOURCE_MANUAL   MBEDTLS_ENTROPY_MAX_SOURCES
83 
84 #define MBEDTLS_ENTROPY_SOURCE_STRONG   1       /**< Entropy source is strong   */
85 #define MBEDTLS_ENTROPY_SOURCE_WEAK     0       /**< Entropy source is weak     */
86 
87 #ifdef __cplusplus
88 extern "C" {
89 #endif
90 
91 /**
92  * \brief           Entropy poll callback pointer
93  *
94  * \param data      Callback-specific data pointer
95  * \param output    Data to fill
96  * \param len       Maximum size to provide
97  * \param olen      The actual amount of bytes put into the buffer (Can be 0)
98  *
99  * \return          0 if no critical failures occurred,
100  *                  MBEDTLS_ERR_ENTROPY_SOURCE_FAILED otherwise
101  */
102 typedef int (*mbedtls_entropy_f_source_ptr)(void *data, unsigned char *output, size_t len,
103                             size_t *olen);
104 
105 /**
106  * \brief           Entropy source state
107  */
108 typedef struct mbedtls_entropy_source_state
109 {
110     mbedtls_entropy_f_source_ptr    f_source;   /**< The entropy source callback */
111     void *          p_source;   /**< The callback data pointer */
112     size_t          size;       /**< Amount received in bytes */
113     size_t          threshold;  /**< Minimum bytes required before release */
114     int             strong;     /**< Is the source strong? */
115 }
116 mbedtls_entropy_source_state;
117 
118 /**
119  * \brief           Entropy context structure
120  */
121 typedef struct mbedtls_entropy_context
122 {
123     int accumulator_started; /* 0 after init.
124                               * 1 after the first update.
125                               * -1 after free. */
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; /* Number of entries used in source. */
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 */
290