Botan::CT::Mask< T > Class Template Reference

#include <ct_utils.h>

Public Member Functions
constexpr void	_const_time_poison () const
constexpr void	_const_time_unpoison () const
constexpr bool	as_bool () const
constexpr CT::Choice	as_choice () const
template<typename U> requires (sizeof(U) <= sizeof(T))
void	conditional_swap (U &x, U &y) const
constexpr T	if_not_set_return (T x) const
constexpr T	if_set_return (T x) const
constexpr void	if_set_zero_out (T buf[], size_t elems)
	Mask (const Mask< T > &other)=default
template<typename U>
constexpr	Mask (Mask< U > o)
Mask< T > &	operator&= (Mask< T > o)
Mask< T > &	operator= (const Mask< T > &other)=default
Mask< T > &	operator^= (Mask< T > o)
Mask< T > &	operator|= (Mask< T > o)
constexpr Mask< T >	operator~ () const
constexpr T	select (T x, T y) const
constexpr T	select_and_unpoison (T x, T y) const
Mask< T >	select_mask (Mask< T > x, Mask< T > y) const
constexpr void	select_n (T output[], const T x[], const T y[], size_t len) const
constexpr T	unpoisoned_value () const
constexpr T	value () const

Static Public Member Functions
static constexpr Mask< T >	cleared ()
template<typename U>
static constexpr Mask< T >	expand (Mask< U > m)
static constexpr Mask< T >	expand (T v)
static constexpr Mask< T >	expand_bit (T v, size_t bit)
static constexpr Mask< T >	expand_top_bit (T v)
static constexpr Mask< T >	from_choice (Choice c)
static constexpr Mask< T >	is_any_of (T v, std::initializer_list< T > accepted)
static constexpr Mask< T >	is_equal (T x, T y)
static constexpr Mask< T >	is_gt (T x, T y)
static constexpr Mask< T >	is_gte (T x, T y)
static constexpr Mask< T >	is_lt (T x, T y)
static constexpr Mask< T >	is_lte (T x, T y)
static constexpr Mask< T >	is_within_range (T v, T l, T u)
static constexpr Mask< T >	is_zero (T x)
static constexpr Mask< T >	set ()

Friends
Mask< T >	operator& (Mask< T > x, Mask< T > y)
Mask< T >	operator^ (Mask< T > x, Mask< T > y)
Mask< T >	operator| (Mask< T > x, Mask< T > y)

Detailed Description

template<typename T>
class Botan::CT::Mask< T >

A Mask type used for constant-time operations. A Mask<T> always has value either |0| (all bits cleared) or |1| (all bits set). All operations in a Mask<T> are intended to compile to code which does not contain conditional jumps. This must be verified with tooling (eg binary disassembly or using valgrind) since you never know what a compiler might do.

Definition at line 380 of file ct_utils.h.

Constructor & Destructor Documentation

Mask() [1/2]

template<typename T>

Botan::CT::Mask< T >::Mask ( const Mask< T > & other )

default

References Mask().

Referenced by cleared(), conditional_swap(), expand(), expand(), expand_bit(), expand_top_bit(), from_choice(), is_any_of(), is_equal(), is_gt(), is_gte(), is_lt(), is_lte(), is_within_range(), is_zero(), Mask(), Mask(), operator&, operator&=(), operator=(), operator^, operator^=(), operator|, operator|=(), operator~(), select_mask(), and set().

Mask() [2/2]

template<typename T>

template<typename U>

Botan::CT::Mask< T >::Mask ( Mask< U > o )

inlineconstexpr

Derive a Mask from a Mask of a larger type

Definition at line 392 of file ct_utils.h.

                                : m_mask(static_cast<T>(o.value())) {
         static_assert(sizeof(U) > sizeof(T), "sizes ok");
      }

References Mask(), and value().

Member Function Documentation

_const_time_poison()

template<typename T>

void Botan::CT::Mask< T >::_const_time_poison ( ) const

