pigweed / third_party / github / ARMmbed / mbedtls / c2a938711085813eae11d99550b280c416a8242e / . / library / constant_time_internal.h

/** | |

* Constant-time functions | |

* | |

* Copyright The Mbed TLS Contributors | |

* SPDX-License-Identifier: Apache-2.0 | |

* | |

* Licensed under the Apache License, Version 2.0 (the "License"); you may | |

* not use this file except in compliance with the License. | |

* You may obtain a copy of the License at | |

* | |

* http://www.apache.org/licenses/LICENSE-2.0 | |

* | |

* Unless required by applicable law or agreed to in writing, software | |

* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT | |

* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | |

* See the License for the specific language governing permissions and | |

* limitations under the License. | |

*/ | |

#ifndef MBEDTLS_CONSTANT_TIME_INTERNAL_H | |

#define MBEDTLS_CONSTANT_TIME_INTERNAL_H | |

#include "common.h" | |

#if defined(MBEDTLS_BIGNUM_C) | |

#include "mbedtls/bignum.h" | |

#endif | |

#if defined(MBEDTLS_SSL_TLS_C) | |

#include "ssl_misc.h" | |

#endif | |

#include <stddef.h> | |

/** Turn a value into a mask: | |

* - if \p value == 0, return the all-bits 0 mask, aka 0 | |

* - otherwise, return the all-bits 1 mask, aka (unsigned) -1 | |

* | |

* This function can be used to write constant-time code by replacing branches | |

* with bit operations using masks. | |

* | |

* \param value The value to analyze. | |

* | |

* \return Zero if \p value is zero, otherwise all-bits-one. | |

*/ | |

unsigned mbedtls_ct_uint_mask( unsigned value ); | |

#if defined(MBEDTLS_SSL_SOME_SUITES_USE_TLS_CBC) | |

/** Turn a value into a mask: | |

* - if \p value == 0, return the all-bits 0 mask, aka 0 | |

* - otherwise, return the all-bits 1 mask, aka (size_t) -1 | |

* | |

* This function can be used to write constant-time code by replacing branches | |

* with bit operations using masks. | |

* | |

* \param value The value to analyze. | |

* | |

* \return Zero if \p value is zero, otherwise all-bits-one. | |

*/ | |

size_t mbedtls_ct_size_mask( size_t value ); | |

#endif /* MBEDTLS_SSL_SOME_SUITES_USE_TLS_CBC */ | |

#if defined(MBEDTLS_BIGNUM_C) | |

/** Turn a value into a mask: | |

* - if \p value == 0, return the all-bits 0 mask, aka 0 | |

* - otherwise, return the all-bits 1 mask, aka (mbedtls_mpi_uint) -1 | |

* | |

* This function can be used to write constant-time code by replacing branches | |

* with bit operations using masks. | |

* | |

* \param value The value to analyze. | |

* | |

* \return Zero if \p value is zero, otherwise all-bits-one. | |

*/ | |

mbedtls_mpi_uint mbedtls_ct_mpi_uint_mask( mbedtls_mpi_uint value ); | |

#endif /* MBEDTLS_BIGNUM_C */ | |

#if defined(MBEDTLS_SSL_SOME_SUITES_USE_TLS_CBC) | |

/** Constant-flow mask generation for "greater or equal" comparison: | |

* - if \p x >= \p y, return all-bits 1, that is (size_t) -1 | |

* - otherwise, return all bits 0, that is 0 | |

* | |

* This function can be used to write constant-time code by replacing branches | |

* with bit operations using masks. | |

* | |

* \param x The first value to analyze. | |

* \param y The second value to analyze. | |

* | |

* \return All-bits-one if \p x is greater or equal than \p y, | |

* otherwise zero. | |

*/ | |

size_t mbedtls_ct_size_mask_ge( size_t x, | |

size_t y ); | |

#endif /* MBEDTLS_SSL_SOME_SUITES_USE_TLS_CBC */ | |

/** Constant-flow boolean "equal" comparison: | |

* return x == y | |

* | |

* This is equivalent to \p x == \p y, but is likely to be compiled | |

* to code using bitwise operation rather than a branch. | |

* | |

* \param x The first value to analyze. | |

* \param y The second value to analyze. | |

* | |

* \return 1 if \p x equals to \p y, otherwise 0. | |

*/ | |

unsigned mbedtls_ct_size_bool_eq( size_t x, | |

size_t y ); | |

