Botan 3.8.1
Crypto and TLS for C&
Botan::CT::Mask< T > Class Template Referencefinal

#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]

◆ 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.

392 : m_mask(static_cast<T>(o.value())) {
393 static_assert(sizeof(U) > sizeof(T), "sizes ok");
394 }
constexpr T value() const
Definition ct_utils.h:636

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.

638{ CT::poison(m_mask); }
constexpr void poison(const T *p, size_t n)
Definition ct_utils.h:54

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.

640{ CT::unpoison(m_mask); }
constexpr void unpoison(const T *p, size_t n)
Definition ct_utils.h:65

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.

626{ return unpoisoned_value() != 0; }
constexpr T unpoisoned_value() const
Definition ct_utils.h:610

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.

static constexpr Choice from_int(T v)
Definition ct_utils.h:312

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.

404{ return Mask<T>(0); }
Mask(const Mask< T > &other)=default

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.

599 {
600 auto cnd = Mask<U>(*this);
601 U t0 = cnd.select(y, x);
602 U t1 = cnd.select(x, y);
603 x = t0;
604 y = t1;
605 }
constexpr T select(T x, T y) const
Definition ct_utils.h:560

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.

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

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

◆ expand() [2/2]

◆ 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.

433 {
434 return CT::Mask<T>::expand_top_bit(v << (sizeof(v) * 8 - 1 - bit));
435 }
static constexpr Mask< T > expand_top_bit(T v)
Definition ct_utils.h:427

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

◆ 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.

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

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.

555{ 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.

550{ 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.

587 {
588 for(size_t i = 0; i != elems; ++i) {
589 buf[i] = this->if_not_set_return(buf[i]);
590 }
591 }
constexpr T if_not_set_return(T x) const
Definition ct_utils.h:555

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.

491 {
492 T accept = 0;
493
494 for(auto a : accepted) {
495 const T diff = a ^ v;
496 const T eq_zero = value_barrier<T>(~diff & (diff - 1));
497 accept |= eq_zero;
498 }
499
501 }

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

◆ is_equal()

◆ 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.

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

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

◆ 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.

462 {
463 T u = x ^ ((x ^ y) | ((x - y) ^ x));
465 }

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.

475{ 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.

482 {
483 //return Mask<T>::is_gte(v, l) & Mask<T>::is_lte(v, u);
484
485 const T v_lt_l = v ^ ((v ^ l) | ((v - l) ^ v));
486 const T v_gt_u = u ^ ((u ^ v) | ((u - v) ^ u));
489 }

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

◆ is_zero()

◆ 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.

506 {
507 m_mask &= o.value();
508 return (*this);
509 }

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.

514 {
515 m_mask ^= o.value();
516 return (*this);
517 }

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.

522 {
523 m_mask |= o.value();
524 return (*this);
525 }

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.

545{ 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.

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

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.

562 {
563 T r = this->select(x, y);
565 return r;
566 }

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.

571{ 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.

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

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.

399{ 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.

610 {
611 T r = value();
613 return r;
614 }

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.

636{ 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.

530{ 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.

535{ 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.

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

References Mask(), and value().


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