inlineconstexpr

Definition at line 638 of file ct_utils.h.

{ CT::poison(m_mask); }

References Botan::CT::poison().

_const_time_unpoison()

template<typename T>

void Botan::CT::Mask< T >::_const_time_unpoison ( ) const

inlineconstexpr

Definition at line 640 of file ct_utils.h.

{ CT::unpoison(m_mask); }

References Botan::CT::unpoison().

as_bool()

template<typename T>

bool Botan::CT::Mask< T >::as_bool ( ) const

inlineconstexpr

Unsafe conversion to bool

This conversion itself is (probably) constant time, but once the mask is reduced to a simple bool, it's entirely possible for the compiler to perform range analysis on the values, since there are just the two. As a consequence even if the caller is not using this in an obviously branchy way (if(mask.as_bool()) ...) a smart compiler may introduce branches depending on the value.

Definition at line 626 of file ct_utils.h.

{ return unpoisoned_value() != 0; }

References unpoisoned_value().

as_choice()

template<typename T>

CT::Choice Botan::CT::Mask< T >::as_choice ( ) const

inlineconstexpr

Return a Choice based on this mask

Definition at line 631 of file ct_utils.h.

{ return CT::Choice::from_int(unpoisoned_value()); }

References Botan::CT::Choice::from_int(), and unpoisoned_value().

Referenced by Botan::oaep_find_delim().

cleared()

template<typename T>

static constexpr Mask< T > Botan::CT::Mask< T >::cleared ( )

inlinestaticconstexpr

Return a Mask<T> of |0| (all bits cleared)

Definition at line 404 of file ct_utils.h.

{ return Mask<T>(0); }

References Mask().

Referenced by Botan::Classic_McEliece_PrivateKeyInternal::check_key(), Botan::low_zero_bits(), Botan::oaep_find_delim(), Botan::OneAndZeros_Padding::unpad(), and Botan::x448().

conditional_swap()

template<typename T>

template<typename U>
requires (sizeof(U) <= sizeof(T))

void Botan::CT::Mask< T >::conditional_swap ( U & x, U & y ) const

inline

If this mask is set, swap x and y

Definition at line 597 of file ct_utils.h.

      {
         auto cnd = Mask<U>(*this);
         U t0 = cnd.select(y, x);
         U t1 = cnd.select(x, y);
         x = t0;
         y = t1;
      }

References Mask().

expand() [1/2]

template<typename T>

template<typename U>

static constexpr Mask< T > Botan::CT::Mask< T >::expand ( Mask< U > m )

inlinestaticconstexpr

Return a Mask<T> which is set if m is set

Definition at line 441 of file ct_utils.h.

                                                 {
         static_assert(sizeof(U) < sizeof(T), "sizes ok");
         return ~Mask<T>::is_zero(m.value());
      }

References is_zero(), Mask(), and value().

expand() [2/2]

template<typename T>

static constexpr Mask< T > Botan::CT::Mask< T >::expand ( T v )

inlinestaticconstexpr

Return a Mask<T> which is set if v is != 0

Definition at line 409 of file ct_utils.h.

{ return ~Mask<T>::is_zero(value_barrier<T>(v)); }

References is_zero(), Mask(), and Botan::CT::value_barrier().

