Botan 3.0.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

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)
 
bool is_set () const
 
 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< T > operator~ () const
 
T select (T x, T y) const
 
T select_and_unpoison (T x, T y) const
 
Mask< T > select_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< T > cleared ()
 
template<typename U >
static Mask< T > expand (Mask< U > m)
 
static Mask< T > expand (T v)
 
static Mask< T > is_any_of (T v, std::initializer_list< T > accepted)
 
static Mask< T > is_equal (T x, T y)
 
static Mask< T > is_gt (T x, T y)
 
static Mask< T > is_gte (T x, T y)
 
static Mask< T > is_lt (T x, T y)
 
static Mask< T > is_lte (T x, T y)
 
static Mask< T > is_within_range (T v, T l, T u)
 
static Mask< T > is_zero (T x)
 
static 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>
requires std::is_unsigned<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 >
Botan::CT::Mask< T >::Mask ( Mask< U >  o)
inline

Derive a Mask from a Mask of a larger type

Definition at line 97 of file ct_utils.h.

97 : m_mask(static_cast<T>(o.value()))
98 {
99 static_assert(sizeof(U) > sizeof(T), "sizes ok");
100 }
T
FE_25519 T
Definition: ge.cpp:36

References T.

Member Function Documentation

◆ cleared()

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

Return a Mask<T> with all bits cleared

Definition at line 113 of file ct_utils.h.

114 {
115 return Mask<T>(0);
116 }

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

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

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

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

Definition at line 121 of file ct_utils.h.

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

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

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

279 {
280 return ~m_mask & x;
281 }

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

271 {
272 return m_mask & x;
273 }

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 
)
inline

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

Definition at line 319 of file ct_utils.h.

320 {
321 for(size_t i = 0; i != elems; ++i)
322 {
323 buf[i] = this->if_not_set_return(buf[i]);
324 }
325 }
Botan::CT::Mask::if_not_set_return
T if_not_set_return(T x) const
Definition: ct_utils.h:278

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

195 {
196 T accept = 0;
197
198 for(auto a: accepted)
199 {
200 const T diff = a ^ v;
201 const T eq_zero = ~diff & (diff - 1);
202 accept |= eq_zero;
203 }
204
205 return Mask<T>(expand_top_bit(accept));
206 }
Botan::expand_top_bit
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

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

Definition at line 147 of file ct_utils.h.

148 {
149 return Mask<T>::is_zero(static_cast<T>(x ^ y));
150 }
y
static SIMD_4x64 y
Definition: argon2_avx2.cpp:135
Botan::CT::Mask::is_zero
static Mask< T > is_zero(T x)
Definition: ct_utils.h:139

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

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

164 {
165 return Mask<T>::is_lt(y, x);
166 }
Botan::CT::Mask::is_lt
static Mask< T > is_lt(T x, T y)
Definition: ct_utils.h:155

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

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

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

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

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

References y.

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

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

References y.

Referenced by Botan::TLS::check_tls_cbc_padding().

◆ is_set()

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

Return true iff this mask is set

Definition at line 340 of file ct_utils.h.

341 {
342 return unpoisoned_value() != 0;
343 }
Botan::CT::Mask::unpoisoned_value
T unpoisoned_value() const
Definition: ct_utils.h:330

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

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

185 {
186 //return Mask<T>::is_gte(v, l) & Mask<T>::is_lte(v, u);
187
188 const T v_lt_l = v^((v^l) | ((v-l)^v));
189 const T v_gt_u = u^((u^v) | ((u-v)^u));
190 const T either = v_lt_l | v_gt_u;
191 return ~Mask<T>(expand_top_bit(either));
192 }

References Botan::expand_top_bit(), and T.

◆ is_zero()

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

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

Definition at line 139 of file ct_utils.h.

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

Referenced by Botan::bigint_cmp(), Botan::bigint_ct_is_eq(), Botan::bigint_ct_is_lt(), Botan::ct_compare_u8(), Botan::BigInt::ct_reduce_below(), 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 211 of file ct_utils.h.

212 {
213 m_mask &= o.value();
214 return (*this);
215 }

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

221 {
222 m_mask ^= o.value();
223 return (*this);
224 }

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

230 {
231 m_mask |= o.value();
232 return (*this);
233 }

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

263 {
264 return Mask<T>(~value());
265 }
Botan::CT::Mask::value
T value() const
Definition: ct_utils.h:348

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

287 {
288 return choose(value(), x, y);
289 }
Botan::choose
constexpr T choose(T mask, T a, T b)
Definition: bit_ops.h:175

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

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

292 {
293 T r = this->select(x, y);
294 CT::unpoison(r);
295 return r;
296 }
Botan::CT::Mask::select
T select(T x, T y) const
Definition: ct_utils.h:286
Botan::CT::unpoison
void unpoison(const T *p, size_t n)
Definition: ct_utils.h:58

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

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

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

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

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

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

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

◆ set()

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

Return a Mask<T> with all bits set

Definition at line 105 of file ct_utils.h.

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

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

331 {
332 T r = value();
333 CT::unpoison(r);
334 return r;
335 }

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

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

◆ value()

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

Return the underlying value of the mask

Definition at line 348 of file ct_utils.h.

349 {
350 return m_mask;
351 }

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 Function Documentation

◆ operator&

template<typename T >
Mask< T > operator& ( Mask< T >  x,
Mask< T >  y 
)
friend

AND-combine two masks

Definition at line 238 of file ct_utils.h.

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

◆ operator^

template<typename T >
Mask< T > operator^ ( Mask< T >  x,
Mask< T >  y 
)
friend

XOR-combine two masks

Definition at line 246 of file ct_utils.h.

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

◆ operator|

template<typename T >
Mask< T > operator| ( Mask< T >  x,
Mask< T >  y 
)
friend

OR-combine two masks

Definition at line 254 of file ct_utils.h.

255 {
256 return Mask<T>(x.value() | y.value());
257 }
The documentation for this class was generated from the following file:
Generated by doxygen 1.9.6