Struct Choice

Source

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

Expand description

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§

Source §

impl Choice

Source

pub const FALSE: Self

Equivalent of false.

Source

pub const TRUE: Self

Equivalent of true.

Source

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

Create a new Choice from the given u8 value, which MUST be either 0 or 1.

§Panics

in debug builds, panics if the value is anything other than 0 or 1.

Source

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.

Source

pub fn to_u8(self) -> u8

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

Source

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.

Source

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.

Source

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

Apply an and conditional to the given Choices.

Source

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

Apply an or conditional to the given Choices.

Source

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

Apply an xor conditional to the given Choices.

Source

pub const fn not(self) -> Choice

Compute the boolean inverse of self.

Source

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

const fn equality operation.

Source

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

const fn not equal operation.

Source

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

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

Source

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

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

Source

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

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

Source

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

Initialize from the least significant bit of a u32.

Source

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

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

Source

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

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

Source

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

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

Source

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

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

Source

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

Initialize from the least significant bit of a u64.

Source

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

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

Source

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

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

Source

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

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

Source

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

Initialize from the least significant bit of a u128.

Source

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.

Source

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.

Source

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.

Source

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.

Source