/** * Constant-time functions * * Copyright The Mbed TLS Contributors * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later */ #ifndef MBEDTLS_CONSTANT_TIME_INTERNAL_H #define MBEDTLS_CONSTANT_TIME_INTERNAL_H #include <stdint.h> #include <stddef.h> #include "common.h" #if defined(MBEDTLS_BIGNUM_C) #include "mbedtls/bignum.h" #endif /* The constant-time interface provides various operations that are likely * to result in constant-time code that does not branch or use conditional * instructions for secret data (for secret pointers, this also applies to * the data pointed to). * * It has three main parts: * * - boolean operations * These are all named mbedtls_ct_<type>_<operation>. * They operate over <type> and return mbedtls_ct_condition_t. * All arguments are considered secret. * example: bool x = y | z => x = mbedtls_ct_bool_or(y, z) * example: bool x = y == z => x = mbedtls_ct_uint_eq(y, z) * * - conditional data selection * These are all named mbedtls_ct_<type>_if and mbedtls_ct_<type>_if_else_0 * All arguments are considered secret. * example: size_t a = x ? b : c => a = mbedtls_ct_size_if(x, b, c) * example: unsigned a = x ? b : 0 => a = mbedtls_ct_uint_if_else_0(x, b) * * - block memory operations * Only some arguments are considered secret, as documented for each * function. * example: if (x) memcpy(...) => mbedtls_ct_memcpy_if(x, ...) * * mbedtls_ct_condition_t must be treated as opaque and only created and * manipulated via the functions in this header. The compiler should never * be able to prove anything about its value at compile-time. * * mbedtls_ct_uint_t is an unsigned integer type over which constant time * operations may be performed via the functions in this header. It is as big * as the larger of size_t and mbedtls_mpi_uint, i.e. it is safe to cast * to/from "unsigned int", "size_t", and "mbedtls_mpi_uint" (and any other * not-larger integer types). * * For Arm (32-bit, 64-bit and Thumb), x86 and x86-64, assembly implementations * are used to ensure that the generated code is constant time. For other * architectures, it uses a plain C fallback designed to yield constant-time code * (this has been observed to be constant-time on latest gcc, clang and MSVC * as of May 2023). * * For readability, the static inline definitions are separated out into * constant_time_impl.h. */ #if (SIZE_MAX > 0xffffffffffffffffULL) /* Pointer size > 64-bit */ typedef size_t mbedtls_ct_condition_t; typedef size_t mbedtls_ct_uint_t; typedef ptrdiff_t mbedtls_ct_int_t; #define MBEDTLS_CT_TRUE … #elif (SIZE_MAX > 0xffffffff) || defined(MBEDTLS_HAVE_INT64) /* 32-bit < pointer size <= 64-bit, or 64-bit MPI */ mbedtls_ct_condition_t; mbedtls_ct_uint_t; mbedtls_ct_int_t; #define MBEDTLS_CT_SIZE_64 #define MBEDTLS_CT_TRUE … #else /* Pointer size <= 32-bit, and no 64-bit MPIs */ typedef uint32_t mbedtls_ct_condition_t; typedef uint32_t mbedtls_ct_uint_t; typedef int32_t mbedtls_ct_int_t; #define MBEDTLS_CT_SIZE_32 #define MBEDTLS_CT_TRUE … #endif #define MBEDTLS_CT_FALSE … /* ============================================================================ * Boolean operations */ /** Convert a number into a mbedtls_ct_condition_t. * * \param x Number to convert. * * \return MBEDTLS_CT_TRUE if \p x != 0, or MBEDTLS_CT_FALSE if \p x == 0 * */ static inline mbedtls_ct_condition_t mbedtls_ct_bool(mbedtls_ct_uint_t x); /** Boolean "not equal" operation. * * Functionally equivalent to: * * \p x != \p y * * \param x The first value to analyze. * \param y The second value to analyze. * * \return MBEDTLS_CT_TRUE if \p x != \p y, otherwise MBEDTLS_CT_FALSE. */ static inline mbedtls_ct_condition_t mbedtls_ct_uint_ne(mbedtls_ct_uint_t x, mbedtls_ct_uint_t y); /** Boolean "equals" operation. * * Functionally equivalent to: * * \p x == \p y * * \param x The first value to analyze. * \param y The second value to analyze. * * \return MBEDTLS_CT_TRUE if \p x == \p y, otherwise MBEDTLS_CT_FALSE. */ static inline mbedtls_ct_condition_t mbedtls_ct_uint_eq(mbedtls_ct_uint_t x, mbedtls_ct_uint_t y); /** Boolean "less than" operation. * * Functionally equivalent to: * * \p x < \p y * * \param x The first value to analyze. * \param y The second value to analyze. * * \return MBEDTLS_CT_TRUE if \p x < \p y, otherwise MBEDTLS_CT_FALSE. */ static inline mbedtls_ct_condition_t mbedtls_ct_uint_lt(mbedtls_ct_uint_t x, mbedtls_ct_uint_t y); /** Boolean "greater than" operation. * * Functionally equivalent to: * * \p x > \p y * * \param x The first value to analyze. * \param y The second value to analyze. * * \return MBEDTLS_CT_TRUE if \p x > \p y, otherwise MBEDTLS_CT_FALSE. */ static inline mbedtls_ct_condition_t mbedtls_ct_uint_gt(mbedtls_ct_uint_t x, mbedtls_ct_uint_t y); /** Boolean "greater or equal" operation. * * Functionally equivalent to: * * \p x >= \p y * * \param x The first value to analyze. * \param y The second value to analyze. * * \return MBEDTLS_CT_TRUE if \p x >= \p y, * otherwise MBEDTLS_CT_FALSE. */ static inline mbedtls_ct_condition_t mbedtls_ct_uint_ge(mbedtls_ct_uint_t x, mbedtls_ct_uint_t y); /** Boolean "less than or equal" operation. * * Functionally equivalent to: * * \p x <= \p y * * \param x The first value to analyze. * \param y The second value to analyze. * * \return MBEDTLS_CT_TRUE if \p x <= \p y, * otherwise MBEDTLS_CT_FALSE. */ static inline mbedtls_ct_condition_t mbedtls_ct_uint_le(mbedtls_ct_uint_t x, mbedtls_ct_uint_t y); /** Boolean not-equals operation. * * Functionally equivalent to: * * \p x != \p y * * \param x The first value to analyze. * \param y The second value to analyze. * * \note This is more efficient than mbedtls_ct_uint_ne if both arguments are * mbedtls_ct_condition_t. * * \return MBEDTLS_CT_TRUE if \p x != \p y, * otherwise MBEDTLS_CT_FALSE. */ static inline mbedtls_ct_condition_t mbedtls_ct_bool_ne(mbedtls_ct_condition_t x, mbedtls_ct_condition_t y); /** Boolean "and" operation. * * Functionally equivalent to: * * \p x && \p y * * \param x The first value to analyze. * \param y The second value to analyze. * * \return MBEDTLS_CT_TRUE if \p x && \p y, * otherwise MBEDTLS_CT_FALSE. */ static inline mbedtls_ct_condition_t mbedtls_ct_bool_and(mbedtls_ct_condition_t x, mbedtls_ct_condition_t y); /** Boolean "or" operation. * * Functionally equivalent to: * * \p x || \p y * * \param x The first value to analyze. * \param y The second value to analyze. * * \return MBEDTLS_CT_TRUE if \p x || \p y, * otherwise MBEDTLS_CT_FALSE. */ static inline mbedtls_ct_condition_t mbedtls_ct_bool_or(mbedtls_ct_condition_t x, mbedtls_ct_condition_t y); /** Boolean "not" operation. * * Functionally equivalent to: * * ! \p x * * \param x The value to invert * * \return MBEDTLS_CT_FALSE if \p x, otherwise MBEDTLS_CT_TRUE. */ static inline mbedtls_ct_condition_t mbedtls_ct_bool_not(mbedtls_ct_condition_t x); /* ============================================================================ * Data selection operations */ /** Choose between two size_t values. * * Functionally equivalent to: * * condition ? if1 : if0. * * \param condition Condition to test. * \param if1 Value to use if \p condition == MBEDTLS_CT_TRUE. * \param if0 Value to use if \p condition == MBEDTLS_CT_FALSE. * * \return \c if1 if \p condition == MBEDTLS_CT_TRUE, otherwise \c if0. */ static inline size_t mbedtls_ct_size_if(mbedtls_ct_condition_t condition, size_t if1, size_t if0); /** Choose between two unsigned values. * * Functionally equivalent to: * * condition ? if1 : if0. * * \param condition Condition to test. * \param if1 Value to use if \p condition == MBEDTLS_CT_TRUE. * \param if0 Value to use if \p condition == MBEDTLS_CT_FALSE. * * \return \c if1 if \p condition == MBEDTLS_CT_TRUE, otherwise \c if0. */ static inline unsigned mbedtls_ct_uint_if(mbedtls_ct_condition_t condition, unsigned if1, unsigned if0); /** Choose between two mbedtls_ct_condition_t values. * * Functionally equivalent to: * * condition ? if1 : if0. * * \param condition Condition to test. * \param if1 Value to use if \p condition == MBEDTLS_CT_TRUE. * \param if0 Value to use if \p condition == MBEDTLS_CT_FALSE. * * \return \c if1 if \p condition == MBEDTLS_CT_TRUE, otherwise \c if0. */ static inline mbedtls_ct_condition_t mbedtls_ct_bool_if(mbedtls_ct_condition_t condition, mbedtls_ct_condition_t if1, mbedtls_ct_condition_t if0); #if defined(MBEDTLS_BIGNUM_C) /** Choose between two mbedtls_mpi_uint values. * * Functionally equivalent to: * * condition ? if1 : if0. * * \param condition Condition to test. * \param if1 Value to use if \p condition == MBEDTLS_CT_TRUE. * \param if0 Value to use if \p condition == MBEDTLS_CT_FALSE. * * \return \c if1 if \p condition == MBEDTLS_CT_TRUE, otherwise \c if0. */ static inline mbedtls_mpi_uint mbedtls_ct_mpi_uint_if(mbedtls_ct_condition_t condition, \ mbedtls_mpi_uint if1, \ mbedtls_mpi_uint if0); #endif /** Choose between an unsigned value and 0. * * Functionally equivalent to: * * condition ? if1 : 0. * * Functionally equivalent to mbedtls_ct_uint_if(condition, if1, 0) but * results in smaller code size. * * \param condition Condition to test. * \param if1 Value to use if \p condition == MBEDTLS_CT_TRUE. * * \return \c if1 if \p condition == MBEDTLS_CT_TRUE, otherwise 0. */ static inline unsigned mbedtls_ct_uint_if_else_0(mbedtls_ct_condition_t condition, unsigned if1); /** Choose between an mbedtls_ct_condition_t and 0. * * Functionally equivalent to: * * condition ? if1 : 0. * * Functionally equivalent to mbedtls_ct_bool_if(condition, if1, 0) but * results in smaller code size. * * \param condition Condition to test. * \param if1 Value to use if \p condition == MBEDTLS_CT_TRUE. * * \return \c if1 if \p condition == MBEDTLS_CT_TRUE, otherwise 0. */ static inline mbedtls_ct_condition_t mbedtls_ct_bool_if_else_0(mbedtls_ct_condition_t condition, mbedtls_ct_condition_t if1); /** Choose between a size_t value and 0. * * Functionally equivalent to: * * condition ? if1 : 0. * * Functionally equivalent to mbedtls_ct_size_if(condition, if1, 0) but * results in smaller code size. * * \param condition Condition to test. * \param if1 Value to use if \p condition == MBEDTLS_CT_TRUE. * * \return \c if1 if \p condition == MBEDTLS_CT_TRUE, otherwise 0. */ static inline size_t mbedtls_ct_size_if_else_0(mbedtls_ct_condition_t condition, size_t if1); #if defined(MBEDTLS_BIGNUM_C) /** Choose between an mbedtls_mpi_uint value and 0. * * Functionally equivalent to: * * condition ? if1 : 0. * * Functionally equivalent to mbedtls_ct_mpi_uint_if(condition, if1, 0) but * results in smaller code size. * * \param condition Condition to test. * \param if1 Value to use if \p condition == MBEDTLS_CT_TRUE. * * \return \c if1 if \p condition == MBEDTLS_CT_TRUE, otherwise 0. */ static inline mbedtls_mpi_uint mbedtls_ct_mpi_uint_if_else_0(mbedtls_ct_condition_t condition, mbedtls_mpi_uint if1); #endif /** Constant-flow char selection * * \param low Secret. Bottom of range * \param high Secret. Top of range * \param c Secret. Value to compare to range * \param t Secret. Value to return, if in range * * \return \p t if \p low <= \p c <= \p high, 0 otherwise. */ static inline unsigned char mbedtls_ct_uchar_in_range_if(unsigned char low, unsigned char high, unsigned char c, unsigned char t); /** Choose between two error values. The values must be in the range [-32767..0]. * * Functionally equivalent to: * * condition ? if1 : if0. * * \param condition Condition to test. * \param if1 Value to use if \p condition == MBEDTLS_CT_TRUE. * \param if0 Value to use if \p condition == MBEDTLS_CT_FALSE. * * \return \c if1 if \p condition == MBEDTLS_CT_TRUE, otherwise \c if0. */ static inline int mbedtls_ct_error_if(mbedtls_ct_condition_t condition, int if1, int if0); /** Choose between an error value and 0. The error value must be in the range [-32767..0]. * * Functionally equivalent to: * * condition ? if1 : 0. * * Functionally equivalent to mbedtls_ct_error_if(condition, if1, 0) but * results in smaller code size. * * \param condition Condition to test. * \param if1 Value to use if \p condition == MBEDTLS_CT_TRUE. * * \return \c if1 if \p condition == MBEDTLS_CT_TRUE, otherwise 0. */ static inline int mbedtls_ct_error_if_else_0(mbedtls_ct_condition_t condition, int if1); /* ============================================================================ * Block memory operations */ #if defined(MBEDTLS_PKCS1_V15) && defined(MBEDTLS_RSA_C) && !defined(MBEDTLS_RSA_ALT) /** Conditionally set a block of memory to zero. * * Regardless of the condition, every byte will be read once and written to * once. * * \param condition Secret. Condition to test. * \param buf Secret. Pointer to the start of the buffer. * \param len Number of bytes to set to zero. * * \warning Unlike mbedtls_platform_zeroize, this does not have the same guarantees * about not being optimised away if the memory is never read again. */ void mbedtls_ct_zeroize_if(mbedtls_ct_condition_t condition, void *buf, size_t len); /** Shift some data towards the left inside a buffer. * * Functionally equivalent to: * * memmove(start, start + offset, total - offset); * memset(start + (total - offset), 0, offset); * * Timing independence comes at the expense of performance. * * \param start Secret. Pointer to the start of the buffer. * \param total Total size of the buffer. * \param offset Secret. Offset from which to copy \p total - \p offset bytes. */ void mbedtls_ct_memmove_left(void *start, size_t total, size_t offset); #endif /* defined(MBEDTLS_PKCS1_V15) && defined(MBEDTLS_RSA_C) && !defined(MBEDTLS_RSA_ALT) */ /** Conditional memcpy. * * Functionally equivalent to: * * if (condition) { * memcpy(dest, src1, len); * } else { * if (src2 != NULL) * memcpy(dest, src2, len); * } * * It will always read len bytes from src1. * If src2 != NULL, it will always read len bytes from src2. * If src2 == NULL, it will instead read len bytes from dest (as if src2 == dest). * * \param condition The condition * \param dest Secret. Destination pointer. * \param src1 Secret. Pointer to copy from (if \p condition == MBEDTLS_CT_TRUE). * This may be equal to \p dest, but may not overlap in other ways. * \param src2 Secret (contents only - may branch to determine if this parameter is NULL). * Pointer to copy from (if \p condition == MBEDTLS_CT_FALSE and \p src2 is not NULL). May be NULL. * This may be equal to \p dest, but may not overlap it in other ways. It may overlap with \p src1. * \param len Number of bytes to copy. */ void mbedtls_ct_memcpy_if(mbedtls_ct_condition_t condition, unsigned char *dest, const unsigned char *src1, const unsigned char *src2, size_t len ); /** Copy data from a secret position. * * Functionally equivalent to: * * memcpy(dst, src + offset, len) * * This function copies \p len bytes from \p src + \p offset to * \p dst, with a code flow and memory access pattern that does not depend on * \p offset, but only on \p offset_min, \p offset_max and \p len. * * \note This function reads from \p dest, but the value that * is read does not influence the result and this * function's behavior is well-defined regardless of the * contents of the buffers. This may result in false * positives from static or dynamic analyzers, especially * if \p dest is not initialized. * * \param dest Secret. The destination buffer. This must point to a writable * buffer of at least \p len bytes. * \param src Secret. The base of the source buffer. This must point to a * readable buffer of at least \p offset_max + \p len * bytes. Shouldn't overlap with \p dest * \param offset Secret. The offset in the source buffer from which to copy. * This must be no less than \p offset_min and no greater * than \p offset_max. * \param offset_min The minimal value of \p offset. * \param offset_max The maximal value of \p offset. * \param len The number of bytes to copy. */ void mbedtls_ct_memcpy_offset(unsigned char *dest, const unsigned char *src, size_t offset, size_t offset_min, size_t offset_max, size_t len); /* Documented in include/mbedtls/constant_time.h. a and b are secret. int mbedtls_ct_memcmp(const void *a, const void *b, size_t n); */ #if defined(MBEDTLS_NIST_KW_C) /** Constant-time buffer comparison without branches. * * Similar to mbedtls_ct_memcmp, except that the result only depends on part of * the input data - differences in the head or tail are ignored. Functionally equivalent to: * * memcmp(a + skip_head, b + skip_head, size - skip_head - skip_tail) * * Time taken depends on \p n, but not on \p skip_head or \p skip_tail . * * Behaviour is undefined if ( \p skip_head + \p skip_tail) > \p n. * * \param a Secret. Pointer to the first buffer, containing at least \p n bytes. May not be NULL. * \param b Secret. Pointer to the second buffer, containing at least \p n bytes. May not be NULL. * \param n The number of bytes to examine (total size of the buffers). * \param skip_head Secret. The number of bytes to treat as non-significant at the start of the buffer. * These bytes will still be read. * \param skip_tail Secret. The number of bytes to treat as non-significant at the end of the buffer. * These bytes will still be read. * * \return Zero if the contents of the two buffers are the same, otherwise non-zero. */ int mbedtls_ct_memcmp_partial(const void *a, const void *b, size_t n, size_t skip_head, size_t skip_tail); #endif /* Include the implementation of static inline functions above. */ #include "constant_time_impl.h" #endif /* MBEDTLS_CONSTANT_TIME_INTERNAL_H */
Codebase Browser
godot