Struct Choice 

pub struct Choice(/* private fields */);

Constant-time analogue of bool providing a “best effort” optimization barrier.

Attempts to hint to the compiler and its codegen backends that optimizations should not be applied which depend on a value.

This is used as a “belt-and-suspenders” defense in addition to mechanisms like constant-time predication intrinsics provided by the cmov crate, and is never expected to be the only line of defense.

Implementations

impl Choice

pub const FALSE: Self

Equivalent of false.

pub const TRUE: Self

Equivalent of true.

pub const fn new(value: u8) -> Self

👎Deprecated since 0.2.3: use Choice::from_u8_lsb instead

DEPRECATED: legacy alias for Choice::from_u8_lsb.

pub fn to_bool(self) -> bool

Convert Choice into a bool.

Security Warning

Using this function will introduce timing variability, since computing this at all currently requires a branch.

This is intended to be used as either the one and only branch at the end of a constant-time operation to e.g. differentiate between success and failure, or in contexts where constant-time doesn’t matter, e.g. variable-time code that operates on “maybe secret” types which aren’t secrets in a particular context.

If you are trying to use this in the context of a constant-time operation, be warned that the small amount of timing variability it introduces can potentially be exploited. Whenever possible, prefer fully constant-time approaches instead.

pub fn to_u8(self) -> u8

Convert Choice to a u8, attempting to apply a “best effort” optimization barrier.

pub const fn to_bool_vartime(self) -> bool

HACK: workaround to allow const fn boolean support on Rust 1.85.

This does not apply black_box to the output.

Security Warning

See the security warnings for Choice::to_bool.

pub const fn to_u8_vartime(self) -> u8

HACK: workaround to allow const fn boolean support on Rust 1.85.

This does not apply black_box to the output.

pub const fn and(self, rhs: Choice) -> Choice

Apply an and conditional to the given Choices.

pub const fn or(self, rhs: Choice) -> Choice

Apply an or conditional to the given Choices.

pub const fn xor(self, rhs: Choice) -> Choice

Apply an xor conditional to the given Choices.

pub const fn not(self) -> Choice

Compute the boolean inverse of self.

pub const fn eq(self, other: Self) -> Self

const fn equality operation.

pub const fn ne(self, other: Self) -> Self

const fn not equal operation.

pub const fn from_i64_eq(x: i64, y: i64) -> Self

Returns the truthy value if x == y, and the falsy value otherwise.

pub const fn from_u8_eq(x: u8, y: u8) -> Self

Returns the truthy value if x == y, and the falsy value otherwise.

pub const fn from_u8_le(x: u8, y: u8) -> Self

Returns the truthy value if x <= y and the falsy value otherwise.

pub const fn from_u8_lsb(value: u8) -> Self

Initialize from the least significant bit of a u8.

pub const fn from_u8_lt(x: u8, y: u8) -> Self

Returns the truthy value if x < y, and the falsy value otherwise.

pub const fn from_u8_nz(value: u8) -> Self

Returns the truthy value if value != 0, and the falsy value otherwise.

pub const fn from_u16_eq(x: u16, y: u16) -> Self

Returns the truthy value if x == y, and the falsy value otherwise.

pub const fn from_u16_le(x: u16, y: u16) -> Self

Returns the truthy value if x <= y and the falsy value otherwise.

pub const fn from_u16_lsb(value: u16) -> Self

Initialize from the least significant bit of a u16.

pub const fn from_u16_lt(x: u16, y: u16) -> Self

Returns the truthy value if x < y, and the falsy value otherwise.

pub const fn from_u16_nz(value: u16) -> Self

Returns the truthy value if value != 0, and the falsy value otherwise.

pub const fn from_u32_eq(x: u32, y: u32) -> Self

Returns the truthy value if x == y, and the falsy value otherwise.

pub const fn from_u32_le(x: u32, y: u32) -> Self

Returns the truthy value if x <= y and the falsy value otherwise.

pub const fn from_u32_lsb(value: u32) -> Self

Initialize from the least significant bit of a u32.

pub const fn from_u32_lt(x: u32, y: u32) -> Self

Returns the truthy value if x < y, and the falsy value otherwise.

pub const fn from_u32_nz(value: u32) -> Self

Returns the truthy value if value != 0, and the falsy value otherwise.

pub const fn from_u64_eq(x: u64, y: u64) -> Self

Returns the truthy value if x == y, and the falsy value otherwise.

pub const fn from_u64_le(x: u64, y: u64) -> Self

Returns the truthy value if x <= y and the falsy value otherwise.

pub const fn from_u64_lsb(value: u64) -> Self

Initialize from the least significant bit of a u64.

pub const fn from_u64_lt(x: u64, y: u64) -> Self

Returns the truthy value if x < y, and the falsy value otherwise.

pub const fn from_u64_nz(value: u64) -> Self

Returns the truthy value if value != 0, and the falsy value otherwise.

