Botan 3.3.0
Crypto and TLS for C&
Public Member Functions | Static Public Member Functions | Friends | List of all members
Botan::CT::Mask< T > Class Template Referencefinal

#include <ct_utils.h>

Public Member Functions

bool as_bool () const
 
T if_not_set_return (T x) const
 
T if_set_return (T x) const
 
void if_set_zero_out (T buf[], size_t elems)
 
 Mask (const Mask< T > &other)=default
 
template<typename U >
 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)
 
Mask< Toperator~ () const
 
T select (T x, T y) const
 
T select_and_unpoison (T x, T y) const
 
Mask< Tselect_mask (Mask< T > x, Mask< T > y) const
 
void select_n (T output[], const T x[], const T y[], size_t len) const
 
T unpoisoned_value () const
 
T value () const
 

Static Public Member Functions

static Mask< Tcleared ()
 
template<typename U >
static Mask< Texpand (Mask< U > m)
 
static Mask< Texpand (T v)
 
static Mask< Tis_any_of (T v, std::initializer_list< T > accepted)
 
static Mask< Tis_equal (T x, T y)
 
static Mask< Tis_gt (T x, T y)
 
static Mask< Tis_gte (T x, T y)
 
static Mask< Tis_lt (T x, T y)
 
static Mask< Tis_lte (T x, T y)
 
static Mask< Tis_within_range (T v, T l, T u)
 
static Mask< Tis_zero (T x)
 
static Mask< Tset ()
 

Friends

Mask< Toperator& (Mask< T > x, Mask< T > y)
 
Mask< Toperator^ (Mask< T > x, Mask< T > y)
 