Referenced by Botan::bigint_cnd_abs(), Botan::bigint_cnd_add(), Botan::bigint_cnd_sub(), Botan::bigint_cnd_swap(), Botan::bigint_ct_is_lt(), Botan::bigint_shl1(), Botan::bigint_shl2(), Botan::bigint_shr1(), Botan::bigint_shr2(), Botan::Scalar448::bytes_are_reduced(), Botan::Classic_McEliece_PrivateKeyInternal::check_key(), Botan::BigInt::cond_flip_sign(), Botan::CT::conditional_assign_mem(), Botan::CT::conditional_copy_mem(), Botan::CT::conditional_swap(), Botan::constant_time_compare(), Botan::Classic_McEliece_Field_Ordering::create_from_control_bits(), Botan::BigInt::ct_cond_assign(), Botan::Ed448Point::decode(), Botan::GF_Mask::expand(), Botan::low_zero_bits(), Botan::bitvector_base< AllocatorT >::bitref< BlockT >::operator=(), Botan::Ed448Point::operator==(), Botan::bitvector_base< AllocatorT >::bitref< BlockT >::operator^=(), Botan::bitvector_base< AllocatorT >::bitref< BlockT >::operator|=(), Botan::Classic_McEliece_Field_Ordering::permute_with_pivots(), Botan::Sodium::sodium_is_zero(), Botan::ANSI_X923_Padding::unpad(), Botan::OneAndZeros_Padding::unpad(), and Botan::x448().

expand_bit()

template<typename T>

static constexpr Mask< T > Botan::CT::Mask< T >::expand_bit ( T v, size_t bit )

inlinestaticconstexpr

Return a Mask<T> which is set if the given bit of v is set. bit must be from 0 (LSB) to (sizeof(T) * 8 - 1) (MSB).

Definition at line 433 of file ct_utils.h.

                                                           {
         return CT::Mask<T>::expand_top_bit(v << (sizeof(v) * 8 - 1 - bit));
      }

References expand_top_bit(), and Mask().

Referenced by Botan::FrodoMatrix::sample().

expand_top_bit()

template<typename T>

static constexpr Mask< T > Botan::CT::Mask< T >::expand_top_bit ( T v )

inlinestaticconstexpr

Return a Mask<T> which is set if the top bit of v is set

Definition at line 427 of file ct_utils.h.

{ return Mask<T>(Botan::expand_top_bit<T>(value_barrier<T>(v))); }

References Botan::expand_top_bit(), Mask(), and Botan::CT::value_barrier().

Referenced by Botan::ct_divide_word(), Botan::ct_mod_word(), expand_bit(), is_any_of(), is_lt(), is_within_range(), and Botan::CRYSTALS::Trait_Base< ConstantsT, DerivedT >::poly_cadd_q().

from_choice()

template<typename T>

static constexpr Mask< T > Botan::CT::Mask< T >::from_choice ( Choice c )

inlinestaticconstexpr

Return a Mask<T> which is set if choice is set

Definition at line 414 of file ct_utils.h.

                                                     {
         if constexpr(sizeof(T) <= sizeof(uint32_t)) {
            // Take advantage of the fact that Choice's mask is always
            // either |0| or |1|
            return Mask<T>(static_cast<T>(c.value()));
         } else {
            return ~Mask<T>::is_zero(c.value());
         }
      }

References is_zero(), Mask(), and Botan::CT::Choice::value().

Referenced by Botan::CT::conditional_assign_mem(), Botan::CT::copy_output(), Botan::bitvector_base< secure_allocator >::ct_conditional_xor(), Botan::PK_Ops::Decryption_with_EME::decrypt(), and Botan::CT::Option< T >::value_or().

if_not_set_return()

template<typename T>

T Botan::CT::Mask< T >::if_not_set_return ( T x ) const

inlineconstexpr

Return x if the mask is cleared, or otherwise zero

Definition at line 555 of file ct_utils.h.

{ return ~value() & x; }

References value().

Referenced by if_set_zero_out().

if_set_return()

template<typename T>

T Botan::CT::Mask< T >::if_set_return ( T x ) const

inlineconstexpr

Return x if the mask is set, or otherwise zero

Definition at line 550 of file ct_utils.h.

{ return value() & x; }

References value().

Referenced by Botan::oaep_find_delim().

if_set_zero_out()

template<typename T>

void Botan::CT::Mask< T >::if_set_zero_out ( T buf[], size_t elems )

inlineconstexpr

If this mask is set, zero out buf, otherwise do nothing

Definition at line 587 of file ct_utils.h.

                                                            {
         for(size_t i = 0; i != elems; ++i) {
            buf[i] = this->if_not_set_return(buf[i]);
         }
      }