pub const fn from_u128_eq(x: u128, y: u128) -> Self

Returns the truthy value if x == y, and the falsy value otherwise.

pub const fn from_u128_le(x: u128, y: u128) -> Self

Returns the truthy value if x <= y and the falsy value otherwise.

pub const fn from_u128_lsb(value: u128) -> Self

Initialize from the least significant bit of a u128.

pub const fn from_u128_lt(x: u128, y: u128) -> Self

Returns the truthy value if x < y, and the falsy value otherwise.

pub const fn from_u128_nz(value: u128) -> Self

Returns the truthy value if value != 0, and the falsy value otherwise.

pub const fn select_i64(self, a: i64, b: i64) -> i64

const fn helper: return b if self is truthy, otherwise return a.

Only use this instead of the CtSelect trait in the event you’re in a const fn context and can’t use the trait. The former will provide better constant-time assurances.

pub const fn select_u32(self, a: u32, b: u32) -> u32

const fn helper: return b if self is truthy, otherwise return a.

Only use this instead of the CtSelect trait in the event you’re in a const fn context and can’t use the trait. The former will provide better constant-time assurances.

pub const fn select_u64(self, a: u64, b: u64) -> u64

const fn helper: return b if self is truthy, otherwise return a.

Only use this instead of the CtSelect trait in the event you’re in a const fn context and can’t use the trait. The former will provide better constant-time assurances.

pub const fn select_u128(self, a: u128, b: u128) -> u128

const fn helper: return b if self is truthy, otherwise return a.

Only use this instead of the CtSelect trait in the event you’re in a const fn context and can’t use the trait. The former will provide better constant-time assurances.

pub const fn to_u32_mask(self) -> u32

Create a u32 bitmask.

Returns

• 0 for Choice::FALSE
• u32::MAX for Choice::TRUE

pub const fn to_u64_mask(self) -> u64

Create a u64 bitmask.

Returns

• 0 for Choice::FALSE
• u64::MAX for Choice::TRUE

pub const fn to_u128_mask(self) -> u128

Create a u128 bitmask.

Returns

• 0 for Choice::FALSE
• u128::MAX for Choice::TRUE

Trait Implementations

impl BitAnd for Choice

type Output = Choice

The resulting type after applying the & operator.

fn bitand(self, rhs: Choice) -> Choice

Performs the & operation.

impl BitAndAssign for Choice

fn bitand_assign(&mut self, rhs: Choice)

Performs the &= operation.

impl BitOr for Choice

type Output = Choice

The resulting type after applying the | operator.

fn bitor(self, rhs: Choice) -> Choice

Performs the | operation.

impl BitOrAssign for Choice

fn bitor_assign(&mut self, rhs: Choice)

Performs the |= operation.

impl BitXor for Choice

type Output = Choice

The resulting type after applying the ^ operator.

fn bitxor(self, rhs: Choice) -> Choice

Performs the ^ operation.

impl BitXorAssign for Choice

fn bitxor_assign(&mut self, rhs: Choice)

Performs the ^= operation.

impl Clone for Choice

fn clone(&self) -> Choice

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl ConditionallySelectable for Choice

Available on crate feature subtle only.

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 ConstantTimeEq for Choice

Available on crate feature subtle only.

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

Determine if two items are equal.

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

Determine if two items are NOT equal.

impl CtEq for Choice

fn ct_eq(&self, other: &Self) -> Self

Equality

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

Inequality

impl CtSelect for Choice

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

Select between self and other based on choice, returning a copy of the value.

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

Conditionally assign other to self if choice is Choice::TRUE.

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

Conditionally swap self and other if choice is Choice::TRUE.

impl Debug for Choice

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

Formats the value using the given formatter.

impl From<Choice> for Choice

Available on crate feature subtle only.

fn from(choice: Choice) -> Choice

Converts to this type from the input type.

impl From<Choice> for Choice

Available on crate feature subtle only.

fn from(choice: Choice) -> Choice

Converts to this type from the input type.

impl From<Choice> for bool

Convert Choice into a bool.

Security Warning

Using this function will introduce timing variability, since computing this at all currently requires a branch.

See the security warnings for Choice::to_bool.

fn from(choice: Choice) -> bool

Converts to this type from the input type.

impl From<Choice> for u8

fn from(choice: Choice) -> u8

Converts to this type from the input type.

impl From<u8> for Choice

DEPRECATED: this exists to aid migrating code from subtle. Use Choice::from_u8_lsb instead.

Note

Rust doesn’t actually let us deprecate an impl block, however this comment is here to discourage future use and warn that this will be removed in a future release.

fn from(value: u8) -> Self

Converts to this type from the input type.

impl Not for Choice

type Output = Choice

The resulting type after applying the ! operator.

fn not(self) -> Choice

Performs the unary ! operation.

impl PartialEq for Choice

fn eq(&self, other: &Choice) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for Choice

impl Eq for Choice

impl StructuralPartialEq for Choice