blob: 6d549f16ff292b967a30271f1bcb84b417293996 [file] [log] [blame]
gabor-mezei-armdb9a38c2021-09-27 11:28:54 +02001/**
2 * Constant-time functions
3 *
4 * Copyright The Mbed TLS Contributors
5 * SPDX-License-Identifier: Apache-2.0
6 *
7 * Licensed under the Apache License, Version 2.0 (the "License"); you may
8 * not use this file except in compliance with the License.
9 * You may obtain a copy of the License at
10 *
11 * http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing, software
14 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
15 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 * See the License for the specific language governing permissions and
17 * limitations under the License.
18 */
19
Gabor Mezei291df7b2021-10-19 11:27:17 +020020#ifndef MBEDTLS_CONSTANT_TIME_INTERNAL_H
21#define MBEDTLS_CONSTANT_TIME_INTERNAL_H
22
Dave Rodgman40a41d02023-05-17 11:59:56 +010023#include <stdint.h>
24#include <stddef.h>
25
gabor-mezei-armdb9a38c2021-09-27 11:28:54 +020026#include "common.h"
27
gabor-mezei-arm3f90fd52021-09-27 12:55:33 +020028#if defined(MBEDTLS_BIGNUM_C)
29#include "mbedtls/bignum.h"
30#endif
31
Dave Rodgman40a41d02023-05-17 11:59:56 +010032/* The constant-time interface provides various operations that are likely
33 * to result in constant-time code that does not branch or use conditional
34 * instructions for secret data (for secret pointers, this also applies to
35 * the data pointed to).
36 *
37 * It has three main parts:
38 *
Dave Rodgmanf27727b2023-05-13 12:12:02 +010039 * - boolean operations
Dave Rodgman40a41d02023-05-17 11:59:56 +010040 * These are all named mbedtls_ct_bool_<operation>, and operate over
41 * mbedtls_ct_condition_t.
Dave Rodgmanf27727b2023-05-13 12:12:02 +010042 * All arguments are considered secret.
Dave Rodgman40a41d02023-05-17 11:59:56 +010043 * example: bool x = y | z => x = mbedtls_ct_bool_or(y, z)
44 *
45 * - conditional data selection
46 * These are all named mbedtls_ct_<type>_if and mbedtls_ct_<type>_if0
47 * All arguments are considered secret.
48 * example: size_t a = x ? b : c => a = mbedtls_ct_size_if(x, b, c)
49 * example: unsigned a = x ? b : 0 => a = mbedtls_ct_uint_if0(x, b)
50 *
51 * - block memory operations
52 * Only some arguments are considered secret, as documented for each
53 * function.
54 * example: if (x) memcpy(...) => mbedtls_ct_memcpy_if(x, ...)
55 *
Dave Rodgman93cec452023-07-31 12:30:26 +010056 * mbedtls_ct_condition_t must be treated as opaque and only created and
57 * manipulated via the functions in this header. The compiler should never
58 * be able to prove anything about its value at compile-time.
Dave Rodgman40a41d02023-05-17 11:59:56 +010059 *
60 * mbedtls_ct_uint_t is an unsigned integer type over which constant time
61 * operations may be performed via the functions in this header. It is as big
62 * as the larger of size_t and mbedtls_mpi_uint, i.e. it is safe to cast
63 * to/from "unsigned int", "size_t", and "mbedtls_mpi_uint" (and any other
64 * not-larger integer types).
65 *
Dave Rodgmanf27727b2023-05-13 12:12:02 +010066 * For Arm (32-bit, 64-bit and Thumb), x86 and x86-64, assembly implementations
67 * are used to ensure that the generated code is constant time. For other
Dave Rodgman0172de82023-07-31 12:32:23 +010068 * architectures, it uses a plain C fallback designed to yield constant-time code
69 * (this has been observed to be constant-time on latest gcc, clang and MSVC
70 * as of May 2023).
Dave Rodgman205295c2023-08-01 14:10:56 +010071 *
72 * For readability, the static inline definitions are separated out into
73 * constant_time_impl.h.
Dave Rodgman40a41d02023-05-17 11:59:56 +010074 */
75
76#if (SIZE_MAX > 0xffffffffffffffffULL)
77/* Pointer size > 64-bit */
78typedef size_t mbedtls_ct_condition_t;
79typedef size_t mbedtls_ct_uint_t;
80typedef ptrdiff_t mbedtls_ct_int_t;
Dave Rodgmanfba55982023-07-14 13:44:22 +010081#define MBEDTLS_CT_TRUE ((mbedtls_ct_condition_t) mbedtls_ct_compiler_opaque(SIZE_MAX))
Dave Rodgman40a41d02023-05-17 11:59:56 +010082#elif (SIZE_MAX > 0xffffffff) || defined(MBEDTLS_HAVE_INT64)
Dave Rodgmanc882adf2023-06-21 07:37:56 +010083/* 32-bit < pointer size <= 64-bit, or 64-bit MPI */
Dave Rodgman40a41d02023-05-17 11:59:56 +010084typedef uint64_t mbedtls_ct_condition_t;
85typedef uint64_t mbedtls_ct_uint_t;
86typedef int64_t mbedtls_ct_int_t;
Dave Rodgmanfba55982023-07-14 13:44:22 +010087#define MBEDTLS_CT_TRUE ((mbedtls_ct_condition_t) mbedtls_ct_compiler_opaque(UINT64_MAX))
Dave Rodgman40a41d02023-05-17 11:59:56 +010088#else
Dave Rodgmanc882adf2023-06-21 07:37:56 +010089/* Pointer size <= 32-bit, and no 64-bit MPIs */
Dave Rodgman40a41d02023-05-17 11:59:56 +010090typedef uint32_t mbedtls_ct_condition_t;
91typedef uint32_t mbedtls_ct_uint_t;
92typedef int32_t mbedtls_ct_int_t;
Dave Rodgmanfba55982023-07-14 13:44:22 +010093#define MBEDTLS_CT_TRUE ((mbedtls_ct_condition_t) mbedtls_ct_compiler_opaque(UINT32_MAX))
Dave Rodgman40a41d02023-05-17 11:59:56 +010094#endif
Dave Rodgmanfba55982023-07-14 13:44:22 +010095#define MBEDTLS_CT_FALSE ((mbedtls_ct_condition_t) mbedtls_ct_compiler_opaque(0))
Dave Rodgman40a41d02023-05-17 11:59:56 +010096
Dave Rodgman40a41d02023-05-17 11:59:56 +010097/* ============================================================================
98 * Boolean operations
99 */
100
101/** Convert a number into a mbedtls_ct_condition_t.
102 *
103 * \param x Number to convert.
104 *
105 * \return MBEDTLS_CT_TRUE if \p x != 0, or MBEDTLS_CT_FALSE if \p x == 0
106 *
107 */
108static inline mbedtls_ct_condition_t mbedtls_ct_bool(mbedtls_ct_uint_t x);
109
110/** Boolean "not equal" operation.
111 *
112 * Functionally equivalent to:
113 *
114 * \p x != \p y
115 *
116 * \param x The first value to analyze.
117 * \param y The second value to analyze.
118 *
119 * \return MBEDTLS_CT_TRUE if \p x != \p y, otherwise MBEDTLS_CT_FALSE.
120 */
121static inline mbedtls_ct_condition_t mbedtls_ct_bool_ne(mbedtls_ct_uint_t x, mbedtls_ct_uint_t y);
122
123/** Boolean "equals" operation.
124 *
125 * Functionally equivalent to:
126 *
127 * \p x == \p y
128 *
129 * \param x The first value to analyze.
130 * \param y The second value to analyze.
131 *
132 * \return MBEDTLS_CT_TRUE if \p x == \p y, otherwise MBEDTLS_CT_FALSE.
133 */
134static inline mbedtls_ct_condition_t mbedtls_ct_bool_eq(mbedtls_ct_uint_t x,
135 mbedtls_ct_uint_t y);
136
137/** Boolean "less than" operation.
138 *
139 * Functionally equivalent to:
140 *
141 * \p x < \p y
142 *
143 * \param x The first value to analyze.
144 * \param y The second value to analyze.
145 *
146 * \return MBEDTLS_CT_TRUE if \p x < \p y, otherwise MBEDTLS_CT_FALSE.
147 */
148static inline mbedtls_ct_condition_t mbedtls_ct_bool_lt(mbedtls_ct_uint_t x, mbedtls_ct_uint_t y);
149
150/** Boolean "greater than" operation.
151 *
152 * Functionally equivalent to:
153 *
154 * \p x > \p y
155 *
156 * \param x The first value to analyze.
157 * \param y The second value to analyze.
158 *
159 * \return MBEDTLS_CT_TRUE if \p x > \p y, otherwise MBEDTLS_CT_FALSE.
160 */
161static inline mbedtls_ct_condition_t mbedtls_ct_bool_gt(mbedtls_ct_uint_t x,
162 mbedtls_ct_uint_t y);
163
164/** Boolean "greater or equal" operation.
165 *
166 * Functionally equivalent to:
167 *
168 * \p x >= \p y
169 *
170 * \param x The first value to analyze.
171 * \param y The second value to analyze.
172 *
173 * \return MBEDTLS_CT_TRUE if \p x >= \p y,
174 * otherwise MBEDTLS_CT_FALSE.
175 */
176static inline mbedtls_ct_condition_t mbedtls_ct_bool_ge(mbedtls_ct_uint_t x,
177 mbedtls_ct_uint_t y);
178
179/** Boolean "less than or equal" operation.
180 *
181 * Functionally equivalent to:
182 *
183 * \p x <= \p y
184 *
185 * \param x The first value to analyze.
186 * \param y The second value to analyze.
187 *
188 * \return MBEDTLS_CT_TRUE if \p x <= \p y,
189 * otherwise MBEDTLS_CT_FALSE.
190 */
191static inline mbedtls_ct_condition_t mbedtls_ct_bool_le(mbedtls_ct_uint_t x,
192 mbedtls_ct_uint_t y);
193
194/** Boolean "xor" operation.
195 *
196 * Functionally equivalent to:
197 *
198 * \p x ^ \p y
199 *
200 * \param x The first value to analyze.
201 * \param y The second value to analyze.
202 *
203 * \note This is more efficient than mbedtls_ct_bool_ne if both arguments are
204 * mbedtls_ct_condition_t.
205 *
206 * \return MBEDTLS_CT_TRUE if \p x ^ \p y,
207 * otherwise MBEDTLS_CT_FALSE.
208 */
209static inline mbedtls_ct_condition_t mbedtls_ct_bool_xor(mbedtls_ct_condition_t x,
210 mbedtls_ct_condition_t y);
211
212/** Boolean "and" operation.
213 *
214 * Functionally equivalent to:
215 *
216 * \p x && \p y
217 *
218 * \param x The first value to analyze.
219 * \param y The second value to analyze.
220 *
221 * \return MBEDTLS_CT_TRUE if \p x && \p y,
222 * otherwise MBEDTLS_CT_FALSE.
223 */
224static inline mbedtls_ct_condition_t mbedtls_ct_bool_and(mbedtls_ct_condition_t x,
225 mbedtls_ct_condition_t y);
226
227/** Boolean "or" operation.
228 *
229 * Functionally equivalent to:
230 *
231 * \p x || \p y
232 *
233 * \param x The first value to analyze.
234 * \param y The second value to analyze.
235 *
236 * \return MBEDTLS_CT_TRUE if \p x || \p y,
237 * otherwise MBEDTLS_CT_FALSE.
238 */
239static inline mbedtls_ct_condition_t mbedtls_ct_bool_or(mbedtls_ct_condition_t x,
240 mbedtls_ct_condition_t y);
241
242/** Boolean "not" operation.
243 *
244 * Functionally equivalent to:
245 *
246 * ! \p x
247 *
248 * \param x The value to invert
249 *
250 * \return MBEDTLS_CT_FALSE if \p x, otherwise MBEDTLS_CT_TRUE.
251 */
252static inline mbedtls_ct_condition_t mbedtls_ct_bool_not(mbedtls_ct_condition_t x);
253
254
255/* ============================================================================
256 * Data selection operations
257 */
258
259/** Choose between two size_t values.
260 *
261 * Functionally equivalent to:
262 *
263 * condition ? if1 : if0.
264 *
265 * \param condition Condition to test.
266 * \param if1 Value to use if \p condition == MBEDTLS_CT_TRUE.
267 * \param if0 Value to use if \p condition == MBEDTLS_CT_FALSE.
268 *
269 * \return \c if1 if \p condition == MBEDTLS_CT_TRUE, otherwise \c if0.
270 */
271static inline size_t mbedtls_ct_size_if(mbedtls_ct_condition_t condition,
272 size_t if1,
273 size_t if0);
274
275/** Choose between two unsigned values.
276 *
277 * Functionally equivalent to:
278 *
279 * condition ? if1 : if0.
280 *
281 * \param condition Condition to test.
282 * \param if1 Value to use if \p condition == MBEDTLS_CT_TRUE.
283 * \param if0 Value to use if \p condition == MBEDTLS_CT_FALSE.
284 *
285 * \return \c if1 if \p condition == MBEDTLS_CT_TRUE, otherwise \c if0.
286 */
Dave Rodgman2b4486a2023-05-17 15:51:59 +0100287static inline unsigned mbedtls_ct_uint_if(mbedtls_ct_condition_t condition,
Dave Rodgman40a41d02023-05-17 11:59:56 +0100288 unsigned if1,
289 unsigned if0);
290
291#if defined(MBEDTLS_BIGNUM_C)
292
293/** Choose between two mbedtls_mpi_uint values.
294 *
295 * Functionally equivalent to:
296 *
297 * condition ? if1 : if0.
298 *
299 * \param condition Condition to test.
300 * \param if1 Value to use if \p condition == MBEDTLS_CT_TRUE.
301 * \param if0 Value to use if \p condition == MBEDTLS_CT_FALSE.
302 *
303 * \return \c if1 if \p condition == MBEDTLS_CT_TRUE, otherwise \c if0.
304 */
305static inline mbedtls_mpi_uint mbedtls_ct_mpi_uint_if(mbedtls_ct_condition_t condition, \
306 mbedtls_mpi_uint if1, \
307 mbedtls_mpi_uint if0);
308
309#endif
310
311/** Choose between an unsigned value and 0.
312 *
313 * Functionally equivalent to:
314 *
315 * condition ? if1 : 0.
316 *
317 * Functionally equivalent tombedtls_ct_uint_if(condition, if1, 0) but
318 * results in smaller code size.
319 *
320 * \param condition Condition to test.
321 * \param if1 Value to use if \p condition == MBEDTLS_CT_TRUE.
322 *
323 * \return \c if1 if \p condition == MBEDTLS_CT_TRUE, otherwise 0.
324 */
325static inline unsigned mbedtls_ct_uint_if0(mbedtls_ct_condition_t condition, unsigned if1);
326
327#if defined(MBEDTLS_BIGNUM_C)
328
329/** Choose between an mbedtls_mpi_uint value and 0.
330 *
331 * Functionally equivalent to:
332 *
333 * condition ? if1 : 0.
334 *
335 * Functionally equivalent tombedtls_ct_mpi_uint_if(condition, if1, 0) but
336 * results in smaller code size.
337 *
338 * \param condition Condition to test.
339 * \param if1 Value to use if \p condition == MBEDTLS_CT_TRUE.
340 *
341 * \return \c if1 if \p condition == MBEDTLS_CT_TRUE, otherwise 0.
342 */
343static inline mbedtls_mpi_uint mbedtls_ct_mpi_uint_if0(mbedtls_ct_condition_t condition,
344 mbedtls_mpi_uint if1);
345
346#endif
347
348/** Constant-flow char selection
349 *
350 * \param low Secret. Bottom of range
351 * \param high Secret. Top of range
352 * \param c Secret. Value to compare to range
353 * \param t Secret. Value to return, if in range
354 *
355 * \return \p t if \p low <= \p c <= \p high, 0 otherwise.
356 */
357static inline unsigned char mbedtls_ct_uchar_in_range_if(unsigned char low,
358 unsigned char high,
359 unsigned char c,
360 unsigned char t);
361
362
363/* ============================================================================
364 * Block memory operations
365 */
366
367#if defined(MBEDTLS_PKCS1_V15) && defined(MBEDTLS_RSA_C) && !defined(MBEDTLS_RSA_ALT)
368
369/** Conditionally set a block of memory to zero.
370 *
371 * Regardless of the condition, every byte will be read once and written to
372 * once.
373 *
374 * \param condition Secret. Condition to test.
375 * \param buf Secret. Pointer to the start of the buffer.
376 * \param len Number of bytes to set to zero.
377 *
378 * \warning Unlike mbedtls_platform_zeroize, this does not have the same guarantees
379 * about not being optimised away if the memory is never read again.
380 */
381void mbedtls_ct_zeroize_if(mbedtls_ct_condition_t condition, void *buf, size_t len);
382
383/** Shift some data towards the left inside a buffer.
384 *
385 * Functionally equivalent to:
386 *
387 * memmove(start, start + offset, total - offset);
388 * memset(start + (total - offset), 0, offset);
389 *
390 * Timing independence comes at the expense of performance.
391 *
392 * \param start Secret. Pointer to the start of the buffer.
393 * \param total Total size of the buffer.
394 * \param offset Secret. Offset from which to copy \p total - \p offset bytes.
395 */
396void mbedtls_ct_memmove_left(void *start,
397 size_t total,
398 size_t offset);
399
400#endif /* defined(MBEDTLS_PKCS1_V15) && defined(MBEDTLS_RSA_C) && !defined(MBEDTLS_RSA_ALT) */
401
402/** Conditional memcpy.
403 *
404 * Functionally equivalent to:
405 *
406 * if (condition) {
407 * memcpy(dest, src1, len);
408 * } else {
409 * if (src2 != NULL)
410 * memcpy(dest, src2, len);
411 * }
412 *
413 * It will always read len bytes from src1.
414 * If src2 != NULL, it will always read len bytes from src2.
415 * If src2 == NULL, it will instead read len bytes from dest (as if src2 == dest).
416 *
417 * \param condition The condition
418 * \param dest Secret. Destination pointer.
Dave Rodgman31086452023-05-18 13:47:13 +0100419 * \param src1 Secret. Pointer to copy from (if \p condition == MBEDTLS_CT_TRUE).
420 * This may be equal to \p dest, but may not overlap in other ways.
Dave Rodgman741d4232023-07-31 12:31:01 +0100421 * \param src2 Secret (contents only - may branch to determine if this parameter is NULL).
Dave Rodgman31086452023-05-18 13:47:13 +0100422 * Pointer to copy from (if \p condition == MBEDTLS_CT_FALSE and \p src2 is not NULL). May be NULL.
423 * This may be equal to \p dest, but may not overlap it in other ways. It may overlap with \p src1.
Dave Rodgman40a41d02023-05-17 11:59:56 +0100424 * \param len Number of bytes to copy.
425 */
426void mbedtls_ct_memcpy_if(mbedtls_ct_condition_t condition,
427 unsigned char *dest,
428 const unsigned char *src1,
429 const unsigned char *src2,
430 size_t len
431 );
432
433/** Copy data from a secret position.
434 *
435 * Functionally equivalent to:
436 *
437 * memcpy(dst, src + offset, len)
438 *
439 * This function copies \p len bytes from \p src_base + \p offset to \p
440 * dst, with a code flow and memory access pattern that does not depend on
441 * \p offset, but only on \p offset_min, \p offset_max and \p len.
442 *
443 * \note This function reads from \p dest, but the value that
444 * is read does not influence the result and this
445 * function's behavior is well-defined regardless of the
446 * contents of the buffers. This may result in false
447 * positives from static or dynamic analyzers, especially
448 * if \p dest is not initialized.
449 *
450 * \param dest Secret. The destination buffer. This must point to a writable
451 * buffer of at least \p len bytes.
452 * \param src Secret. The base of the source buffer. This must point to a
453 * readable buffer of at least \p offset_max + \p len
Dave Rodgman31086452023-05-18 13:47:13 +0100454 * bytes. Shouldn't overlap with \p dest
Dave Rodgman40a41d02023-05-17 11:59:56 +0100455 * \param offset Secret. The offset in the source buffer from which to copy.
456 * This must be no less than \p offset_min and no greater
457 * than \p offset_max.
458 * \param offset_min The minimal value of \p offset.
459 * \param offset_max The maximal value of \p offset.
460 * \param len The number of bytes to copy.
461 */
462void mbedtls_ct_memcpy_offset(unsigned char *dest,
463 const unsigned char *src,
464 size_t offset,
465 size_t offset_min,
466 size_t offset_max,
467 size_t len);
468
Dave Rodgman9ee0e1f2023-07-31 12:33:36 +0100469/* Documented in include/mbedtls/constant_time.h. a and b are secret.
470
471 int mbedtls_ct_memcmp(const void *a,
472 const void *b,
473 size_t n);
474 */
Dave Rodgman40a41d02023-05-17 11:59:56 +0100475
Dave Rodgman205295c2023-08-01 14:10:56 +0100476/* Include the implementation of static inline functions above. */
477#include "constant_time_impl.h"
Dave Rodgmana02b3682023-07-14 13:43:39 +0100478
Gabor Mezei291df7b2021-10-19 11:27:17 +0200479#endif /* MBEDTLS_CONSTANT_TIME_INTERNAL_H */