Struct Choice 

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

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

This type attempts to hint to the compiler and its codegen backends that optimizations should not be applied which depend on specific values of this type.

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 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 Choice::TRUE if x == y, and Choice::FALSE otherwise.

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

Returns Choice::TRUE if x == y, and Choice::FALSE otherwise.

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

Returns Choice::TRUE if x <= y and Choice::FALSE 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 Choice::TRUE if x < y, and Choice::FALSE otherwise.

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

Returns Choice::TRUE if value != 0, and Choice::FALSE otherwise.

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

Returns Choice::TRUE if x == y, and Choice::FALSE otherwise.

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

Returns Choice::TRUE if x <= y and Choice::FALSE 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 Choice::TRUE if x < y, and Choice::FALSE otherwise.

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

Returns Choice::TRUE if value != 0, and Choice::FALSE otherwise.

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

Returns Choice::TRUE if x == y, and Choice::FALSE otherwise.

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

Returns Choice::TRUE if x <= y and Choice::FALSE 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 Choice::TRUE if x < y, and Choice::FALSE otherwise.

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

Returns Choice::TRUE if value != 0, and Choice::FALSE otherwise.

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

Returns Choice::TRUE if x == y, and Choice::FALSE otherwise.

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

Returns Choice::TRUE if x <= y and Choice::FALSE 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 Choice::TRUE if x < y, and Choice::FALSE otherwise.

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

Returns Choice::TRUE if value != 0, and Choice::FALSE otherwise.

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

Returns Choice::TRUE if x == y, and Choice::FALSE otherwise.

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

Returns Choice::TRUE if x <= y and Choice::FALSE 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 Choice::TRUE if x < y, and Choice::FALSE otherwise.

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

Returns Choice::TRUE if value != 0, and Choice::FALSE otherwise.

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

const fn helper: return b if self is Choice::TRUE, 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_u8(self, a: u8, b: u8) -> u8

const fn helper: return b if self is Choice::TRUE, 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_u16(self, a: u16, b: u16) -> u16

const fn helper: return b if self is Choice::TRUE, 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 Choice::TRUE, 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 Choice::TRUE, 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 Choice::TRUE, 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 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 to_u8_mask(self) -> u8

Create a u8 bitmask.

Returns

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

pub const fn to_u16_mask(self) -> u16

Create a u16 bitmask.

Returns

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

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

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

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

impl CtAssignSlice for Choice

fn ct_assign_slice(dst: &mut [Self], src: &[Self], choice: Choice)

Conditionally assign src to dst if choice is Choice::TRUE, or leave it unchanged for Choice::FALSE.

impl CtEq for Choice

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

Determine if self is equal to other in constant-time.

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

Determine if self is NOT equal to other in constant-time.

impl CtEqSlice for Choice

fn ct_eq_slice(a: &[Self], b: &[Self]) -> Choice

Determine if a is equal to b in constant-time.

fn ct_ne_slice(a: &[Self], b: &[Self]) -> Choice

Determine if a is NOT equal to b in constant-time.

impl Debug for Choice

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

Formats the value using the given formatter.

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

impl CtSelectUsingCtAssign for Choice