Struct timing_shield::TpBool

pub struct TpBool(_);

A boolean type that prevents its value from being leaked to attackers through timing information.

let protected = TpBool::protect(some_boolean);

// Use `protected` from now on instead of `some_boolean`

Use the protect method as early as possible in the computation for maximum protection:

// DANGEROUS:
let badly_protected_boolean = TpU8::protect(some_boolean as u8);

// Safe:
let protected = TpBool::protect(some_boolean).as_u8();

// DANGEROUS:
let badly_protected_value = TpBool::protect(byte1 == byte2);

// Safe:
let protected_bool = TpU8::protect(byte1).tp_eq(&TpU8::protect(byte2));

Note that & and | are provided instead of && and || because the usual boolean short-circuiting behaviour leaks information about the values of the booleans.

Methods

impl TpBool

fn protect(input: bool) -> Self

Hide input behind a protective abstraction to prevent the value from being used in such a way that the value could leak out via a timing side channel.

let protected_bool = TpBool::protect(some_secret_bool);

// Use `protected_bool` instead of `some_secret_bool` to avoid timing leaks

fn as_u8(self) -> TpU8

Casts from one number type to another, following the same conventions as Rust's as keyword.

fn as_u16(self) -> TpU16

Casts from one number type to another, following the same conventions as Rust's as keyword.

fn as_u32(self) -> TpU32

Casts from one number type to another, following the same conventions as Rust's as keyword.

fn as_u64(self) -> TpU64

Casts from one number type to another, following the same conventions as Rust's as keyword.

fn as_i8(self) -> TpI8

Casts from one number type to another, following the same conventions as Rust's as keyword.

fn as_i16(self) -> TpI16

Casts from one number type to another, following the same conventions as Rust's as keyword.

fn as_i32(self) -> TpI32

Casts from one number type to another, following the same conventions as Rust's as keyword.

fn as_i64(self) -> TpI64

Casts from one number type to another, following the same conventions as Rust's as keyword.

fn expose(self) -> bool

Remove the timing protection and expose the raw boolean value. Once the boolean is exposed, it is the library user's responsibility to prevent timing leaks (if necessary). Note: this can be very difficult to do correctly with boolean values.

Commonly, this method is used when a value is safe to make public (e.g. the result of a signature verification).

fn cond_swap<T: ?Sized>(self, a: &mut T, b: &mut T) where
    T: TpCondSwap, 

Constant-time conditional swap. Swaps a and b if this boolean is true, otherwise has no effect. This operation is implemented without branching on the boolean value, and it will not leak information about whether the values were swapped.

fn select<T>(self, when_true: T, when_false: T) -> T where
    T: TpCondSwap, 

Returns one of the arguments, depending on the value of this boolean. The return value is selected without branching on the boolean value, and no information about which value was selected will be leaked.

Trait Implementations

impl Clone for TpBool

fn clone(&self) -> TpBool

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for TpBool

impl Not for TpBool

type Output = TpBool

The resulting type after applying the ! operator

fn not(self) -> TpBool

The method for the unary ! operator

impl BitAnd<TpBool> for TpBool

type Output = TpBool

The resulting type after applying the & operator

fn bitand(self, other: TpBool) -> TpBool

The method for the & operator

impl BitAnd<bool> for TpBool

type Output = TpBool

The resulting type after applying the & operator

fn bitand(self, other: bool) -> TpBool

The method for the & operator

impl BitOr<TpBool> for TpBool

type Output = TpBool

The resulting type after applying the | operator

fn bitor(self, other: TpBool) -> TpBool

The method for the | operator

impl BitOr<bool> for TpBool

type Output = TpBool

The resulting type after applying the | operator

fn bitor(self, other: bool) -> TpBool

The method for the | operator

impl BitXor<TpBool> for TpBool

type Output = TpBool

The resulting type after applying the ^ operator

fn bitxor(self, other: TpBool) -> TpBool

The method for the ^ operator

impl BitXor<bool> for TpBool

type Output = TpBool

The resulting type after applying the ^ operator

fn bitxor(self, other: bool) -> TpBool

The method for the ^ operator

impl BitAndAssign<TpBool> for TpBool

fn bitand_assign(&mut self, rhs: TpBool)

The method for the &= operator

impl BitAndAssign<bool> for TpBool

fn bitand_assign(&mut self, rhs: bool)

The method for the &= operator

impl BitOrAssign<TpBool> for TpBool

fn bitor_assign(&mut self, rhs: TpBool)

The method for the |= operator

impl BitOrAssign<bool> for TpBool

fn bitor_assign(&mut self, rhs: bool)

The method for the |= operator

impl BitXorAssign<TpBool> for TpBool

fn bitxor_assign(&mut self, rhs: TpBool)

The method for the ^= operator

impl BitXorAssign<bool> for TpBool

fn bitxor_assign(&mut self, rhs: bool)

The method for the ^= operator

impl TpEq<TpBool> for TpBool

fn tp_eq(&self, other: &TpBool) -> TpBool

Compare self with other for equality without leaking the result. Important: if either input is not a timing-protected type, this operation might leak the value of that type. To prevent timing leaks, protect values before performing any operations on them.

fn tp_not_eq(&self, other: &TpBool) -> TpBool

Compare self with other for inequality without leaking the result. Important: if either input is not a timing-protected type, this operation might leak the value of that type. To prevent timing leaks, protect values before performing any operations on them.

impl TpEq<bool> for TpBool

fn tp_eq(&self, other: &bool) -> TpBool

Compare self with other for equality without leaking the result. Important: if either input is not a timing-protected type, this operation might leak the value of that type. To prevent timing leaks, protect values before performing any operations on them.

fn tp_not_eq(&self, other: &bool) -> TpBool

Compare self with other for inequality without leaking the result. Important: if either input is not a timing-protected type, this operation might leak the value of that type. To prevent timing leaks, protect values before performing any operations on them.

impl TpCondSwap for TpBool

fn tp_cond_swap(condition: TpBool, a: &mut TpBool, b: &mut TpBool)

Swap a and b if and only if condition is true.