References if_not_set_return().

is_any_of()

template<typename T>

static constexpr Mask< T > Botan::CT::Mask< T >::is_any_of ( T v, std::initializer_list< T > accepted )

inlinestaticconstexpr

Definition at line 491 of file ct_utils.h.

                                                                               {
         T accept = 0;
 
         for(auto a : accepted) {
            const T diff = a ^ v;
            const T eq_zero = value_barrier<T>(~diff & (diff - 1));
            accept |= eq_zero;
         }
 
         return Mask<T>::expand_top_bit(accept);
      }

References expand_top_bit(), Mask(), and Botan::CT::value_barrier().

is_equal()

template<typename T>

static constexpr Mask< T > Botan::CT::Mask< T >::is_equal ( T x, T y )

inlinestaticconstexpr

Return a Mask<T> which is set if x == y

Definition at line 454 of file ct_utils.h.

                                                  {
         const T diff = value_barrier(x) ^ value_barrier(y);
         return Mask<T>::is_zero(diff);
      }

References is_zero(), Mask(), and Botan::CT::value_barrier().

Referenced by Botan::OneAndZeros_Padding::add_padding(), Botan::bigint_cmp(), Botan::bigint_ct_is_lt(), Botan::Classic_McEliece_PrivateKeyInternal::check_key(), Botan::TLS::check_tls_cbc_padding(), Botan::constant_time_compare(), Botan::CT::copy_output(), Botan::BigInt::ct_cond_assign(), Botan::AffinePointTable< C, R >::ct_select(), Botan::AffinePointTable< C, R >::ct_select(), Botan::PK_Decryptor::decrypt_or_random(), Botan::GF_Mask::is_equal(), Botan::Dilithium_Algos::make_hint(), Botan::EC_Point_Base_Point_Precompute::mul(), Botan::EC_Point_Var_Point_Precompute::mul(), Botan::oaep_find_delim(), Botan::Classic_McEliece_Field_Ordering::permute_with_pivots(), Botan::Sodium::sodium_compare(), Botan::ESP_Padding::unpad(), Botan::OneAndZeros_Padding::unpad(), and Botan::PKCS7_Padding::unpad().

is_gt()

template<typename T>

static constexpr Mask< T > Botan::CT::Mask< T >::is_gt ( T x, T y )

inlinestaticconstexpr

Return a Mask<T> which is set if x > y

Definition at line 470 of file ct_utils.h.

{ return Mask<T>::is_lt(y, x); }

References is_lt(), and Mask().

Referenced by Botan::OneAndZeros_Padding::add_padding(), is_lte(), Botan::Dilithium_Algos::make_hint(), Botan::ANSI_X923_Padding::unpad(), Botan::ESP_Padding::unpad(), and Botan::PKCS7_Padding::unpad().

is_gte()

template<typename T>

static constexpr Mask< T > Botan::CT::Mask< T >::is_gte ( T x, T y )

inlinestaticconstexpr

Return a Mask<T> which is set if x >= y

Definition at line 480 of file ct_utils.h.

{ return ~Mask<T>::is_lt(x, y); }

References is_lt(), and Mask().

Referenced by Botan::ANSI_X923_Padding::add_padding(), Botan::ESP_Padding::add_padding(), Botan::PKCS7_Padding::add_padding(), Botan::ct_divide_word(), Botan::ct_mod_word(), Botan::ANSI_X923_Padding::unpad(), and Botan::PKCS7_Padding::unpad().

is_lt()

template<typename T>

static constexpr Mask< T > Botan::CT::Mask< T >::is_lt ( T x, T y )

inlinestaticconstexpr

Return a Mask<T> which is set if x < y

Definition at line 462 of file ct_utils.h.

                                               {
         T u = x ^ ((x ^ y) | ((x - y) ^ x));
         return Mask<T>::expand_top_bit(u);
      }

References expand_top_bit(), and Mask().

