1 /** 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 20 #ifndef MBEDTLS_CONSTANT_TIME_INTERNAL_H 21 #define MBEDTLS_CONSTANT_TIME_INTERNAL_H 22 23 #include "common.h" 24 25 #if defined(MBEDTLS_BIGNUM_C) 26 #include "mbedtls/bignum.h" 27 #endif 28 29 #if defined(MBEDTLS_SSL_TLS_C) 30 #include "ssl_misc.h" 31 #endif 32 33 #include <stddef.h> 34 35 36 /** Turn a value into a mask: 37 * - if \p value == 0, return the all-bits 0 mask, aka 0 38 * - otherwise, return the all-bits 1 mask, aka (unsigned) -1 39 * 40 * This function can be used to write constant-time code by replacing branches 41 * with bit operations using masks. 42 * 43 * \param value The value to analyze. 44 * 45 * \return Zero if \p value is zero, otherwise all-bits-one. 46 */ 47 unsigned mbedtls_ct_uint_mask( unsigned value ); 48 49 #if defined(MBEDTLS_SSL_SOME_SUITES_USE_MAC) 50 51 /** Turn a value into a mask: 52 * - if \p value == 0, return the all-bits 0 mask, aka 0 53 * - otherwise, return the all-bits 1 mask, aka (size_t) -1 54 * 55 * This function can be used to write constant-time code by replacing branches 56 * with bit operations using masks. 57 * 58 * \param value The value to analyze. 59 * 60 * \return Zero if \p value is zero, otherwise all-bits-one. 61 */ 62 size_t mbedtls_ct_size_mask( size_t value ); 63 64 #endif /* MBEDTLS_SSL_SOME_SUITES_USE_MAC */ 65 66 #if defined(MBEDTLS_BIGNUM_C) 67 68 /** Turn a value into a mask: 69 * - if \p value == 0, return the all-bits 0 mask, aka 0 70 * - otherwise, return the all-bits 1 mask, aka (mbedtls_mpi_uint) -1 71 * 72 * This function can be used to write constant-time code by replacing branches 73 * with bit operations using masks. 74 * 75 * \param value The value to analyze. 76 * 77 * \return Zero if \p value is zero, otherwise all-bits-one. 78 */ 79 mbedtls_mpi_uint mbedtls_ct_mpi_uint_mask( mbedtls_mpi_uint value ); 80 81 #endif /* MBEDTLS_BIGNUM_C */ 82 83 #if defined(MBEDTLS_SSL_SOME_SUITES_USE_TLS_CBC) 84 85 /** Constant-flow mask generation for "greater or equal" comparison: 86 * - if \p x >= \p y, return all-bits 1, that is (size_t) -1 87 * - otherwise, return all bits 0, that is 0 88 * 89 * This function can be used to write constant-time code by replacing branches 90 * with bit operations using masks. 91 * 92 * \param x The first value to analyze. 93 * \param y The second value to analyze. 94 * 95 * \return All-bits-one if \p x is greater or equal than \p y, 96 * otherwise zero. 97 */ 98 size_t mbedtls_ct_size_mask_ge( size_t x, 99 size_t y ); 100 101 #endif /* MBEDTLS_SSL_SOME_SUITES_USE_TLS_CBC */ 102 103 /** Constant-flow boolean "equal" comparison: 104 * return x == y 105 * 106 * This is equivalent to \p x == \p y, but is likely to be compiled 107 * to code using bitwise operation rather than a branch. 108 * 109 * \param x The first value to analyze. 110 * \param y The second value to analyze. 111 * 112 * \return 1 if \p x equals to \p y, otherwise 0. 113 */ 114 unsigned mbedtls_ct_size_bool_eq( size_t x, 115 size_t y ); 116 117 #if defined(MBEDTLS_BIGNUM_C) 118 119 /** Decide if an integer is less than the other, without branches. 120 * 121 * This is equivalent to \p x < \p y, but is likely to be compiled 122 * to code using bitwise operation rather than a branch. 123 * 124 * \param x The first value to analyze. 125 * \param y The second value to analyze. 126 * 127 * \return 1 if \p x is less than \p y, otherwise 0. 128 */ 129 unsigned mbedtls_ct_mpi_uint_lt( const mbedtls_mpi_uint x, 130 const mbedtls_mpi_uint y ); 131 132 /** 133 * \brief Check if one unsigned MPI is less than another in constant 134 * time. 135 * 136 * \param A The left-hand MPI. This must point to an array of limbs 137 * with the same allocated length as \p B. 138 * \param B The right-hand MPI. This must point to an array of limbs 139 * with the same allocated length as \p A. 140 * \param limbs The number of limbs in \p A and \p B. 141 * This must not be 0. 142 * 143 * \return The result of the comparison: 144 * \c 1 if \p A is less than \p B. 145 * \c 0 if \p A is greater than or equal to \p B. 146 */ 147 unsigned mbedtls_mpi_core_lt_ct( const mbedtls_mpi_uint *A, 148 const mbedtls_mpi_uint *B, 149 size_t limbs); 150 #endif /* MBEDTLS_BIGNUM_C */ 151 152 /** Choose between two integer values without branches. 153 * 154 * This is equivalent to `condition ? if1 : if0`, but is likely to be compiled 155 * to code using bitwise operation rather than a branch. 156 * 157 * \param condition Condition to test. 158 * \param if1 Value to use if \p condition is nonzero. 159 * \param if0 Value to use if \p condition is zero. 160 * 161 * \return \c if1 if \p condition is nonzero, otherwise \c if0. 162 */ 163 unsigned mbedtls_ct_uint_if( unsigned condition, 164 unsigned if1, 165 unsigned if0 ); 166 167 #if defined(MBEDTLS_BIGNUM_C) 168 169 /** Conditionally assign a value without branches. 170 * 171 * This is equivalent to `if ( condition ) dest = src`, but is likely 172 * to be compiled to code using bitwise operation rather than a branch. 173 * 174 * \param n \p dest and \p src must be arrays of limbs of size n. 175 * \param dest The MPI to conditionally assign to. This must point 176 * to an initialized MPI. 177 * \param src The MPI to be assigned from. This must point to an 178 * initialized MPI. 179 * \param condition Condition to test, must be 0 or 1. 180 */ 181 void mbedtls_ct_mpi_uint_cond_assign( size_t n, 182 mbedtls_mpi_uint *dest, 183 const mbedtls_mpi_uint *src, 184 unsigned char condition ); 185 186 #endif /* MBEDTLS_BIGNUM_C */ 187 188 #if defined(MBEDTLS_BASE64_C) 189 190 /** Given a value in the range 0..63, return the corresponding Base64 digit. 191 * 192 * The implementation assumes that letters are consecutive (e.g. ASCII 193 * but not EBCDIC). 194 * 195 * \param value A value in the range 0..63. 196 * 197 * \return A base64 digit converted from \p value. 198 */ 199 unsigned char mbedtls_ct_base64_enc_char( unsigned char value ); 200 201 /** Given a Base64 digit, return its value. 202 * 203 * If c is not a Base64 digit ('A'..'Z', 'a'..'z', '0'..'9', '+' or '/'), 204 * return -1. 205 * 206 * The implementation assumes that letters are consecutive (e.g. ASCII 207 * but not EBCDIC). 208 * 209 * \param c A base64 digit. 210 * 211 * \return The value of the base64 digit \p c. 212 */ 213 signed char mbedtls_ct_base64_dec_value( unsigned char c ); 214 215 #endif /* MBEDTLS_BASE64_C */ 216 217 #if defined(MBEDTLS_SSL_SOME_SUITES_USE_MAC) 218 219 /** Conditional memcpy without branches. 220 * 221 * This is equivalent to `if ( c1 == c2 ) memcpy(dest, src, len)`, but is likely 222 * to be compiled to code using bitwise operation rather than a branch. 223 * 224 * \param dest The pointer to conditionally copy to. 225 * \param src The pointer to copy from. Shouldn't overlap with \p dest. 226 * \param len The number of bytes to copy. 227 * \param c1 The first value to analyze in the condition. 228 * \param c2 The second value to analyze in the condition. 229 */ 230 void mbedtls_ct_memcpy_if_eq( unsigned char *dest, 231 const unsigned char *src, 232 size_t len, 233 size_t c1, size_t c2 ); 234 235 /** Copy data from a secret position with constant flow. 236 * 237 * This function copies \p len bytes from \p src_base + \p offset_secret to \p 238 * dst, with a code flow and memory access pattern that does not depend on \p 239 * offset_secret, but only on \p offset_min, \p offset_max and \p len. 240 * Functionally equivalent to `memcpy(dst, src + offset_secret, len)`. 241 * 242 * \note This function reads from \p dest, but the value that 243 * is read does not influence the result and this 244 * function's behavior is well-defined regardless of the 245 * contents of the buffers. This may result in false 246 * positives from static or dynamic analyzers, especially 247 * if \p dest is not initialized. 248 * 249 * \param dest The destination buffer. This must point to a writable 250 * buffer of at least \p len bytes. 251 * \param src The base of the source buffer. This must point to a 252 * readable buffer of at least \p offset_max + \p len 253 * bytes. Shouldn't overlap with \p dest. 254 * \param offset The offset in the source buffer from which to copy. 255 * This must be no less than \p offset_min and no greater 256 * than \p offset_max. 257 * \param offset_min The minimal value of \p offset. 258 * \param offset_max The maximal value of \p offset. 259 * \param len The number of bytes to copy. 260 */ 261 void mbedtls_ct_memcpy_offset( unsigned char *dest, 262 const unsigned char *src, 263 size_t offset, 264 size_t offset_min, 265 size_t offset_max, 266 size_t len ); 267 268 /** Compute the HMAC of variable-length data with constant flow. 269 * 270 * This function computes the HMAC of the concatenation of \p add_data and \p 271 * data, and does with a code flow and memory access pattern that does not 272 * depend on \p data_len_secret, but only on \p min_data_len and \p 273 * max_data_len. In particular, this function always reads exactly \p 274 * max_data_len bytes from \p data. 275 * 276 * \param ctx The HMAC context. It must have keys configured 277 * with mbedtls_md_hmac_starts() and use one of the 278 * following hashes: SHA-384, SHA-256, SHA-1 or MD-5. 279 * It is reset using mbedtls_md_hmac_reset() after 280 * the computation is complete to prepare for the 281 * next computation. 282 * \param add_data The first part of the message whose HMAC is being 283 * calculated. This must point to a readable buffer 284 * of \p add_data_len bytes. 285 * \param add_data_len The length of \p add_data in bytes. 286 * \param data The buffer containing the second part of the 287 * message. This must point to a readable buffer 288 * of \p max_data_len bytes. 289 * \param data_len_secret The length of the data to process in \p data. 290 * This must be no less than \p min_data_len and no 291 * greater than \p max_data_len. 292 * \param min_data_len The minimal length of the second part of the 293 * message, read from \p data. 294 * \param max_data_len The maximal length of the second part of the 295 * message, read from \p data. 296 * \param output The HMAC will be written here. This must point to 297 * a writable buffer of sufficient size to hold the 298 * HMAC value. 299 * 300 * \retval 0 on success. 301 * \retval #MBEDTLS_ERR_PLATFORM_HW_ACCEL_FAILED 302 * The hardware accelerator failed. 303 */ 304 #if defined(MBEDTLS_USE_PSA_CRYPTO) 305 int mbedtls_ct_hmac( mbedtls_svc_key_id_t key, 306 psa_algorithm_t alg, 307 const unsigned char *add_data, 308 size_t add_data_len, 309 const unsigned char *data, 310 size_t data_len_secret, 311 size_t min_data_len, 312 size_t max_data_len, 313 unsigned char *output ); 314 #else 315 int mbedtls_ct_hmac( mbedtls_md_context_t *ctx, 316 const unsigned char *add_data, 317 size_t add_data_len, 318 const unsigned char *data, 319 size_t data_len_secret, 320 size_t min_data_len, 321 size_t max_data_len, 322 unsigned char *output ); 323 #endif /* MBEDTLS_USE_PSA_CRYPTO */ 324 325 #endif /* MBEDTLS_SSL_SOME_SUITES_USE_MAC */ 326 327 #if defined(MBEDTLS_PKCS1_V15) && defined(MBEDTLS_RSA_C) && !defined(MBEDTLS_RSA_ALT) 328 329 /** This function performs the unpadding part of a PKCS#1 v1.5 decryption 330 * operation (EME-PKCS1-v1_5 decoding). 331 * 332 * \note The return value from this function is a sensitive value 333 * (this is unusual). #MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE shouldn't happen 334 * in a well-written application, but 0 vs #MBEDTLS_ERR_RSA_INVALID_PADDING 335 * is often a situation that an attacker can provoke and leaking which 336 * one is the result is precisely the information the attacker wants. 337 * 338 * \param input The input buffer which is the payload inside PKCS#1v1.5 339 * encryption padding, called the "encoded message EM" 340 * by the terminology. 341 * \param ilen The length of the payload in the \p input buffer. 342 * \param output The buffer for the payload, called "message M" by the 343 * PKCS#1 terminology. This must be a writable buffer of 344 * length \p output_max_len bytes. 345 * \param olen The address at which to store the length of 346 * the payload. This must not be \c NULL. 347 * \param output_max_len The length in bytes of the output buffer \p output. 348 * 349 * \return \c 0 on success. 350 * \return #MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE 351 * The output buffer is too small for the unpadded payload. 352 * \return #MBEDTLS_ERR_RSA_INVALID_PADDING 353 * The input doesn't contain properly formatted padding. 354 */ 355 int mbedtls_ct_rsaes_pkcs1_v15_unpadding( unsigned char *input, 356 size_t ilen, 357 unsigned char *output, 358 size_t output_max_len, 359 size_t *olen ); 360 361 #endif /* MBEDTLS_PKCS1_V15 && MBEDTLS_RSA_C && ! MBEDTLS_RSA_ALT */ 362 363 #endif /* MBEDTLS_CONSTANT_TIME_INTERNAL_H */ 364
