Botan::CT Namespace Reference

Classes
class	Choice
class	Mask
class	Option

Concepts
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 *sink, const T *src, size_t elems)
template<typename T >
constexpr Mask< T >	conditional_assign_mem (T cnd, T *sink, const T *src, size_t elems)
template<typename T >
constexpr Mask< T >	conditional_copy_mem (Mask< T > mask, T *to, const T *from0, const T *from1, size_t elems)
template<typename T >
constexpr Mask< T >	conditional_copy_mem (T cnd, T *to, const T *from0, const T *from1, 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_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<typename T > requires std::unsigned_integral<T> && (!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 (T &p)
template<std::integral T>
constexpr void	unpoison (T &p)
template<ranges::spanable_range R> requires std::is_trivially_copyable_v<std::ranges::range_value_t<R>>
constexpr void	poison (R &&r)
template<ranges::spanable_range R> requires std::is_trivially_copyable_v<std::ranges::range_value_t<R>>
constexpr void	unpoison (R &&r)
template<typename T > requires requires(const T& x) { x._const_time_poison(); }
constexpr void	poison (const T &x)
template<typename T > requires requires(const T& x) { x._const_time_unpoison(); }
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 (R &&r)
template<std::ranges::range R> requires unpoisonable<std::ranges::range_value_t<R>>
constexpr void	unpoison_range (R &&r)
template<poisonable... Ts> requires (sizeof...(Ts) > 0)
constexpr void	poison_all (Ts &&... ts)
template<unpoisonable... Ts> requires (sizeof...(Ts) > 0)
constexpr void	unpoison_all (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)

Function Documentation

all_zeros()

template<typename T >

CT::Mask< T > Botan::CT::all_zeros ( const T elem[], size_t len )

inlineconstexpr

Definition at line 775 of file ct_utils.h.

                                                                 {
   T sum = 0;
   for(size_t i = 0; i != len; ++i) {
      sum |= elem[i];
   }
   return CT::Mask<T>::is_zero(sum);
}

References Botan::CT::Mask< T >::is_zero(), and T.

Referenced by Botan::EC_Point::add(), Botan::EC_Point::add_affine(), Botan::Scalar448::bytes_are_reduced(), and Botan::Gf448Elem::is_zero().

conditional_assign_mem() [1/2]

template<typename T >

Mask< T > Botan::CT::conditional_assign_mem ( Choice cnd, T * sink, const T * src, size_t elems )

inlineconstexpr

Definition at line 751 of file ct_utils.h.

                                                                                                 {
   const auto mask = CT::Mask<T>::from_choice(cnd);
   mask.select_n(sink, src, sink, elems);
   return mask;
}

References Botan::CT::Mask< T >::from_choice().

conditional_assign_mem() [2/2]

template<typename T >

Mask< T > Botan::CT::conditional_assign_mem ( T cnd, T * sink, const T * src, size_t elems )

inlineconstexpr

Definition at line 744 of file ct_utils.h.

                                                                                            {
   const auto mask = CT::Mask<T>::expand(cnd);
   mask.select_n(sink, src, sink, elems);
   return mask;
}

References Botan::CT::Mask< T >::expand().

Referenced by Botan::bigint_monty_maybe_sub(), Botan::bigint_monty_maybe_sub(), and Botan::Gf448Elem::ct_cond_assign().

conditional_copy_mem() [1/2]

template<typename T >

Mask< T > Botan::CT::conditional_copy_mem ( Mask< T > mask, T * to, const T * from0, const T * from1, size_t elems )

inlineconstexpr

Definition at line 732 of file ct_utils.h.

                                                                                                                 {
   mask.select_n(to, from0, from1, elems);
   return mask;
}

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().

conditional_copy_mem() [2/2]

template<typename T >

Mask< T > Botan::CT::conditional_copy_mem ( T cnd, T * to, const T * from0, const T * from1, size_t elems )

inlineconstexpr

Definition at line 738 of file ct_utils.h.

                                                                                                          {
   const auto mask = CT::Mask<T>::expand(cnd);
   return CT::conditional_copy_mem(mask, to, from0, from1, elems);
}

References conditional_copy_mem(), and Botan::CT::Mask< T >::expand().

conditional_swap()

template<typename T >

void Botan::CT::conditional_swap ( bool cnd, T & x, T & y )

inlineconstexpr

Definition at line 758 of file ct_utils.h.

                                                             {
   const auto swap = CT::Mask<T>::expand(cnd);
   swap.conditional_swap(x, y);
}

References Botan::CT::Mask< T >::expand().

Referenced by Botan::bigint_sub_abs(), conditional_swap_ptr(), and Botan::Gf448Elem::ct_cond_swap().

conditional_swap_ptr()

template<typename T >

void Botan::CT::conditional_swap_ptr ( bool cnd, T & x, T & y )

inlineconstexpr

Definition at line 764 of file ct_utils.h.

                                                                 {
   uintptr_t xp = reinterpret_cast<uintptr_t>(x);
   uintptr_t yp = reinterpret_cast<uintptr_t>(y);
 
   conditional_swap<uintptr_t>(cnd, xp, yp);
 
   x = reinterpret_cast<T>(xp);
   y = reinterpret_cast<T>(yp);
}

References conditional_swap(), and T.

Referenced by Botan::bigint_sub_abs().

copy_output()

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

• if accept was set or not
• the value of offset
• the value of input

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.

                                                  {
   // This leaks information about the input length, but this happens
   // unavoidably since we are unable to ready any bytes besides those
   // in input[0..n]
   BOTAN_ARG_CHECK(output.size() >= input.size(), "Invalid span lengths");
 
   /*
   * We do not poison the input here because if we did we would have
   * to unpoison it at exit. We assume instead that callers have
   * already poisoned the input and will unpoison it at their own
   * time.
   */
   CT::poison(offset);
 
   /**
   * Zeroize the entire output buffer to get started
   */
   clear_mem(output);
 
   /*
   * If the offset is greater than input length, then the arguments are
   * invalid. Ideally we would throw an exception, but that leaks
   * information about the offset. Instead treat it as if the input
   * was invalid.
   */
   accept = accept && CT::Mask<size_t>::is_lte(offset, input.size()).as_choice();
 
   /*
   * If the input is invalid, then set offset == input_length
   */
   offset = CT::Mask<size_t>::from_choice(accept).select(offset, input.size());
 
   /*
   * Move the desired output bytes to the front using a slow (O^n)
   * but constant time loop that does not leak the value of the offset
   */
   for(size_t i = 0; i != input.size(); ++i) {
      /*
      * If bad_input was set then we modified offset to equal the input_length.
      * In that case, this_loop will be greater than input_length, and so is_eq
      * mask will always be false. As a result none of the input values will be
      * written to output.
      *
      * This is ignoring the possibility of integer overflow of offset + i. But
      * for this to happen the input would have to consume nearly the entire
      * address space.
      */
      const size_t this_loop = offset + i;
 
      /*
      start index from i rather than 0 since we know j must be >= i + offset
      to have any effect, and starting from i does not reveal information
      */
      for(size_t j = i; j != input.size(); ++j) {
         const uint8_t b = input[j];
         const auto is_eq = CT::Mask<size_t>::is_equal(j, this_loop);
         output[i] |= is_eq.if_set_return(b);
      }
   }
 
   // This will always be zero if the input was invalid
   const size_t output_bytes = input.size() - offset;
 
   CT::unpoison_all(output, output_bytes);
 
   return CT::Option<size_t>(output_bytes, accept);
}

References Botan::b, 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().

count_leading_zero_bytes()

size_t Botan::CT::count_leading_zero_bytes

(

std::span< const uint8_t >

input

)

Referenced by strip_leading_zeros().

driveby_poison()

template<poisonable T>
requires (std::is_rvalue_reference_v<decltype(v)>)

decltype(auto) Botan::CT::driveby_poison ( T && v )

nodiscard

Poisons an r-value v and forwards it as the return value.

Definition at line 226 of file ct_utils.h.

{
   poison(v);
   return std::forward<T>(v);
}

References poison().

driveby_unpoison()

template<unpoisonable T>
requires (std::is_rvalue_reference_v<decltype(v)>)

decltype(auto) Botan::CT::driveby_unpoison ( T && v )

nodiscard

Unpoisons an r-value v and forwards it as the return value.

Definition at line 237 of file ct_utils.h.

{
   unpoison(v);
   return std::forward<T>(v);
}

References unpoison().

Referenced by Botan::Classic_McEliece_PublicKeyInternal::create_from_private_key(), Botan::Dilithium_Algos::infinity_norm_within_bound(), and Botan::HSS_LMS_PrivateKey::private_key_bits().

is_equal()

template<typename T >

CT::Mask< T > Botan::CT::is_equal ( const T x[], const T y[], size_t len )

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 788 of file ct_utils.h.

                                                                          {
   if(std::is_constant_evaluated()) {
      T difference = 0;
 
      for(size_t i = 0; i != len; ++i) {
         difference = difference | (x[i] ^ y[i]);
      }
 
      return CT::Mask<T>::is_zero(difference);
   } else {
      volatile T difference = 0;
 
      for(size_t i = 0; i != len; ++i) {
         difference = difference | (x[i] ^ y[i]);
      }
 
      return CT::Mask<T>::is_zero(difference);
   }
}

References Botan::CT::Mask< T >::is_zero(), and T.

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::Kyber_KEM_Decryptor::decapsulate(), Botan::ML_KEM_Decryptor::decapsulate(), Botan::TLS::Session::decrypt(), Botan::CryptoBox::decrypt_bin(), Botan::ed25519_verify(), is_not_equal(), Botan::EC_AffinePoint::operator==(), Botan::Gf448Elem::operator==(), Botan::Classic_McEliece_Decryptor::raw_kem_decrypt(), Botan::RTSS_Share::reconstruct(), Botan::Sodium::sodium_memcmp(), Botan::TLS::Finished_12::verify(), and Botan::MessageAuthenticationCode::verify_mac_result().

is_not_equal()

template<typename T >

CT::Mask< T > Botan::CT::is_not_equal ( const T x[], const T y[], size_t len )

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 813 of file ct_utils.h.

                                                                              {
   return ~CT::is_equal(x, y, len);
}

References is_equal().

Referenced by Botan::Sodium::crypto_secretbox_xsalsa20poly1305_open(), and Botan::oaep_find_delim().

poison() [1/5]

template<typename T >
requires requires(const T& v) { ::Botan::CT::poison(v); }

void Botan::CT::poison ( const std::optional< T > & x )

constexpr

Poison an optional object if it has a value.

Definition at line 146 of file ct_utils.h.

                                               {
   if(x.has_value()) {
      poison(x.value());
   }
}

References poison().

poison() [2/5]

template<typename T >
requires requires(const T& x) { x._const_time_poison(); }

void Botan::CT::poison ( const T & x )

constexpr

Poison a class type that provides a public _const_time_poison() method For instance: BigInt, CT::Mask<>, FrodoMatrix, ...

Definition at line 131 of file ct_utils.h.

                                  {
   x._const_time_poison();
}

poison() [3/5]

template<typename T >

void Botan::CT::poison ( const T * p, size_t n )

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 53 of file ct_utils.h.

                                                   {
#if defined(BOTAN_HAS_VALGRIND)
   if(!std::is_constant_evaluated()) {
      VALGRIND_MAKE_MEM_UNDEFINED(p, n * sizeof(T));
   }
#endif
 
   BOTAN_UNUSED(p, n);
}

References BOTAN_UNUSED, and T.

Referenced by Botan::bitvector_base< AllocatorT >::_const_time_poison(), Botan::CRYSTALS::Polynomial< Trait, D >::_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::ANSI_X923_Padding::add_padding(), Botan::ESP_Padding::add_padding(), Botan::OneAndZeros_Padding::add_padding(), Botan::PKCS7_Padding::add_padding(), Botan::BOTAN_FUNC_ISA(), Botan::Classic_McEliece_PrivateKey::Classic_McEliece_PrivateKey(), copy_output(), Botan::curve25519_donna(), driveby_poison(), Botan::Kyber_KEM_Encryptor::encapsulate(), Botan::Dilithium_Algos::expand_keypair(), Botan::Kyber_Algos::expand_keypair(), poison(), poison(), poison(), poison_all(), poison_range(), Botan::ANSI_X923_Padding::unpad(), Botan::ESP_Padding::unpad(), Botan::OneAndZeros_Padding::unpad(), and Botan::PKCS7_Padding::unpad().

poison() [4/5]

template<ranges::spanable_range R>
requires std::is_trivially_copyable_v<std::ranges::range_value_t<R>>

void Botan::CT::poison ( R && r )

constexpr

Poison a contiguous buffer of trivial objects (e.g. integers and such)

Definition at line 113 of file ct_utils.h.

                             {
   std::span s{r};
   poison(s.data(), s.size());
}

References poison().

poison() [5/5]

template<std::integral T>

void Botan::CT::poison ( T & p )

constexpr

Poison a single integral object

Definition at line 99 of file ct_utils.h.

                            {
   poison(&p, 1);
}

References poison().

poison_all()

template<poisonable... Ts>
requires (sizeof...(Ts) > 0)

void Botan::CT::poison_all ( Ts &&... ts )

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 195 of file ct_utils.h.

                                      {
   (poison(ts), ...);
}

References poison().

Referenced by Botan::Dilithium_PrivateKeyInternal::_const_time_poison(), Botan::Kyber_PrivateKeyInternal::_const_time_poison(), Botan::FrodoKEM_PrivateKey::FrodoKEM_PrivateKey(), Botan::gcd(), and scoped_poison().

poison_has_effect()

bool Botan::CT::poison_has_effect ( )

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.

Returns

true if CT::poison() and CT::unpoison() are effective

Definition at line 82 of file ct_utils.h.

                                {
#if defined(BOTAN_HAS_VALGRIND)
   return RUNNING_ON_VALGRIND;
#else
   return false;
#endif
}

poison_range()

template<std::ranges::range R>
requires poisonable<std::ranges::range_value_t<R>>

void Botan::CT::poison_range ( R && r )

constexpr

Poison a range of objects by calling poison on each element.

Definition at line 175 of file ct_utils.h.

                                   {
   for(const auto& v : r) {
      poison(v);
   }
}

References poison().

Referenced by Botan::CRYSTALS::PolynomialMatrix< Trait >::_const_time_poison(), and Botan::CRYSTALS::PolynomialVector< Trait, D >::_const_time_poison().

scoped_poison()

template<typename... Ts>
requires (sizeof...(Ts) > 0) && (poisonable<Ts> && ...) && (unpoisonable<Ts> && ...)

auto Botan::CT::scoped_poison ( const Ts &... xs )

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 216 of file ct_utils.h.

                                                            {
   auto scope = scoped_cleanup([&] { unpoison_all(xs...); });
   poison_all(xs...);
   return scope;
}

References poison_all(), and unpoison_all().

Referenced by Botan::X448_PrivateKey::check_key(), Botan::Classic_McEliece_PrivateKey::Classic_McEliece_PrivateKey(), Botan::Kyber_KEM_Decryptor::decapsulate(), Botan::ML_KEM_Decryptor::decapsulate(), Botan::Kyber_Expanded_Keypair_Codec::decode_keypair(), Botan::Ed448_PrivateKey::Ed448_PrivateKey(), Botan::ML_KEM_Encryptor::encapsulate(), Botan::Kyber_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(), and Botan::X448_PrivateKey::X448_PrivateKey().

strip_leading_zeros()

secure_vector< uint8_t > Botan::CT::strip_leading_zeros

(

std::span< const uint8_t >

input

)

Definition at line 94 of file ct_utils.cpp.

                                                                           {
   const size_t leading_zeros = CT::count_leading_zero_bytes(input);
 
   secure_vector<uint8_t> output(input.size());
 
   const auto written = CT::copy_output(CT::Choice::yes(), output, input, leading_zeros);
 
   /*
   This is potentially not const time, depending on how std::vector is
   implemented. But since we are always reducing length, it should
   just amount to setting the member var holding the length.
   */
   output.resize(written.value_or(0));
 
   return output;
}

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().

unpoison() [1/5]

template<typename T >
requires requires(const T& v) { ::Botan::CT::unpoison(v); }

void Botan::CT::unpoison ( const std::optional< T > & x )

constexpr

Definition at line 154 of file ct_utils.h.

                                                 {
   if(x.has_value()) {
      unpoison(x.value());
   }
}

References unpoison().

unpoison() [2/5]

template<typename T >
requires requires(const T& x) { x._const_time_unpoison(); }

void Botan::CT::unpoison ( const T & x )

constexpr

Definition at line 137 of file ct_utils.h.

                                    {
   x._const_time_unpoison();
}

unpoison() [3/5]

template<typename T >

void Botan::CT::unpoison ( const T * p, size_t n )

inlineconstexpr

Definition at line 64 of file ct_utils.h.

                                                     {
#if defined(BOTAN_HAS_VALGRIND)
   if(!std::is_constant_evaluated()) {
      VALGRIND_MAKE_MEM_DEFINED(p, n * sizeof(T));
   }
#endif
 
   BOTAN_UNUSED(p, n);
}

References BOTAN_UNUSED, and T.

Referenced by Botan::bitvector_base< AllocatorT >::_const_time_unpoison(), Botan::CRYSTALS::Polynomial< Trait, D >::_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::ANSI_X923_Padding::add_padding(), Botan::ESP_Padding::add_padding(), Botan::OneAndZeros_Padding::add_padding(), Botan::PKCS7_Padding::add_padding(), Botan::bigint_cmp(), Botan::BOTAN_FUNC_ISA(), 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::Ed448_PrivateKey::Ed448_PrivateKey(), Botan::Kyber_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::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(), Botan::ANSI_X923_Padding::unpad(), Botan::ESP_Padding::unpad(), Botan::OneAndZeros_Padding::unpad(), Botan::PKCS7_Padding::unpad(), unpoison(), unpoison(), unpoison(), unpoison_all(), unpoison_range(), Botan::CT::Mask< T >::unpoisoned_value(), and Botan::X448_PrivateKey::X448_PrivateKey().

unpoison() [4/5]

template<ranges::spanable_range R>
requires std::is_trivially_copyable_v<std::ranges::range_value_t<R>>

void Botan::CT::unpoison ( R && r )

constexpr

Definition at line 120 of file ct_utils.h.

                               {
   std::span s{r};
   unpoison(s.data(), s.size());
}

References unpoison().

unpoison() [5/5]

template<std::integral T>

void Botan::CT::unpoison ( T & p )

constexpr

Definition at line 104 of file ct_utils.h.

                              {
   unpoison(&p, 1);
}

References unpoison().

unpoison_all()

template<unpoisonable... Ts>
requires (sizeof...(Ts) > 0)

void Botan::CT::unpoison_all ( Ts &&... ts )

constexpr

Definition at line 201 of file ct_utils.h.

                                        {
   (unpoison(ts), ...);
}

References unpoison().

Referenced by Botan::Dilithium_PrivateKeyInternal::_const_time_unpoison(), Botan::Kyber_PrivateKeyInternal::_const_time_unpoison(), Botan::Classic_McEliece_PrivateKey::Classic_McEliece_PrivateKey(), Botan::Classic_McEliece_PrivateKey::Classic_McEliece_PrivateKey(), copy_output(), Botan::Kyber_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().

unpoison_range()

template<std::ranges::range R>
requires unpoisonable<std::ranges::range_value_t<R>>

void Botan::CT::unpoison_range ( R && r )

constexpr

Definition at line 183 of file ct_utils.h.

                                     {
   for(const auto& v : r) {
      unpoison(v);
   }
}

References unpoison().

Referenced by Botan::CRYSTALS::PolynomialMatrix< Trait >::_const_time_unpoison(), and Botan::CRYSTALS::PolynomialVector< Trait, D >::_const_time_unpoison().

value_barrier()

template<typename T >
requires std::unsigned_integral<T> && (!std::same_as<bool, T>)

T Botan::CT::value_barrier ( T x )

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:

• asm: Use an inline assembly expression which (currently) prevents Clang and GCC from optimizing based on the possible value of the input expression.
• volatile: Launder the input through a volatile variable. This is likely to cause significant performance regressions since the value must be actually stored and loaded back from memory each time.
• none: disable constant time barriers entirely. This is used with MSVC, which is not known to perform optimizations that break constant time code and which does not support GCC-style inline asm.

Definition at line 272 of file ct_utils.h.

{
   if(std::is_constant_evaluated()) {
      return x;
   } else {
#if defined(BOTAN_CT_VALUE_BARRIER_USE_ASM)
      /*
      * We may want a "stronger" statement such as
      *     asm volatile("" : "+r,m"(x) : : "memory);
      * (see https://theunixzoo.co.uk/blog/2021-10-14-preventing-optimisations.html)
      * however the current approach seems sufficient with current compilers,
      * and is minimally damaging with regards to degrading code generation.
      */
      asm("" : "+r"(x) : /* no input */);
      return x;
#elif defined(BOTAN_CT_VALUE_BARRIER_USE_VOLATILE)
      volatile T vx = x;
      return vx;
#else
      return x;
#endif
   }
}

References T.

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().