#if defined(MBEDTLS_BIGNUM_C) | |

/** Decide if an integer is less than the other, without branches. | |

* | |

* This is equivalent to \p x < \p y, but is likely to be compiled | |

* to code using bitwise operation rather than a branch. | |

* | |

* \param x The first value to analyze. | |

* \param y The second value to analyze. | |

* | |

* \return 1 if \p x is less than \p y, otherwise 0. | |

*/ | |

unsigned mbedtls_ct_mpi_uint_lt( const mbedtls_mpi_uint x, | |

const mbedtls_mpi_uint y ); | |

#endif /* MBEDTLS_BIGNUM_C */ | |

/** Choose between two integer values without branches. | |

* | |

* This is equivalent to `condition ? if1 : if0`, but is likely to be compiled | |

* to code using bitwise operation rather than a branch. | |

* | |

* \param condition Condition to test. | |

* \param if1 Value to use if \p condition is nonzero. | |

* \param if0 Value to use if \p condition is zero. | |

* | |

* \return \c if1 if \p condition is nonzero, otherwise \c if0. | |

*/ | |

unsigned mbedtls_ct_uint_if( unsigned condition, | |

unsigned if1, | |

unsigned if0 ); | |

#if defined(MBEDTLS_BIGNUM_C) | |

/** Conditionally assign a value without branches. | |

* | |

* This is equivalent to `if ( condition ) dest = src`, but is likely | |

* to be compiled to code using bitwise operation rather than a branch. | |

* | |

* \param n \p dest and \p src must be arrays of limbs of size n. | |

* \param dest The MPI to conditionally assign to. This must point | |

* to an initialized MPI. | |

* \param src The MPI to be assigned from. This must point to an | |

* initialized MPI. | |

* \param condition Condition to test, must be 0 or 1. | |

*/ | |

void mbedtls_ct_mpi_uint_cond_assign( size_t n, | |

mbedtls_mpi_uint *dest, | |

const mbedtls_mpi_uint *src, | |

unsigned char condition ); | |

#endif /* MBEDTLS_BIGNUM_C */ | |

#if defined(MBEDTLS_BASE64_C) | |

/** Given a value in the range 0..63, return the corresponding Base64 digit. | |

* | |

* The implementation assumes that letters are consecutive (e.g. ASCII | |

* but not EBCDIC). | |

* | |

* \param value A value in the range 0..63. | |

* | |

* \return A base64 digit converted from \p value. | |

*/ | |

unsigned char mbedtls_ct_base64_enc_char( unsigned char value ); | |

/** Given a Base64 digit, return its value. | |

* | |

* If c is not a Base64 digit ('A'..'Z', 'a'..'z', '0'..'9', '+' or '/'), | |

* return -1. | |

* | |

* The implementation assumes that letters are consecutive (e.g. ASCII | |

* but not EBCDIC). | |

* | |

* \param c A base64 digit. | |

* | |

* \return The value of the base64 digit \p c. | |

*/ | |

signed char mbedtls_ct_base64_dec_value( unsigned char c ); | |

#endif /* MBEDTLS_BASE64_C */ | |

#if defined(MBEDTLS_SSL_SOME_SUITES_USE_TLS_CBC) | |

/** Conditional memcpy without branches. | |

* | |

* This is equivalent to `if ( c1 == c2 ) memcpy(dest, src, len)`, but is likely | |

* to be compiled to code using bitwise operation rather than a branch. | |

* | |

* \param dest The pointer to conditionally copy to. | |

* \param src The pointer to copy from. Shouldn't overlap with \p dest. | |

* \param len The number of bytes to copy. | |

* \param c1 The first value to analyze in the condition. | |

* \param c2 The second value to analyze in the condition. | |

*/ | |

void mbedtls_ct_memcpy_if_eq( unsigned char *dest, | |

const unsigned char *src, | |

size_t len, | |

size_t c1, size_t c2 ); | |

