Skip to content

ctutils: add Choice::to_u8_mask/to_u16_mask #1322

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tarcieri merged 1 commit into from
Jan 3, 2026
Merged

ctutils: add Choice::to_u8_mask/to_u16_mask #1322

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
194 changes: 124 additions & 70 deletions ctutils/src/choice.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,61 +45,8 @@ impl Choice {
/// Equivalent of [`true`].
pub const TRUE: Self = Self(1);

/// Convert `Choice` into a `bool`.
///
/// <div class = "warning">
/// <b>Security Warning</b>
///
/// 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.
/// </div>
// TODO(tarcieri): `const fn` when MSRV 1.86
pub fn to_bool(self) -> bool {
self.to_u8() != 0
}

/// Convert [`Choice`] to a `u8`, attempting to apply a "best effort" optimization barrier.
// TODO(tarcieri): `const fn` when MSRV 1.86
pub fn to_u8(self) -> u8 {
// `black_box` is documented as working on a "best effort" basis. That's fine, this type is
// likewise documented as only working on a "best effort" basis itself. The only way we
// rely on `black_box` for correctness is it behaving as the identity function.
core::hint::black_box(self.0)
}

/// HACK: workaround to allow `const fn` boolean support on Rust 1.85.
///
/// This does not apply `black_box` to the output.
///
/// <div class = "warning">
/// <b>Security Warning</b>
///
/// See the security warnings for [`Choice::to_bool`].
/// </div>
// TODO(tarcieri): deprecate/remove this in favor of `to_bool` when MSRV is Rust 1.86
pub const fn to_bool_vartime(self) -> bool {
self.0 != 0
}

/// HACK: workaround to allow `const fn` boolean support on Rust 1.85.
///
/// This does not apply `black_box` to the output.
// TODO(tarcieri): deprecate/remove this in favor of `to_u8` when MSRV is Rust 1.86
pub const fn to_u8_vartime(self) -> u8 {
self.0
}

//
// Bitwise ops
// `const fn` bitwise ops
//

/// Apply an `and` conditional to the given [`Choice`]s.
Expand Down Expand Up @@ -128,7 +75,7 @@ impl Choice {
}

//
// Comparison ops
// `const fn` comparison ops
//

/// `const fn` equality operation.
Expand Down Expand Up @@ -355,14 +302,91 @@ impl Choice {
a ^ (self.to_u128_mask() & (a ^ b))
}

//
// Output conversion methods
//

/// Convert `Choice` into a `bool`.
///
/// <div class = "warning">
/// <b>Security Warning</b>
///
/// 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.
/// </div>
// TODO(tarcieri): `const fn` when MSRV 1.86
pub fn to_bool(self) -> bool {
self.to_u8() != 0
}

/// Convert [`Choice`] to a `u8`, attempting to apply a "best effort" optimization barrier.
// TODO(tarcieri): `const fn` when MSRV 1.86
pub fn to_u8(self) -> u8 {
// `black_box` is documented as working on a "best effort" basis. That's fine, this type is
// likewise documented as only working on a "best effort" basis itself. The only way we
// rely on `black_box` for correctness is it behaving as the identity function.
core::hint::black_box(self.0)
}

/// HACK: workaround to allow `const fn` boolean support on Rust 1.85.
///
/// This does not apply `black_box` to the output.
///
/// <div class = "warning">
/// <b>Security Warning</b>
///
/// See the security warnings for [`Choice::to_bool`].
/// </div>
// TODO(tarcieri): deprecate/remove this in favor of `to_bool` when MSRV is Rust 1.86
pub const fn to_bool_vartime(self) -> bool {
self.0 != 0
}

/// HACK: workaround to allow `const fn` boolean support on Rust 1.85.
///
/// This does not apply `black_box` to the output.
// TODO(tarcieri): deprecate/remove this in favor of `to_u8` when MSRV is Rust 1.86
pub const fn to_u8_vartime(self) -> u8 {
self.0
}

/// Create a `u8` bitmask.
///
/// # Returns
/// - `0` for `Choice::FALSE`
/// - `u8::MAX` for `Choice::TRUE`
#[inline]
pub const fn to_u8_mask(self) -> u8 {
self.0.wrapping_neg()
}

/// Create a `u16` bitmask.
///
/// # Returns
/// - `0` for `Choice::FALSE`
/// - `u16::MAX` for `Choice::TRUE`
#[inline]
pub const fn to_u16_mask(self) -> u16 {
(self.0 as u16).wrapping_neg()
}

/// Create a `u32` bitmask.
///
/// # Returns
/// - `0` for `Choice::FALSE`
/// - `u32::MAX` for `Choice::TRUE`
#[inline]
pub const fn to_u32_mask(self) -> u32 {
(self.0 as u32 & 1).wrapping_neg()
(self.0 as u32).wrapping_neg()
}

/// Create a `u64` bitmask.
Expand All @@ -372,7 +396,7 @@ impl Choice {
/// - `u64::MAX` for `Choice::TRUE`
#[inline]
pub const fn to_u64_mask(self) -> u64 {
(self.0 as u64 & 1).wrapping_neg()
(self.0 as u64).wrapping_neg()
}

/// Create a `u128` bitmask.
Expand All @@ -382,7 +406,7 @@ impl Choice {
/// - `u128::MAX` for `Choice::TRUE`
#[inline]
pub const fn to_u128_mask(self) -> u128 {
(self.0 as u128 & 1).wrapping_neg()
(self.0 as u128).wrapping_neg()
}
}

Expand Down Expand Up @@ -553,18 +577,6 @@ mod tests {
assert_eq!(a.ct_select(&b, Choice::TRUE).to_bool(), b.to_bool());
}

#[test]
fn to_bool() {
assert!(!Choice::FALSE.to_bool());
assert!(Choice::TRUE.to_bool());
}

#[test]
fn to_u8() {
assert_eq!(Choice::FALSE.to_u8(), 0);
assert_eq!(Choice::TRUE.to_u8(), 1);
}

#[test]
fn and() {
assert_eq!((Choice::FALSE & Choice::FALSE).to_u8(), 0);
Expand Down Expand Up @@ -813,4 +825,46 @@ mod tests {
assert_eq!(Choice::TRUE.select_u128(a, b), b);
assert_eq!(Choice::FALSE.select_u128(a, b), a);
}

#[test]
fn to_bool() {
assert!(!Choice::FALSE.to_bool());
assert!(Choice::TRUE.to_bool());
}

#[test]
fn to_u8() {
assert_eq!(Choice::FALSE.to_u8(), 0);
assert_eq!(Choice::TRUE.to_u8(), 1);
}

#[test]
fn to_u8_mask() {
assert_eq!(Choice::FALSE.to_u8_mask(), 0);
assert_eq!(Choice::TRUE.to_u8_mask(), u8::MAX);
}

#[test]
fn to_u16_mask() {
assert_eq!(Choice::FALSE.to_u16_mask(), 0);
assert_eq!(Choice::TRUE.to_u16_mask(), u16::MAX);
}

#[test]
fn to_u32_mask() {
assert_eq!(Choice::FALSE.to_u32_mask(), 0);
assert_eq!(Choice::TRUE.to_u32_mask(), u32::MAX);
}

#[test]
fn to_u64_mask() {
assert_eq!(Choice::FALSE.to_u64_mask(), 0);
assert_eq!(Choice::TRUE.to_u64_mask(), u64::MAX);
}

#[test]
fn to_u128_mask() {
assert_eq!(Choice::FALSE.to_u128_mask(), 0);
assert_eq!(Choice::TRUE.to_u128_mask(), u128::MAX);
}
}