Botan::CT Namespace Reference

Classes
class	Mask

Functions
template<typename T >
Mask< T >	conditional_copy_mem (T cnd, T *to, const T *from0, const T *from1, size_t elems)
template<typename T >
void	conditional_swap (bool cnd, T &x, T &y)
template<typename T >
void	conditional_swap_ptr (bool cnd, T &x, T &y)
secure_vector< uint8_t >	copy_output (CT::Mask< uint8_t > bad_input_u8, const uint8_t input[], size_t input_length, size_t offset)
template<typename T >
void	poison (const T *p, size_t n)
secure_vector< uint8_t >	strip_leading_zeros (const secure_vector< uint8_t > &in)
secure_vector< uint8_t >	strip_leading_zeros (const uint8_t in[], size_t length)
template<typename T >
void	unpoison (const T *p, size_t n)
template<typename T >
void	unpoison (T &p)

Function Documentation

conditional_copy_mem()

template<typename T >

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

inline

Definition at line 360 of file ct_utils.h.

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

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

Referenced by Botan::bigint_monty_redc_16(), Botan::bigint_monty_redc_24(), Botan::bigint_monty_redc_32(), Botan::bigint_monty_redc_4(), Botan::bigint_monty_redc_6(), Botan::bigint_monty_redc_8(), Botan::bigint_monty_redc_generic(), and Botan::BigInt::mod_add().

conditional_swap()

template<typename T >

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

inline

Definition at line 372 of file ct_utils.h.

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

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

Referenced by Botan::bigint_sub_abs().

conditional_swap_ptr()

template<typename T >

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

inline

Definition at line 383 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 T.

Referenced by Botan::bigint_sub_abs().

copy_output()

BOTAN_TEST_API secure_vector< uint8_t > Botan::CT::copy_output	(	CT::Mask< uint8_t >	bad_input,
		const uint8_t	input[],
		size_t	input_length,
		size_t	offset
	)

If bad_input is unset, return input[offset:input_length] copied to new buffer. If bad_input is set, return an empty vector. In all cases, the capacity of the vector is equal to input_length

This function attempts to avoid leaking the following:

• if bad_input was set or not
• the value of offset
• the values in input[]

This function leaks the value of input_length

Definition at line 11 of file ct_utils.cpp.

   {
   /*
   * 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, sizeof(size_t));
 
   secure_vector<uint8_t> output(input_length);
 
   auto bad_input = CT::Mask<size_t>::expand(bad_input_u8);
 
   /*
   * If the offset is greater than input_length then the arguments are
   * invalid. Ideally we would through an exception but that leaks
   * information about the offset. Instead treat it as if the input
   * was invalid.
   */
   bad_input |= CT::Mask<size_t>::is_gt(offset, input_length);
 
   /*
   * If the input is invalid, then set offset == input_length as a result
   * at the end we will set output_bytes == 0 causing the final result to
   * be an empty vector.
   */
   offset = bad_input.select(input_length, offset);
 
   /*
   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_length; ++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, and we just allocated an output buffer of equal size.
      */
      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_length; ++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);
         }
      }
 
   const size_t output_bytes = input_length - offset;
 
   CT::unpoison(output.data(), output.size());
   CT::unpoison(output_bytes);
 
   /*
   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(output_bytes);
   return output;
   }

References b, Botan::CT::Mask< T >::expand(), Botan::CT::Mask< T >::is_equal(), Botan::CT::Mask< T >::is_gt(), poison(), and unpoison().

Referenced by Botan::oaep_find_delim(), strip_leading_zeros(), and Botan::EME_PKCS1v15::unpad().

poison()

template<typename T >

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

inline

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

   {
#if defined(BOTAN_HAS_VALGRIND)
   VALGRIND_MAKE_MEM_UNDEFINED(p, n * sizeof(T));
#else
   BOTAN_UNUSED(p, n);
#endif
   }

References BOTAN_UNUSED, and T.

Referenced by Botan::PKCS7_Padding::add_padding(), Botan::ANSI_X923_Padding::add_padding(), Botan::OneAndZeros_Padding::add_padding(), Botan::ESP_Padding::add_padding(), copy_output(), Botan::curve25519_donna(), Botan::TLS::TLS_CBC_HMAC_AEAD_Decryption::finish(), Botan::oaep_find_delim(), Botan::PKCS7_Padding::unpad(), Botan::ANSI_X923_Padding::unpad(), Botan::OneAndZeros_Padding::unpad(), Botan::ESP_Padding::unpad(), and Botan::EME_PKCS1v15::unpad().

strip_leading_zeros() [1/2]

secure_vector< uint8_t > Botan::CT::strip_leading_zeros ( const secure_vector< uint8_t > &  in )

inline

Definition at line 414 of file ct_utils.h.

   {
   return strip_leading_zeros(in.data(), in.size());
   }

References strip_leading_zeros().

strip_leading_zeros() [2/2]

secure_vector< uint8_t > Botan::CT::strip_leading_zeros	(	const uint8_t	in[],
		size_t	length
	)

Definition at line 87 of file ct_utils.cpp.

   {
   size_t leading_zeros = 0;
 
   auto only_zeros = Mask<uint8_t>::set();
 
   for(size_t i = 0; i != length; ++i)
      {
      only_zeros &= CT::Mask<uint8_t>::is_zero(in[i]);
      leading_zeros += only_zeros.if_set_return(1);
      }
 
   return copy_output(CT::Mask<uint8_t>::cleared(), in, length, leading_zeros);
   }

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

Referenced by Botan::TLS::Client_Key_Exchange::Client_Key_Exchange(), strip_leading_zeros(), and Botan::TLS::Callbacks::tls_dh_agree().

unpoison() [1/2]

template<typename T >

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

inline

Definition at line 58 of file ct_utils.h.

   {
#if defined(BOTAN_HAS_VALGRIND)
   VALGRIND_MAKE_MEM_DEFINED(p, n * sizeof(T));
#else
   BOTAN_UNUSED(p, n);
#endif
   }

References BOTAN_UNUSED, and T.

Referenced by Botan::PKCS7_Padding::add_padding(), Botan::ANSI_X923_Padding::add_padding(), Botan::OneAndZeros_Padding::add_padding(), Botan::ESP_Padding::add_padding(), Botan::bigint_cmp(), copy_output(), Botan::curve25519_donna(), Botan::TLS::TLS_CBC_HMAC_AEAD_Decryption::finish(), Botan::gcd(), Botan::oaep_find_delim(), Botan::redc_p192(), Botan::redc_p224(), Botan::redc_p256(), Botan::redc_p384(), Botan::CT::Mask< T >::select_and_unpoison(), Botan::BigInt::top_bits_free(), Botan::PKCS7_Padding::unpad(), Botan::ANSI_X923_Padding::unpad(), Botan::OneAndZeros_Padding::unpad(), Botan::ESP_Padding::unpad(), Botan::EME_PKCS1v15::unpad(), and Botan::CT::Mask< T >::unpoisoned_value().

unpoison() [2/2]

template<typename T >

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

inline

Definition at line 68 of file ct_utils.h.

   {
#if defined(BOTAN_HAS_VALGRIND)
   VALGRIND_MAKE_MEM_DEFINED(&p, sizeof(T));
#else
   BOTAN_UNUSED(p);
#endif
   }

References BOTAN_UNUSED, and T.