Struct subtle::CtOption

source ·
pub struct CtOption<T> { /* private fields */ }
Expand description

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§

source§

impl<T> CtOption<T>

source

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.

source

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.

source

pub fn unwrap(self) -> T

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

source

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

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

source

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.

source

pub fn is_some(&self) -> Choice

Returns a true Choice if this value is Some.

source

pub fn is_none(&self) -> Choice

Returns a true Choice if this value is None.

source

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.

source

pub fn and_then<U, F>(self, f: F) -> 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.

source

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

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

source

pub fn into_option(self) -> 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.

It’s equivalent to the corresponding From impl, however this version is friendlier for type inference.

Trait Implementations§

source§

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

source§

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

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

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

source§

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

Select a or b according to choice. Read more
source§

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

Conditionally assign other to self, according to choice. Read more
source§

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

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

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

source§

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.

source§

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

Determine if two items are NOT equal. Read more
source§

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

source§

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

Formats the value using the given formatter. Read more
source§

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

source§

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.

source§

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

Auto Trait Implementations§

§

impl<T> Freeze for CtOption<T>
where T: Freeze,

§

impl<T> RefUnwindSafe for CtOption<T>
where T: RefUnwindSafe,

§

impl<T> Send for CtOption<T>
where T: Send,

§

impl<T> Sync for CtOption<T>
where T: Sync,

§

impl<T> Unpin for CtOption<T>
where T: Unpin,

§

impl<T> UnwindSafe for CtOption<T>
where T: UnwindSafe,

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> CloneToUninit for T
where T: Copy,

source§

unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
source§

impl<T> CloneToUninit for T
where T: Clone,

source§

default unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.