Struct subtle::CtOption

pub struct CtOption<T> { /* private fields */ }

The CtOption<T> type represents an optional value similar to the Option<T> type but is intended for use in constant time APIs.

Any given CtOption<T> is either Some or None, but unlike Option<T> these variants are not exposed. The is_some() method is used to determine if the value is Some, and unwrap_or() and unwrap_or_else() methods are provided to access the underlying value. The value can also be obtained with unwrap() but this will panic if it is None.

Functions that are intended to be constant time may not produce valid results for all inputs, such as square root and inversion operations in finite field arithmetic. Returning an Option<T> from these functions makes it difficult for the caller to reason about the result in constant time, and returning an incorrect value burdens the caller and increases the chance of bugs.

Implementations

impl<T> CtOption<T>

pub fn new(value: T, is_some: Choice) -> CtOption<T>

This method is used to construct a new CtOption<T> and takes a value of type T, and a Choice that determines whether the optional value should be Some or not. If is_some is false, the value will still be stored but its value is never exposed.

pub fn expect(self, msg: &str) -> T

Returns the contained value, consuming the self value.

Panics

Panics if the value is none with a custom panic message provided by msg.

pub fn unwrap(self) -> T

This returns the underlying value but panics if it is not Some.

pub fn unwrap_or(self, def: T) -> T

where T: ConditionallySelectable,

This returns the underlying value if it is Some or the provided value otherwise.

pub fn unwrap_or_else<F>(self, f: F) -> T

where T: ConditionallySelectable, F: FnOnce() -> T,

This returns the underlying value if it is Some or the value produced by the provided closure otherwise.

This operates in constant time, because the provided closure is always called.

pub fn is_some(&self) -> Choice

Returns a true Choice if this value is Some.

pub fn is_none(&self) -> Choice

Returns a true Choice if this value is None.

pub fn map<U, F>(self, f: F) -> CtOption<U>

where T: Default + ConditionallySelectable, F: FnOnce(T) -> U,

Returns a None value if the option is None, otherwise returns a CtOption enclosing the value of the provided closure. The closure is given the enclosed value or, if the option is None, it is provided a dummy value computed using Default::default().

This operates in constant time, because the provided closure is always called.

pub fn and_then<U, F>(self, f: F) -> CtOption<U>

where T: Default + ConditionallySelectable, F: FnOnce(T) -> CtOption<U>,

Returns a None value if the option is None, otherwise returns the result of the provided closure. The closure is given the enclosed value or, if the option is None, it is provided a dummy value computed using Default::default().

This operates in constant time, because the provided closure is always called.

pub fn or_else<F>(self, f: F) -> CtOption<T>

where T: ConditionallySelectable, F: FnOnce() -> CtOption<T>,

Returns self if it contains a value, and otherwise returns the result of calling f. The provided function f is always called.

Trait Implementations

impl<T: Clone> Clone for CtOption<T>

fn clone(&self) -> CtOption<T>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: ConditionallySelectable> ConditionallySelectable for CtOption<T>

fn conditional_select(a: &Self, b: &Self, choice: Choice) -> Self

Select a or b according to choice.

fn conditional_assign(&mut self, other: &Self, choice: Choice)

Conditionally assign other to self, according to choice.

fn conditional_swap(a: &mut Self, b: &mut Self, choice: Choice)

Conditionally swap self and other if choice == 1; otherwise, reassign both unto themselves.

impl<T: ConstantTimeEq> ConstantTimeEq for CtOption<T>

fn ct_eq(&self, rhs: &CtOption<T>) -> Choice

Two CtOption<T>s are equal if they are both Some and their values are equal, or both None.

fn ct_ne(&self, other: &Self) -> Choice

Determine if two items are NOT equal.

impl<T: Debug> Debug for CtOption<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> From<CtOption<T>> for Option<T>

fn from(source: CtOption<T>) -> Option<T>

Convert the CtOption<T> wrapper into an Option<T>, depending on whether the underlying is_some Choice was a 0 or a 1 once unwrapped.

Note

This function exists to avoid ending up with ugly, verbose and/or bad handled conversions from the CtOption<T> wraps to an Option<T> or Result<T, E>. This implementation doesn’t intend to be constant-time nor try to protect the leakage of the T since the Option<T> will do it anyways.

impl<T: Copy> Copy for CtOption<T>