Referenced by Botan::bigint_cmp(), Botan::bigint_ct_is_lt(), Botan::TLS::check_tls_cbc_padding(), is_gt(), is_gte(), Botan::donna128::operator+=(), Botan::donna128::operator+=(), Botan::FrodoMatrix::sample(), and Botan::Sodium::sodium_compare().

is_lte()

template<typename T>

static constexpr Mask< T > Botan::CT::Mask< T >::is_lte ( T x, T y )

inlinestaticconstexpr

Return a Mask<T> which is set if x <= y

Definition at line 475 of file ct_utils.h.

{ return ~Mask<T>::is_gt(x, y); }

References is_gt(), and Mask().

Referenced by Botan::TLS::check_tls_cbc_padding(), Botan::constant_time_compare(), Botan::CT::copy_output(), Botan::GF_Mask::is_lte(), and Botan::Dilithium_Algos::make_hint().

is_within_range()

template<typename T>

static constexpr Mask< T > Botan::CT::Mask< T >::is_within_range ( T v, T l, T u )

inlinestaticconstexpr

Definition at line 482 of file ct_utils.h.

                                                              {
         //return Mask<T>::is_gte(v, l) & Mask<T>::is_lte(v, u);
 
         const T v_lt_l = v ^ ((v ^ l) | ((v - l) ^ v));
         const T v_gt_u = u ^ ((u ^ v) | ((u - v) ^ u));
         const T either = value_barrier(v_lt_l) | value_barrier(v_gt_u);
         return ~Mask<T>::expand_top_bit(either);
      }

References expand_top_bit(), Mask(), and Botan::CT::value_barrier().

is_zero()

template<typename T>

static constexpr Mask< T > Botan::CT::Mask< T >::is_zero ( T x )

inlinestaticconstexpr

Return a Mask<T> which is set if v is == 0 or cleared otherwise

Definition at line 449 of file ct_utils.h.

{ return Mask<T>(ct_is_zero<T>(value_barrier<T>(x))); }

References Botan::ct_is_zero(), Mask(), and Botan::CT::value_barrier().

Referenced by Botan::CT::all_zeros(), Botan::bigint_cmp(), Botan::bigint_ct_is_eq(), Botan::bigint_ct_is_lt(), Botan::CT::count_leading_zero_bytes(), Botan::BigInt::ct_reduce_below(), expand(), expand(), from_choice(), Botan::CT::is_equal(), is_equal(), Botan::GF_Mask::is_zero(), Botan::Dilithium_Algos::make_hint(), Botan::oaep_find_delim(), Botan::ESP_Padding::unpad(), and Botan::OneAndZeros_Padding::unpad().

operator&=()

template<typename T>

Mask< T > & Botan::CT::Mask< T >::operator&= ( Mask< T > o )

inline

AND-combine two masks

Definition at line 506 of file ct_utils.h.

                                     {
         m_mask &= o.value();
         return (*this);
      }

References Mask(), and value().

operator=()

template<typename T>

Mask< T > & Botan::CT::Mask< T >::operator= ( const Mask< T > & other )

default

References Mask().

operator^=()

template<typename T>

Mask< T > & Botan::CT::Mask< T >::operator^= ( Mask< T > o )

inline

XOR-combine two masks

Definition at line 514 of file ct_utils.h.

                                     {
         m_mask ^= o.value();
         return (*this);
      }

References Mask(), and value().

operator|=()

template<typename T>

Mask< T > & Botan::CT::Mask< T >::operator|= ( Mask< T > o )

inline

OR-combine two masks

Definition at line 522 of file ct_utils.h.

                                     {
         m_mask |= o.value();
         return (*this);
      }

References Mask(), and value().

operator~()

template<typename T>

Mask< T > Botan::CT::Mask< T >::operator~ ( ) const

inlineconstexpr

Negate this mask

Definition at line 545 of file ct_utils.h.

{ return Mask<T>(~value()); }

References Mask(), and value().

select()

