Botan 3.9.0
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
 Mask (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 > &&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
 ~Mask ()=default

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_bool (bool v)
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 388 of file ct_utils.h.

Constructor & Destructor Documentation

◆ Mask() [1/3]

◆ Mask() [2/3]

template<typename T>
Botan::CT::Mask< T >::Mask ( Mask< T > && other)
default

References Mask().

◆ ~Mask()

template<typename T>
Botan::CT::Mask< T >::~Mask ( )
default

◆ Mask() [3/3]

template<typename T>
template<typename U>
Botan::CT::Mask< T >::Mask ( Mask< U > o)
inlineexplicitconstexpr

Derive a Mask from a Mask of a larger type

Definition at line 403 of file ct_utils.h.

403 : m_mask(static_cast<T>(o.value())) {
404 static_assert(sizeof(U) > sizeof(T), "sizes ok");
405 }
constexpr T value() const
Definition ct_utils.h:658

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

660{ 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 662 of file ct_utils.h.

662{ 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 642 of file ct_utils.h.

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

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

647 {
648 if constexpr(sizeof(T) >= sizeof(uint32_t)) {
649 return CT::Choice::from_mask(static_cast<uint32_t>(unpoisoned_value()));
650 } else {
652 }
653 }
static constexpr Choice from_int(T v)
Definition ct_utils.h:314
static constexpr Choice from_mask(uint32_t v)
Definition ct_utils.h:331

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

Referenced by Botan::oaep_find_delim().

◆ cleared()

template<typename T>
constexpr Mask< T > Botan::CT::Mask< T >::cleared ( )
inlinestaticconstexpr

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

Definition at line 415 of file ct_utils.h.

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

References Mask().

Referenced by Botan::Classic_McEliece_PrivateKeyInternal::check_key(), Botan::CT::is_equal(), Botan::low_zero_bits(), Botan::oaep_find_delim(), Botan::OneAndZeros_Padding::remove_padding(), 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 613 of file ct_utils.h.

615 {
616 auto cnd = Mask<U>(*this);
617 U t0 = cnd.select(y, x);
618 U t1 = cnd.select(x, y);
619 x = t0;
620 y = t1;
621 }
constexpr T select(T x, T y) const
Definition ct_utils.h:576

References Mask().

◆ expand() [1/2]

template<typename T>
template<typename U>
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 457 of file ct_utils.h.

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

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

◆ expand() [2/2]

◆ expand_bit()

template<typename T>
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 449 of file ct_utils.h.

449 {
450 return CT::Mask<T>::expand_top_bit(v << (sizeof(v) * 8 - 1 - bit));
451 }
static constexpr Mask< T > expand_top_bit(T v)
Definition ct_utils.h:443

References expand_top_bit(), and Mask().

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

◆ expand_bool()

template<typename T>
constexpr Mask< T > Botan::CT::Mask< T >::expand_bool ( bool v)
inlinestaticconstexpr

◆ expand_top_bit()

template<typename T>
constexpr Mask< T > Botan::CT::Mask< T >::expand_top_bit ( T v)
inlinestaticconstexpr

◆ from_choice()

template<typename T>
constexpr Mask< T > Botan::CT::Mask< T >::from_choice ( Choice c)
inlinestaticconstexpr

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

571{ 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 566 of file ct_utils.h.

566{ 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 603 of file ct_utils.h.

603 {
604 for(size_t i = 0; i != elems; ++i) {
605 buf[i] = this->if_not_set_return(buf[i]);
606 }
607 }
constexpr T if_not_set_return(T x) const
Definition ct_utils.h:571

References if_not_set_return().

◆ is_any_of()

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

Definition at line 507 of file ct_utils.h.

507 {
508 T accept = 0;
509
510 for(auto a : accepted) {
511 const T diff = a ^ v;
512 const T eq_zero = value_barrier<T>(~diff & (diff - 1));
513 accept |= eq_zero;
514 }
515
517 }

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

◆ is_equal()

◆ is_gt()

template<typename T>
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 486 of file ct_utils.h.

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

References is_lt(), and Mask().

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

◆ is_gte()

template<typename T>
constexpr Mask< T > Botan::CT::Mask< T >::is_gte ( T x,
T y )
inlinestaticconstexpr

◆ is_lt()

template<typename T>
constexpr Mask< T > Botan::CT::Mask< T >::is_lt ( T x,
T y )
inlinestaticconstexpr

◆ is_lte()

template<typename T>
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 491 of file ct_utils.h.

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

Definition at line 498 of file ct_utils.h.

498 {
499 //return Mask<T>::is_gte(v, l) & Mask<T>::is_lte(v, u);
500
501 const T v_lt_l = v ^ ((v ^ l) | ((v - l) ^ v));
502 const T v_gt_u = u ^ ((u ^ v) | ((u - v) ^ u));
505 }

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

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

References Mask(), and value().

◆ operator=() [1/2]

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

References Mask().

◆ operator=() [2/2]

template<typename T>
Mask< T > & Botan::CT::Mask< T >::operator= ( 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 530 of file ct_utils.h.

530 {
531 m_mask ^= o.value();
532 return (*this);
533 }

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

538 {
539 m_mask |= o.value();
540 return (*this);
541 }

References Mask(), and value().

◆ operator~()

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

Negate this mask

Definition at line 561 of file ct_utils.h.

561{ 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 576 of file ct_utils.h.

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

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

Referenced by 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 578 of file ct_utils.h.

578 {
579 T r = this->select(x, y);
581 return r;
582 }

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

587{ 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 593 of file ct_utils.h.

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

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

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

◆ set()

template<typename T>
constexpr Mask< T > Botan::CT::Mask< T >::set ( )
inlinestaticconstexpr

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

Definition at line 410 of file ct_utils.h.

410{ 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 626 of file ct_utils.h.

626 {
627 T r = value();
629 return r;
630 }

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

658{ 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().

◆ operator&

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

AND-combine two masks

Definition at line 546 of file ct_utils.h.

546{ 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 551 of file ct_utils.h.

551{ 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 556 of file ct_utils.h.

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

References Mask(), and value().


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