/** Copy data from a secret position with constant flow. | |

* | |

* This function copies \p len bytes from \p src_base + \p offset_secret to \p | |

* dst, with a code flow and memory access pattern that does not depend on \p | |

* offset_secret, but only on \p offset_min, \p offset_max and \p len. | |

* Functionally equivalent to `memcpy(dst, src + offset_secret, 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 The destination buffer. This must point to a writable | |

* buffer of at least \p len bytes. | |

* \param src 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 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 ); | |

/** Compute the HMAC of variable-length data with constant flow. | |

* | |

* This function computes the HMAC of the concatenation of \p add_data and \p | |

* data, and does with a code flow and memory access pattern that does not | |

* depend on \p data_len_secret, but only on \p min_data_len and \p | |

* max_data_len. In particular, this function always reads exactly \p | |

* max_data_len bytes from \p data. | |

* | |

* \param ctx The HMAC context. It must have keys configured | |

* with mbedtls_md_hmac_starts() and use one of the | |

* following hashes: SHA-384, SHA-256, SHA-1 or MD-5. | |

* It is reset using mbedtls_md_hmac_reset() after | |

* the computation is complete to prepare for the | |

* next computation. | |

* \param add_data The first part of the message whose HMAC is being | |

* calculated. This must point to a readable buffer | |

* of \p add_data_len bytes. | |

* \param add_data_len The length of \p add_data in bytes. | |

* \param data The buffer containing the second part of the | |

* message. This must point to a readable buffer | |

* of \p max_data_len bytes. | |

* \param data_len_secret The length of the data to process in \p data. | |

* This must be no less than \p min_data_len and no | |

* greater than \p max_data_len. | |

* \param min_data_len The minimal length of the second part of the | |

* message, read from \p data. | |

* \param max_data_len The maximal length of the second part of the | |

* message, read from \p data. | |

* \param output The HMAC will be written here. This must point to | |

* a writable buffer of sufficient size to hold the | |

* HMAC value. | |

* | |

* \retval 0 on success. | |

* \retval #MBEDTLS_ERR_PLATFORM_HW_ACCEL_FAILED | |

* The hardware accelerator failed. | |

*/ | |

#if defined(MBEDTLS_USE_PSA_CRYPTO) | |

int mbedtls_ct_hmac( mbedtls_svc_key_id_t key, | |

psa_algorithm_t alg, | |

const unsigned char *add_data, | |

size_t add_data_len, | |

const unsigned char *data, | |

size_t data_len_secret, | |

size_t min_data_len, | |

size_t max_data_len, | |

unsigned char *output ); | |

#else | |

int mbedtls_ct_hmac( mbedtls_md_context_t *ctx, | |

const unsigned char *add_data, | |

size_t add_data_len, | |

const unsigned char *data, | |

size_t data_len_secret, | |

size_t min_data_len, | |

size_t max_data_len, | |

unsigned char *output ); | |

#endif /* MBEDTLS_USE_PSA_CRYPTO */ | |

#endif /* MBEDTLS_SSL_SOME_SUITES_USE_TLS_CBC */ | |

#if defined(MBEDTLS_PKCS1_V15) && defined(MBEDTLS_RSA_C) && !defined(MBEDTLS_RSA_ALT) | |

/** This function performs the unpadding part of a PKCS#1 v1.5 decryption | |

* operation (EME-PKCS1-v1_5 decoding). | |

* | |

* \note The return value from this function is a sensitive value | |

* (this is unusual). #MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE shouldn't happen | |

* in a well-written application, but 0 vs #MBEDTLS_ERR_RSA_INVALID_PADDING | |

* is often a situation that an attacker can provoke and leaking which | |

* one is the result is precisely the information the attacker wants. | |

* | |

* \param input The input buffer which is the payload inside PKCS#1v1.5 | |

* encryption padding, called the "encoded message EM" | |

* by the terminology. | |

* \param ilen The length of the payload in the \p input buffer. | |

* \param output The buffer for the payload, called "message M" by the | |

* PKCS#1 terminology. This must be a writable buffer of | |

* length \p output_max_len bytes. | |

* \param olen The address at which to store the length of | |

* the payload. This must not be \c NULL. | |

* \param output_max_len The length in bytes of the output buffer \p output. | |

* | |

* \return \c 0 on success. | |

* \return #MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE | |

* The output buffer is too small for the unpadded payload. | |

* \return #MBEDTLS_ERR_RSA_INVALID_PADDING | |

* The input doesn't contain properly formatted padding. | |

*/ | |

int mbedtls_ct_rsaes_pkcs1_v15_unpadding( unsigned char *input, | |

size_t ilen, | |

unsigned char *output, | |

size_t output_max_len, | |

size_t *olen ); | |

#endif /* MBEDTLS_PKCS1_V15 && MBEDTLS_RSA_C && ! MBEDTLS_RSA_ALT */ | |

#endif /* MBEDTLS_CONSTANT_TIME_INTERNAL_H */ |