Botan 3.9.0
Crypto and TLS for C&
|
Classes | |
class | Choice |
class | Mask |
class | Option |
Concepts | |
concept | custom_poisonable |
concept | custom_unpoisonable |
concept | poisonable |
concept | unpoisonable |
concept | ct_conditional_assignable |
Functions | |
template<typename T> | |
constexpr CT::Mask< T > | all_zeros (const T elem[], size_t len) |
template<typename T> | |
constexpr Mask< T > | conditional_assign_mem (Choice cnd, T *dest, const T *src, size_t elems) |
template<typename T> | |
constexpr Mask< T > | conditional_assign_mem (T cnd, T *dest, const T *src, size_t elems) |
template<typename T> | |
constexpr Mask< T > | conditional_copy_mem (Mask< T > mask, T *dest, const T *if_set, const T *if_unset, size_t elems) |
template<typename T> | |
constexpr Mask< T > | conditional_copy_mem (T cnd, T *dest, const T *if_set, const T *if_unset, size_t elems) |
template<typename T> | |
constexpr void | conditional_swap (bool cnd, T &x, T &y) |
template<typename T> | |
constexpr void | conditional_swap_ptr (bool cnd, T &x, T &y) |
BOTAN_TEST_API CT::Option< size_t > | copy_output (CT::Choice accept, std::span< uint8_t > output, std::span< const uint8_t > input, size_t offset) |
size_t | count_leading_zero_bytes (std::span< const uint8_t > input) |
template<typename T> | |
constexpr CT::Mask< T > | is_equal (const T x[], const T y[], size_t len) |
template<typename T> | |
constexpr CT::Mask< T > | is_equal (std::span< const T > x, std::span< const T > y) |
template<typename T> | |
constexpr CT::Mask< T > | is_not_equal (const T x[], const T y[], size_t len) |
secure_vector< uint8_t > | strip_leading_zeros (std::span< const uint8_t > input) |
template<std::unsigned_integral T> requires (!std::same_as<bool, T>) | |
constexpr T | value_barrier (T x) |
Constant Time Check Annotation Helpers | |
template<typename T> | |
constexpr void | poison (const T *p, size_t n) |
template<typename T> | |
constexpr void | unpoison (const T *p, size_t n) |
bool | poison_has_effect () |
Constant Time Check Annotation Convenience overloads | |
template<std::integral T> | |
constexpr void | poison (const T &p) |
template<std::integral T> | |
constexpr void | unpoison (const T &p) |
template<ranges::spanable_range R> requires std::is_trivially_copyable_v<std::ranges::range_value_t<R>> && (!custom_poisonable<R>) | |
constexpr void | poison (const R &r) |
template<ranges::spanable_range R> requires std::is_trivially_copyable_v<std::ranges::range_value_t<R>> && (!custom_unpoisonable<R>) | |
constexpr void | unpoison (const R &r) |
template<custom_poisonable T> | |
constexpr void | poison (const T &x) |
template<custom_unpoisonable T> | |
constexpr void | unpoison (const T &x) |
template<typename T> requires requires(const T& v) { ::Botan::CT::poison(v); } | |
constexpr void | poison (const std::optional< T > &x) |
template<typename T> requires requires(const T& v) { ::Botan::CT::unpoison(v); } | |
constexpr void | unpoison (const std::optional< T > &x) |
Higher-level Constant Time Check Annotation Helpers | |
template<std::ranges::range R> requires poisonable<std::ranges::range_value_t<R>> | |
constexpr void | poison_range (const R &r) |
template<std::ranges::range R> requires unpoisonable<std::ranges::range_value_t<R>> | |
constexpr void | unpoison_range (const R &r) |
template<poisonable... Ts> requires (sizeof...(Ts) > 0) | |
constexpr void | poison_all (const Ts &... ts) |
template<unpoisonable... Ts> requires (sizeof...(Ts) > 0) | |
constexpr void | unpoison_all (const Ts &... ts) |
template<typename... Ts> requires (sizeof...(Ts) > 0) && (poisonable<Ts> && ...) && (unpoisonable<Ts> && ...) | |
constexpr auto | scoped_poison (const Ts &... xs) |
template<poisonable T> requires (std::is_rvalue_reference_v<decltype(v)>) | |
decltype(auto) | driveby_poison (T &&v) |
template<unpoisonable T> requires (std::is_rvalue_reference_v<decltype(v)>) | |
decltype(auto) | driveby_unpoison (T &&v) |
|
inlineconstexpr |
Definition at line 813 of file ct_utils.h.
References Botan::CT::Mask< T >::is_zero().
Referenced by Botan::EC_Point::add(), Botan::EC_Point::add_affine(), Botan::Scalar448::bytes_are_reduced(), Botan::Ed25519_FieldElement::is_zero(), Botan::Gf448Elem::is_zero(), and Botan::IntMod< MontgomeryRep< ScalarParams > >::is_zero().
|
inlineconstexpr |
Conditional memory assignment (constant time)
If mask is set overwrites dest with src
Definition at line 789 of file ct_utils.h.
References Botan::CT::Mask< T >::from_choice().
|
inlineconstexpr |
Conditional memory assignment (constant time)
If mask is set overwrites dest with src
Definition at line 777 of file ct_utils.h.
References Botan::CT::Mask< T >::expand().
Referenced by Botan::bigint_monty_maybe_sub(), Botan::bigint_monty_maybe_sub(), Botan::Gf448Elem::ct_cond_assign(), and Botan::redc_crandall().
|
inlineconstexpr |
Conditional memory copy (constant time)
If mask is set, then sets dest to if_set, otherwise sets dest to if_unset
Definition at line 760 of file ct_utils.h.
References Botan::CT::Mask< T >::select_n().
Referenced by Botan::bigint_sub_abs(), conditional_copy_mem(), Botan::Kyber_KEM_Decryptor::decapsulate(), Botan::ML_KEM_Decryptor::decapsulate(), and Botan::BigInt::mod_add().
|
inlineconstexpr |
Definition at line 766 of file ct_utils.h.
References conditional_copy_mem(), and Botan::CT::Mask< T >::expand().
|
inlineconstexpr |
Definition at line 796 of file ct_utils.h.
References Botan::CT::Mask< T >::expand().
Referenced by conditional_swap_ptr(), and Botan::Gf448Elem::ct_cond_swap().
|
inlineconstexpr |
Definition at line 802 of file ct_utils.h.
References conditional_swap().
CT::Option< size_t > Botan::CT::copy_output | ( | CT::Choice | accept, |
std::span< uint8_t > | output, | ||
std::span< const uint8_t > | input, | ||
size_t | offset ) |
Constant time conditional copy out with offset
If accept is set and offset <= input_length, sets output[0..] to input[offset:input_length] and returns input_length - offset. The remaining bytes of output are zeroized.
Otherwise, output is zeroized, and returns an empty Ct::Option
The input and output spans may not overlap, and output must be at least as large as input.
This function attempts to avoid leaking the following to side channels
This function leaks the length of the input
Zeroize the entire output buffer to get started
Definition at line 13 of file ct_utils.cpp.
References BOTAN_ARG_CHECK, Botan::clear_mem(), Botan::CT::Mask< T >::from_choice(), Botan::CT::Mask< T >::is_equal(), Botan::CT::Mask< T >::is_lte(), poison(), and unpoison_all().
Referenced by strip_leading_zeros().
size_t Botan::CT::count_leading_zero_bytes | ( | std::span< const uint8_t > | input | ) |
Definition at line 84 of file ct_utils.cpp.
References Botan::CT::Mask< T >::is_zero(), and Botan::CT::Mask< T >::set().
Referenced by strip_leading_zeros().
|
nodiscard |
Poisons an r-value v
and forwards it as the return value.
Definition at line 230 of file ct_utils.h.
References poison().
|
nodiscard |
Unpoisons an r-value v
and forwards it as the return value.
Definition at line 241 of file ct_utils.h.
References unpoison().
Referenced by Botan::Classic_McEliece_PublicKeyInternal::create_from_private_key(), Botan::Dilithium_Algos::infinity_norm_within_bound(), Botan::HSS_LMS_PrivateKey::private_key_bits(), and Botan::BlockCipherModePaddingMethod::unpad().
|
inlineconstexpr |
Compare two arrays of equal size and return a Mask indicating if they are equal or not. The mask is set if they are identical.
Definition at line 826 of file ct_utils.h.
References Botan::CT::Mask< T >::is_zero().
Referenced by Botan::argon2_check_pwhash(), botan_constant_time_compare(), Botan::Gf448Elem::bytes_are_canonical_representation(), Botan::check_bcrypt(), Botan::Classic_McEliece_PrivateKeyInternal::check_key(), Botan::Ed25519_PublicKey::check_key(), Botan::X448_PrivateKey::check_key(), Botan::check_passhash9(), Botan::constant_time_compare(), Botan::FrodoMatrix::constant_time_compare(), Botan::Sodium::crypto_secretbox_open_detached(), Botan::Sodium::crypto_verify_16(), Botan::Sodium::crypto_verify_32(), Botan::Sodium::crypto_verify_64(), Botan::ct_compare_u8(), Botan::Classic_McEliece_Field_Ordering::ct_is_equal(), Botan::Kyber_KEM_Decryptor::decapsulate(), Botan::ML_KEM_Decryptor::decapsulate(), Botan::TLS::Session::decrypt(), Botan::CryptoBox::decrypt_bin(), is_equal(), is_not_equal(), Botan::EC_AffinePoint::operator==(), Botan::Gf448Elem::operator==(), Botan::IntMod< MontgomeryRep< ScalarParams > >::operator==(), Botan::Classic_McEliece_Decryptor::raw_kem_decrypt(), Botan::RTSS_Share::reconstruct(), Botan::signature_check(), Botan::Sodium::sodium_memcmp(), Botan::TLS::Finished_12::verify(), and Botan::MessageAuthenticationCode::verify_mac_result().
|
inlineconstexpr |
Compare two spans and return a Mask which is set iff they were identical.
If the spans are of different length then the function returns early without looking at either span
Definition at line 853 of file ct_utils.h.
References Botan::CT::Mask< T >::cleared(), and is_equal().
|
inlineconstexpr |
Compare two arrays of equal size and return a Mask indicating if they are equal or not. The mask is set if they differ.
Definition at line 866 of file ct_utils.h.
References is_equal().
Referenced by Botan::Sodium::crypto_secretbox_xsalsa20poly1305_open(), and Botan::oaep_find_delim().
|
constexpr |
Poison a contiguous buffer of trivial objects (e.g. integers and such)
Definition at line 119 of file ct_utils.h.
References poison().
|
constexpr |
Poison an optional object if it has a value.
Definition at line 150 of file ct_utils.h.
References poison().
|
constexpr |
|
constexpr |
Poison a class type that provides a public _const_time_poison() method For instance: BigInt, CT::Mask<>, FrodoMatrix, ...
Definition at line 136 of file ct_utils.h.
|
inlineconstexpr |
Use valgrind to mark the contents of memory as being undefined. Valgrind will accept operations which manipulate undefined values, but will warn if an undefined value is used to decided a conditional jump or a load/store address. So if we poison all of our inputs we can confirm that the operations in question are truly const time when compiled by whatever compiler is in use.
Even better, the VALGRIND_MAKE_MEM_* macros work even when the program is not run under valgrind (though with a few cycles of overhead, which is unfortunate in final binaries as these annotations tend to be used in fairly important loops).
This approach was first used in ctgrind (https://github.com/agl/ctgrind) but calling the valgrind mecheck API directly works just as well and doesn't require a custom patched valgrind.
Definition at line 54 of file ct_utils.h.
References BOTAN_UNUSED.
Referenced by Botan::BigInt::_const_time_poison(), Botan::bitvector_base< secure_allocator >::_const_time_poison(), Botan::Classic_McEliece_Field_Ordering::_const_time_poison(), Botan::Classic_McEliece_Polynomial::_const_time_poison(), Botan::CRYSTALS::Polynomial< DilithiumPolyTraits, Botan::CRYSTALS::Domain::NTT >::_const_time_poison(), Botan::CT::Mask< T >::_const_time_poison(), Botan::Dilithium_PrivateKeyInternal::_const_time_poison(), Botan::FrodoMatrix::_const_time_poison(), Botan::HSS_LMS_PrivateKeyInternal::_const_time_poison(), Botan::IntMod< MontgomeryRep< ScalarParams > >::_const_time_poison(), Botan::Montgomery_Int::_const_time_poison(), Botan::basemul_exec(), Botan::BlindedScalarBits< C, WindowBits+1 >::BlindedScalarBits(), Botan::Classic_McEliece_PrivateKey::Classic_McEliece_PrivateKey(), copy_output(), Botan::curve25519_donna(), driveby_poison(), Botan::ed25519_basepoint_mul(), Botan::Kyber_KEM_Encryptor::encapsulate(), Botan::Dilithium_Algos::expand_keypair(), Botan::Kyber_Algos::expand_keypair(), Botan::map_to_curve_sswu(), Botan::WindowedBoothMulTable< C, W >::mul(), Botan::mul2_exec(), poison(), poison(), poison(), poison_all(), poison_range(), and Botan::varpoint_exec().
|
constexpr |
Poisons an arbitrary number of values in a single call. Mostly syntactic sugar to save clutter (i.e. lines-of-code).
Definition at line 199 of file ct_utils.h.
References poison().
Referenced by Botan::AffineCurvePoint< FieldElement, Params >::_const_time_poison(), Botan::Classic_McEliece_PrivateKeyInternal::_const_time_poison(), Botan::Dilithium_PrivateKeyInternal::_const_time_poison(), Botan::Kyber_PrivateKeyInternal::_const_time_poison(), Botan::ProjectiveCurvePoint< FieldElement, Params >::_const_time_poison(), Botan::FrodoKEM_PrivateKey::FrodoKEM_PrivateKey(), Botan::gcd(), and scoped_poison().
|
inline |
Checks whether CT::poison() and CT::unpoison() actually have an effect.
If the build is not instrumented and/or not run using an analysis tool like valgrind, the functions are no-ops and the return value is false.
Definition at line 83 of file ct_utils.h.
|
constexpr |
Poison a range of objects by calling poison on each element.
Definition at line 179 of file ct_utils.h.
References poison().
Referenced by Botan::CRYSTALS::PolynomialMatrix< DilithiumPolyTraits >::_const_time_poison(), and Botan::CRYSTALS::PolynomialVector< DilithiumPolyTraits, Botan::CRYSTALS::Domain::NTT >::_const_time_poison().
|
nodiscardconstexpr |
Poisons an arbitrary number of poisonable values, and unpoisons them when the returned object runs out-of-scope
Use this when you want to poison a value that remains valid longer than the scope you are currently in. For instance, a private key structure that is a member of a Signature_Operation object, that may be used for multiple signatures.
Definition at line 220 of file ct_utils.h.
References poison_all(), and unpoison_all().
Referenced by Botan::BlockCipherModePaddingMethod::add_padding(), Botan::X448_PrivateKey::check_key(), Botan::Classic_McEliece_PrivateKey::Classic_McEliece_PrivateKey(), Botan::Kyber_KEM_Decryptor::decapsulate(), Botan::ML_KEM_Decryptor::decapsulate(), Botan::Expanded_Keypair_Codec::decode_keypair(), Botan::Ed448_PrivateKey::Ed448_PrivateKey(), Botan::ML_KEM_Encryptor::encapsulate(), Botan::Expanded_Keypair_Codec::encode_keypair(), Botan::HSS_LMS_PrivateKey::HSS_LMS_PrivateKey(), Botan::HSS_LMS_PrivateKey::HSS_LMS_PrivateKey(), Botan::HSS_LMS_PrivateKey::private_key_bits(), Botan::Classic_McEliece_Decryptor::raw_kem_decrypt(), Botan::BlockCipherModePaddingMethod::unpad(), and Botan::X448_PrivateKey::X448_PrivateKey().
secure_vector< uint8_t > Botan::CT::strip_leading_zeros | ( | std::span< const uint8_t > | input | ) |
Definition at line 94 of file ct_utils.cpp.
References copy_output(), count_leading_zero_bytes(), and Botan::CT::Choice::yes().
Referenced by Botan::TLS::Client_Key_Exchange::Client_Key_Exchange(), and Botan::TLS::Client_Key_Exchange::Client_Key_Exchange().
|
constexpr |
Definition at line 126 of file ct_utils.h.
References unpoison().
|
constexpr |
Definition at line 158 of file ct_utils.h.
References unpoison().
|
constexpr |
|
constexpr |
Definition at line 141 of file ct_utils.h.
|
inlineconstexpr |
Definition at line 65 of file ct_utils.h.
References BOTAN_UNUSED.
Referenced by Botan::BigInt::_const_time_unpoison(), Botan::bitvector_base< secure_allocator >::_const_time_unpoison(), Botan::Classic_McEliece_Field_Ordering::_const_time_unpoison(), Botan::Classic_McEliece_Matrix::_const_time_unpoison(), Botan::Classic_McEliece_Polynomial::_const_time_unpoison(), Botan::Classic_McEliece_PublicKeyInternal::_const_time_unpoison(), Botan::CRYSTALS::Polynomial< DilithiumPolyTraits, Botan::CRYSTALS::Domain::NTT >::_const_time_unpoison(), Botan::CT::Mask< T >::_const_time_unpoison(), Botan::Dilithium_PrivateKeyInternal::_const_time_unpoison(), Botan::FrodoMatrix::_const_time_unpoison(), Botan::HSS_LMS_PrivateKeyInternal::_const_time_unpoison(), Botan::HSS_LMS_PublicKeyInternal::_const_time_unpoison(), Botan::IntMod< MontgomeryRep< ScalarParams > >::_const_time_unpoison(), Botan::LMS_PublicKey::_const_time_unpoison(), Botan::Montgomery_Int::_const_time_unpoison(), Botan::basemul_exec(), Botan::bigint_cmp(), Botan::Classic_McEliece_Matrix::Classic_McEliece_Matrix(), Botan::Classic_McEliece_Polynomial_Ring::compute_minimal_polynomial(), Botan::Classic_McEliece_Matrix::create_matrix(), Botan::Classic_McEliece_Matrix::create_matrix_and_apply_pivots(), Botan::curve25519_donna(), Botan::Kyber_KEM_Decryptor::decapsulate(), Botan::ML_KEM_Decryptor::decapsulate(), driveby_unpoison(), Botan::ed25519_basepoint_mul(), Botan::Ed448_PrivateKey::Ed448_PrivateKey(), Botan::Expanded_Keypair_Codec::encode_keypair(), Botan::Dilithium_Algos::expand_keypair(), Botan::Kyber_Algos::expand_keypair(), Botan::HSS_LMS_PrivateKey::HSS_LMS_PrivateKey(), Botan::HSS_LMS_PrivateKey::HSS_LMS_PrivateKey(), Botan::map_to_curve_sswu(), Botan::WindowedBoothMulTable< C, W >::mul(), Botan::mul2_exec(), Botan::Classic_McEliece_Decryptor::raw_kem_decrypt(), Botan::CT::Mask< T >::select_and_unpoison(), Botan::LMOTS_Private_Key::sign(), Botan::LMS_PrivateKey::sign_and_get_pk(), Botan::BigInt::top_bits_free(), unpoison(), unpoison(), unpoison(), unpoison_all(), unpoison_range(), Botan::CT::Mask< T >::unpoisoned_value(), Botan::varpoint_exec(), Botan::X448_PrivateKey::X448_PrivateKey(), and Botan::BlindedScalarBits< C, WindowBits+1 >::~BlindedScalarBits().
|
constexpr |
Definition at line 205 of file ct_utils.h.
References unpoison().
Referenced by Botan::AffineCurvePoint< FieldElement, Params >::_const_time_unpoison(), Botan::Classic_McEliece_PrivateKeyInternal::_const_time_unpoison(), Botan::Dilithium_PrivateKeyInternal::_const_time_unpoison(), Botan::Kyber_PrivateKeyInternal::_const_time_unpoison(), Botan::ProjectiveCurvePoint< FieldElement, Params >::_const_time_unpoison(), Botan::Classic_McEliece_PrivateKey::Classic_McEliece_PrivateKey(), Botan::Classic_McEliece_PrivateKey::Classic_McEliece_PrivateKey(), copy_output(), Botan::Expanded_Keypair_Codec::decode_keypair(), Botan::Kyber_KEM_Encryptor::encapsulate(), Botan::ML_KEM_Encryptor::encapsulate(), Botan::Kyber_Algos::expand_keypair(), Botan::FrodoKEM_PrivateKey::FrodoKEM_PrivateKey(), Botan::gcd(), Botan::Classic_McEliece_Encryptor::raw_kem_encrypt(), and scoped_poison().
|
constexpr |
Definition at line 187 of file ct_utils.h.
References unpoison().
Referenced by Botan::CRYSTALS::PolynomialMatrix< DilithiumPolyTraits >::_const_time_unpoison(), and Botan::CRYSTALS::PolynomialVector< DilithiumPolyTraits, Botan::CRYSTALS::Domain::NTT >::_const_time_unpoison().
|
inlineconstexpr |
This function returns its argument, but (if called in a non-constexpr context) attempts to prevent the compiler from reasoning about the value or the possible range of values. Such optimizations have a way of breaking constant time code.
The method that is use is decided at configuration time based on the target compiler and architecture (see ct_value_barrier blocks in src/build-data/cc). The decision can be overridden by the user with the configure.py option --ct-value-barrier-type=
There are three options currently possible in the data files and with the option:
Definition at line 277 of file ct_utils.h.
Referenced by Botan::CT::Mask< T >::expand(), Botan::CT::Mask< T >::expand_top_bit(), Botan::CT::Choice::from_int(), Botan::CT::Mask< T >::is_any_of(), Botan::CT::Mask< T >::is_equal(), Botan::CT::Mask< T >::is_within_range(), Botan::CT::Mask< T >::is_zero(), Botan::Classic_McEliece_GF::operator*(), Botan::FrodoMatrix::sample(), Botan::BigInt::top_bits_free(), Botan::CT::Choice::value(), and Botan::CT::Mask< T >::value().