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