template<typename T>

T Botan::CT::Mask< T >::select ( T x, T y ) const

inlineconstexpr

If this mask is set, return x, otherwise return y

Definition at line 560 of file ct_utils.h.

{ return choose(value(), x, y); }

References Botan::choose(), and value().

Referenced by Botan::bigint_cnd_add_or_sub(), Botan::Classic_McEliece_Decryptor::raw_kem_decrypt(), select_and_unpoison(), and select_mask().

select_and_unpoison()

template<typename T>

T Botan::CT::Mask< T >::select_and_unpoison ( T x, T y ) const

inlineconstexpr

Definition at line 562 of file ct_utils.h.

                                                      {
         T r = this->select(x, y);
         CT::unpoison(r);
         return r;
      }

References select(), and Botan::CT::unpoison().

select_mask()

template<typename T>

Mask< T > Botan::CT::Mask< T >::select_mask ( Mask< T > x, Mask< T > y ) const

inline

If this mask is set, return x, otherwise return y

Definition at line 571 of file ct_utils.h.

{ return Mask<T>(select(x.value(), y.value())); }

References Mask(), select(), and value().

select_n()

template<typename T>

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

inlineconstexpr

Conditionally set output to x or y, depending on if mask is set or cleared (resp)

Definition at line 577 of file ct_utils.h.

                                                                                      {
         const T mask = value();
         for(size_t i = 0; i != len; ++i) {
            output[i] = choose(mask, x[i], y[i]);
         }
      }

References Botan::choose(), and value().

Referenced by Botan::bigint_cnd_add_or_sub(), Botan::CT::conditional_copy_mem(), and Botan::Classic_McEliece_Decryptor::raw_kem_decrypt().

set()

template<typename T>

static constexpr Mask< T > Botan::CT::Mask< T >::set ( )

inlinestaticconstexpr

Return a Mask<T> of |1| (all bits set)

Definition at line 399 of file ct_utils.h.

{ return Mask<T>(static_cast<T>(~0)); }

References Mask().

Referenced by Botan::CT::count_leading_zero_bytes(), Botan::oaep_find_delim(), and Botan::GF_Mask::set().

unpoisoned_value()

template<typename T>

T Botan::CT::Mask< T >::unpoisoned_value ( ) const

inlineconstexpr

Return the value of the mask, unpoisoned

Definition at line 610 of file ct_utils.h.

                                           {
         T r = value();
         CT::unpoison(r);
         return r;
      }

References Botan::CT::unpoison(), and value().

Referenced by as_bool(), and as_choice().

value()

template<typename T>

T Botan::CT::Mask< T >::value ( ) const

inlineconstexpr

Return the underlying value of the mask

Definition at line 636 of file ct_utils.h.

{ return value_barrier<T>(m_mask); }

References Botan::CT::value_barrier().

Referenced by expand(), if_not_set_return(), if_set_return(), Mask(), operator&, operator&=(), operator^, operator^=(), operator|, operator|=(), operator~(), select(), select_mask(), select_n(), and unpoisoned_value().

Friends And Related Symbol Documentation

operator&

template<typename T>

Mask< T > operator& ( Mask< T > x, Mask< T > y )

friend

AND-combine two masks

Definition at line 530 of file ct_utils.h.

{ return Mask<T>(x.value() & y.value()); }

References Mask(), and value().

operator^

template<typename T>

Mask< T > operator^ ( Mask< T > x, Mask< T > y )

friend

XOR-combine two masks

Definition at line 535 of file ct_utils.h.

{ return Mask<T>(x.value() ^ y.value()); }

References Mask(), and value().

operator|

template<typename T>

Mask< T > operator| ( Mask< T > x, Mask< T > y )

friend

OR-combine two masks

Definition at line 540 of file ct_utils.h.

{ return Mask<T>(x.value() | y.value()); }

References Mask(), and value().

---

The documentation for this class was generated from the following file:

• src/lib/utils/ct_utils.h