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

#include <ct_utils.h>

Public Member Functions
constexpr bool	as_bool () 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 >	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 ~0 (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 86 of file ct_utils.h.

Constructor & Destructor Documentation

Mask() [1/2]

template<typename T >

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

default

Mask() [2/2]

template<typename T >

template<typename U >

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

inlineconstexpr

Derive a Mask from a Mask of a larger type

Definition at line 98 of file ct_utils.h.

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

References T.

Member Function Documentation

as_bool()

template<typename T >

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

inlineconstexpr

Return true iff this mask is set

Definition at line 278 of file ct_utils.h.

{ return unpoisoned_value() != 0; }

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

cleared()

template<typename T >

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

inlinestaticconstexpr

Return a Mask<T> with all bits cleared

Definition at line 110 of file ct_utils.h.

{ return Mask<T>(0); }

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

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

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

References T, and Botan::CT::Mask< T >::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 115 of file ct_utils.h.

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

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::BigInt::cond_flip_sign(), Botan::CT::conditional_assign_mem(), Botan::CT::conditional_copy_mem(), Botan::CT::conditional_swap(), Botan::constant_time_compare(), Botan::CT::copy_output(), Botan::BigInt::ct_cond_assign(), Botan::ct_divide_word(), Botan::Ed448Point::decode(), Botan::low_zero_bits(), Botan::Ed448Point::operator==(), Botan::redc_p521(), Botan::Sodium::sodium_is_zero(), Botan::ANSI_X923_Padding::unpad(), Botan::OneAndZeros_Padding::unpad(), and Botan::x448().

if_not_set_return()

template<typename T >

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

{ return ~m_mask & x; }

Referenced by Botan::CT::Mask< T >::if_set_zero_out(), and Botan::EME_PKCS1v15::unpad().

if_set_return()

template<typename T >

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

{ return m_mask & x; }

if_set_zero_out()

template<typename T >

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

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

References Botan::CT::Mask< T >::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 165 of file ct_utils.h.

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

References Botan::expand_top_bit(), and T.

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

{ return Mask<T>::is_zero(static_cast<T>(x ^ y)); }

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

Referenced by Botan::bigint_cmp(), Botan::bigint_ct_is_lt(), Botan::TLS::check_tls_cbc_padding(), Botan::constant_time_compare(), Botan::CT::copy_output(), Botan::PK_Decryptor::decrypt_or_random(), Botan::EC_Point_Base_Point_Precompute::mul(), Botan::EC_Point_Var_Point_Precompute::mul(), Botan::oaep_find_delim(), Botan::redc_p521(), Botan::Sodium::sodium_compare(), Botan::PKCS7_Padding::unpad(), Botan::OneAndZeros_Padding::unpad(), Botan::ESP_Padding::unpad(), and Botan::vartime_divide().

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

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

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

Referenced by Botan::CT::copy_output(), Botan::PKCS7_Padding::unpad(), Botan::ANSI_X923_Padding::unpad(), and Botan::ESP_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 154 of file ct_utils.h.

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

Referenced by Botan::ct_divide_word(), Botan::PKCS7_Padding::unpad(), and Botan::ANSI_X923_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 139 of file ct_utils.h.

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

Referenced by Botan::bigint_cmp(), Botan::bigint_ct_is_lt(), Botan::TLS::check_tls_cbc_padding(), Botan::CT::Mask< T >::is_gt(), 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 149 of file ct_utils.h.

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

Referenced by Botan::TLS::check_tls_cbc_padding(), and Botan::constant_time_compare().

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 156 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 = v_lt_l | v_gt_u;
         return ~Mask<T>(expand_top_bit(either));
      }

References Botan::expand_top_bit(), and T.

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

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

Referenced by Botan::CT::all_zeros(), Botan::bigint_cmp(), Botan::bigint_ct_is_eq(), Botan::bigint_ct_is_lt(), Botan::BigInt::ct_reduce_below(), Botan::CT::is_equal(), Botan::CT::Mask< T >::is_equal(), Botan::oaep_find_delim(), Botan::CT::strip_leading_zeros(), Botan::OneAndZeros_Padding::unpad(), Botan::ESP_Padding::unpad(), and Botan::EME_PKCS1v15::unpad().

operator&=()

template<typename T >

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

inline

AND-combine two masks

Definition at line 180 of file ct_utils.h.

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

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

operator=()

template<typename T >

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

default

operator^=()

template<typename T >

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

inline

XOR-combine two masks

Definition at line 188 of file ct_utils.h.

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

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

operator|=()

template<typename T >

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

inline

OR-combine two masks

Definition at line 196 of file ct_utils.h.

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

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

operator~()

template<typename T >

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

inlineconstexpr

Negate this mask

Definition at line 219 of file ct_utils.h.

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

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

select()

template<typename T >

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

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

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

Referenced by Botan::bigint_cnd_add_or_sub(), Botan::CT::Mask< T >::select_and_unpoison(), Botan::CT::Mask< T >::select_mask(), and Botan::CT::Mask< T >::select_n().

select_and_unpoison()

template<typename T >

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

inlineconstexpr

Definition at line 236 of file ct_utils.h.

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

References Botan::CT::Mask< T >::select(), T, 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 245 of file ct_utils.h.

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

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

select_n()

template<typename T >

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

                                                                                      {
         for(size_t i = 0; i != len; ++i) {
            output[i] = this->select(x[i], y[i]);
         }
      }

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

Referenced by Botan::CT::conditional_copy_mem().

set()

template<typename T >

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

inlinestaticconstexpr

Return a Mask<T> with all bits set

Definition at line 105 of file ct_utils.h.

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

References T.

Referenced by Botan::oaep_find_delim(), and Botan::CT::strip_leading_zeros().

unpoisoned_value()

template<typename T >

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

inlineconstexpr

Return the value of the mask, unpoisoned

Definition at line 269 of file ct_utils.h.

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

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

Referenced by Botan::CT::Mask< T >::as_bool().

value()

template<typename T >

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

inlineconstexpr

Return the underlying value of the mask

Definition at line 283 of file ct_utils.h.

{ return m_mask; }

Referenced by Botan::CT::Mask< T >::expand(), Botan::CT::Mask< T >::operator&=(), Botan::CT::Mask< T >::operator^=(), Botan::CT::Mask< T >::operator|=(), Botan::CT::Mask< T >::operator~(), Botan::CT::Mask< T >::select(), Botan::CT::Mask< T >::select_mask(), and Botan::CT::Mask< T >::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 204 of file ct_utils.h.

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

operator^

template<typename T >

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

friend

XOR-combine two masks

Definition at line 209 of file ct_utils.h.

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

operator|

template<typename T >

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

friend

OR-combine two masks

Definition at line 214 of file ct_utils.h.

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

---

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

• src/lib/utils/ct_utils.h