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 */
290