Mask< Toperator| (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 80 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 >
Botan::CT::Mask< T >::Mask ( Mask< U > o)
inline

Derive a Mask from a Mask of a larger type

Definition at line 92 of file ct_utils.h.

92 : m_mask(static_cast<T>(o.value())) {
93 static_assert(sizeof(U) > sizeof(T), "sizes ok");
94 }
FE_25519 T
Definition ge.cpp:34

References T.

Member Function Documentation

◆ as_bool()

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

Return true iff this mask is set

Definition at line 272 of file ct_utils.h.

272{ return unpoisoned_value() != 0; }
T unpoisoned_value() const
Definition ct_utils.h:263

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

◆ cleared()

template<typename T >
static Mask< T > Botan::CT::Mask< T >::cleared ( )
inlinestatic

Return a Mask<T> with all bits cleared

Definition at line 104 of file ct_utils.h.

104{ return Mask<T>(0); }

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

◆ expand() [1/2]

template<typename T >
template<typename U >
static Mask< T > Botan::CT::Mask< T >::expand ( Mask< U > m)
inlinestatic

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

Definition at line 115 of file ct_utils.h.

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

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

◆ expand() [2/2]

template<typename T >
static Mask< T > Botan::CT::Mask< T >::expand ( T v)
inlinestatic

◆ if_not_set_return()

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

Return x if the mask is cleared, or otherwise zero

Definition at line 223 of file ct_utils.h.

223{ 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 >
T Botan::CT::Mask< T >::if_set_return ( T x) const
inline

Return x if the mask is set, or otherwise zero

Definition at line 218 of file ct_utils.h.

218{ return m_mask & x; }

◆ if_set_zero_out()

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

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

Definition at line 254 of file ct_utils.h.

254 {
255 for(size_t i = 0; i != elems; ++i) {
256 buf[i] = this->if_not_set_return(buf[i]);
257 }
258 }
T if_not_set_return(T x) const
Definition ct_utils.h:223

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

◆ is_any_of()

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

Definition at line 159 of file ct_utils.h.

159 {
160 T accept = 0;
161
162 for(auto a : accepted) {
163 const T diff = a ^ v;
164 const T eq_zero = ~diff & (diff - 1);
165 accept |= eq_zero;
166 }
167
168 return Mask<T>(expand_top_bit(accept));
169 }
constexpr T expand_top_bit(T a)
Definition bit_ops.h:23

References Botan::expand_top_bit(), and T.

◆ is_equal()

template<typename T >
static Mask< T > Botan::CT::Mask< T >::is_equal ( T x,
T y )
inlinestatic

◆ is_gt()

template<typename T >
static Mask< T > Botan::CT::Mask< T >::is_gt ( T x,
T y )
inlinestatic

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

Definition at line 138 of file ct_utils.h.

138{ return Mask<T>::is_lt(y, x); }
static Mask< T > is_lt(T x, T y)
Definition ct_utils.h:133

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 Mask< T > Botan::CT::Mask< T >::is_gte ( T x,
T y )
inlinestatic

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

Definition at line 148 of file ct_utils.h.

148{ 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 Mask< T > Botan::CT::Mask< T >::is_lt ( T x,
T y )
inlinestatic

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

Definition at line 133 of file ct_utils.h.

133{ 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 Mask< T > Botan::CT::Mask< T >::is_lte ( T x,
T y )
inlinestatic

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

Definition at line 143 of file ct_utils.h.

143{ 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 Mask< T > Botan::CT::Mask< T >::is_within_range ( T v,
T l,
T u )
inlinestatic

Definition at line 150 of file ct_utils.h.

150 {
151 //return Mask<T>::is_gte(v, l) & Mask<T>::is_lte(v, u);
152
153 const T v_lt_l = v ^ ((v ^ l) | ((v - l) ^ v));
154 const T v_gt_u = u ^ ((u ^ v) | ((u - v) ^ u));
155 const T either = v_lt_l | v_gt_u;
156 return ~Mask<T>(expand_top_bit(either));
157 }

References Botan::expand_top_bit(), and T.

◆ is_zero()

template<typename T >
static Mask< T > Botan::CT::Mask< T >::is_zero ( T x)
inlinestatic

◆ operator&=()

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

AND-combine two masks

Definition at line 174 of file ct_utils.h.

174 {
175 m_mask &= o.value();
176 return (*this);
177 }

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

182 {
183 m_mask ^= o.value();
184 return (*this);
185 }

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

190 {
191 m_mask |= o.value();
192 return (*this);
193 }

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

◆ operator~()

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

Negate this mask

Definition at line 213 of file ct_utils.h.

213{ return Mask<T>(~value()); }
T value() const
Definition ct_utils.h:277

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

◆ select()

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

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

Definition at line 228 of file ct_utils.h.

228{ return choose(value(), x, y); }
constexpr T choose(T mask, T a, T b)
Definition bit_ops.h:180

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

Referenced by Botan::bigint_cnd_add_or_sub(), Botan::bigint_cnd_addsub(), 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 >
T Botan::CT::Mask< T >::select_and_unpoison ( T x,
T y ) const
inline

Definition at line 230 of file ct_utils.h.

230 {
231 T r = this->select(x, y);
232 CT::unpoison(r);
233 return r;
234 }
T select(T x, T y) const
Definition ct_utils.h:228
void unpoison(const T *p, size_t n)
Definition ct_utils.h:55

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

239{ 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 >
void Botan::CT::Mask< T >::select_n ( T output[],
const T x[],
const T y[],
size_t len ) const
inline

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

Definition at line 245 of file ct_utils.h.

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

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

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

◆ set()

template<typename T >
static Mask< T > Botan::CT::Mask< T >::set ( )
inlinestatic

Return a Mask<T> with all bits set

Definition at line 99 of file ct_utils.h.

99{ 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 >
T Botan::CT::Mask< T >::unpoisoned_value ( ) const
inline

Return the value of the mask, unpoisoned

Definition at line 263 of file ct_utils.h.

263 {
264 T r = value();
265 CT::unpoison(r);
266 return r;
267 }

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

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

◆ value()

template<typename T >
T Botan::CT::Mask< T >::value ( ) const
inline

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

198{ 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 203 of file ct_utils.h.

203{ 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 208 of file ct_utils.h.

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

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