subtle

https://docs.rs/subtle/latest/subtle
Admin
Pure-Rust traits and utilities for constant-time cryptographic implementations, providing a `Choice`...
Tokens:10,445
Snippets:174
Trust Score:9.7
Update:2 months ago
Show doc for...
Tokens:
Raw
### ConstantTimeLess Usage Example

Source: https://docs.rs/subtle/latest/subtle/trait.ConstantTimeLess.html

Demonstrates using the ct_lt method to compare two unsigned integers in constant time.

```rust
use subtle::ConstantTimeLess;

let x: u8 = 13;
let y: u8 = 42;

let x_lt_y = x.ct_lt(&y);

assert_eq!(x_lt_y.unwrap_u8(), 1);

let y_lt_x = y.ct_lt(&x);

assert_eq!(y_lt_x.unwrap_u8(), 0);

let x_lt_x = x.ct_lt(&x);

assert_eq!(x_lt_x.unwrap_u8(), 0);
```

--------------------------------

### ConstantTimeEq Slice Comparison

Source: https://docs.rs/subtle/latest/subtle/trait.ConstantTimeEq.html

Example demonstrating how to use ct_eq with fixed-size arrays, which coerce to slices.

```rust
let a: [u8; 8] = [0,1,2,3,4,5,6,7];
let b: [u8; 8] = [0,1,2,3,0,1,2,3];

let a_eq_a = a.ct_eq(&a);
let a_eq_b = a.ct_eq(&b);

assert_eq!(a_eq_a.unwrap_u8(), 1);
assert_eq!(a_eq_b.unwrap_u8(), 0);
```

--------------------------------

### ConstantTimeEq Usage Example

Source: https://docs.rs/subtle/latest/subtle/trait.ConstantTimeEq.html

Basic usage of the ct_eq method to compare two u8 values.

```rust
use subtle::ConstantTimeEq;
let x: u8 = 5;
let y: u8 = 13;

assert_eq!(x.ct_eq(&y).unwrap_u8(), 0);
assert_eq!(x.ct_eq(&x).unwrap_u8(), 1);
```

--------------------------------

### ConstantTimeGreater Usage Example

Source: https://docs.rs/subtle/latest/subtle/trait.ConstantTimeGreater.html

Demonstrates comparing two u8 values using the ct_gt method and verifying the result with Choice.

```rust
use subtle::ConstantTimeGreater;

let x: u8 = 13;
let y: u8 = 42;

let x_gt_y = x.ct_gt(&y);

assert_eq!(x_gt_y.unwrap_u8(), 0);

let y_gt_x = y.ct_gt(&x);

assert_eq!(y_gt_x.unwrap_u8(), 1);

let x_gt_x = x.ct_gt(&x);

assert_eq!(x_gt_x.unwrap_u8(), 0);
```

--------------------------------

### BlackBox::new

Source: https://docs.rs/subtle/latest/subtle/struct.BlackBox.html?search=std%3A%3Avec

Constructs a new instance of BlackBox wrapping the provided value.

```APIDOC
## pub fn new<T: Copy>(value: T) -> BlackBox<T>

### Description
Constructs a new instance of `BlackBox` which will wrap the specified value. All access to the inner value will be mediated by a `black_box` optimization barrier.

### Parameters
- **value** (T) - Required - The value to wrap in the BlackBox.
```

--------------------------------

### Add subtle dependency

Source: https://docs.rs/subtle/latest/subtle/index.html?search=u32+-%3E+bool

Include the subtle crate in your Cargo.toml file.

```toml
subtle = "2.6"
```

--------------------------------

### BlackBox::get

Source: https://docs.rs/subtle/latest/subtle/struct.BlackBox.html?search=

Reads the inner value, applying an optimization barrier on access.

```APIDOC
## pub fn get<T: Copy>(self) -> T

### Description
Read the inner value, applying an optimization barrier on access.
```

--------------------------------

### BlackBox::new

Source: https://docs.rs/subtle/latest/subtle/struct.BlackBox.html?search=

Constructs a new instance of BlackBox which will wrap the specified value. All access to the inner value will be mediated by a black_box optimization barrier.

```APIDOC
## pub fn new<T: Copy>(value: T) -> BlackBox<T>

### Description
Constructs a new instance of `BlackBox` which will wrap the specified value. All access to the inner value will be mediated by a `black_box` optimization barrier.
```

--------------------------------

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

Source: https://docs.rs/subtle/latest/subtle/trait.ConstantTimeLess.html

Determines whether the current instance is less than the provided instance in constant time.

```APIDOC
## fn ct_lt(&self, other: &Self) -> Choice

### Description
Determine whether `self < other` in constant time. The bitwise-NOT of the return value can be used to determine if `self >= other`.

### Parameters
- **other** (&Self) - The value to compare against.

### Returns
- **Choice** - A `Choice` with a set bit if `self < other`, and with no set bits otherwise.

### Example
```rust
use subtle::ConstantTimeLess;

let x: u8 = 13;
let y: u8 = 42;

let x_lt_y = x.ct_lt(&y);
assert_eq!(x_lt_y.unwrap_u8(), 1);
```
```

--------------------------------

### subtle::BlackBox::try_from

Source: https://docs.rs/subtle/latest/subtle/trait.ConditionallySelectable.html?search=u32+-%3E+bool

Converts a u32 value to a bool within the context of BlackBox.

```APIDOC
## method subtle::BlackBox::try_from

### Description
Converts a u32 value to a bool.

### Signature
`try_from(u32) -> Result<bool>`
```

--------------------------------

### ct_lt

Source: https://docs.rs/subtle/latest/subtle/trait.ConstantTimeLess.html?search=

Determines whether the current instance is less than the provided instance in constant time.

```APIDOC
## fn ct_lt(&self, other: &Self) -> Choice

### Description
Determines whether `self < other` in constant time. The return value is a `Choice` type, where a set bit indicates the condition is true.

### Parameters
- **other** (&Self) - Required - The value to compare against.

### Returns
- **Choice** - A `Choice` object with a set bit if `self < other`, and no set bits otherwise.

### Example
```rust
use subtle::ConstantTimeLess;

let x: u8 = 13;
let y: u8 = 42;

let x_lt_y = x.ct_lt(&y);
assert_eq!(x_lt_y.unwrap_u8(), 1);
```
```

--------------------------------

### subtle::CtOption::try_from

Source: https://docs.rs/subtle/latest/subtle/trait.ConditionallySelectable.html?search=u32+-%3E+bool

Converts a u32 value to a bool within the context of CtOption.

```APIDOC
## method subtle::CtOption::try_from

### Description
Converts a u32 value to a bool.

### Signature
`try_from(u32) -> Result<bool>`
```

--------------------------------

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

Source: https://docs.rs/subtle/latest/subtle/trait.ConstantTimeGreater.html

Determines whether the current instance is greater than the provided instance in constant time.

```APIDOC
## fn ct_gt(&self, other: &Self) -> Choice

### Description
Determines whether `self > other` in constant time. The return value is a `Choice` with a set bit if `self > other`, and no set bits otherwise.

### Parameters
- **other** (&Self) - Required - The value to compare against.

### Returns
- **Choice** - A `Choice` indicating the result of the comparison.
```

--------------------------------

### subtle::CtOption::unwrap_or_else

Source: https://docs.rs/subtle/latest/subtle/trait.ConditionallySelectable.html?search=u32+-%3E+bool

Returns the underlying value if it is Some or the provided fallback.

```APIDOC
## method subtle::CtOption::unwrap_or_else

### Description
Returns the underlying value if it is Some or the provided fallback value.

### Signature
`unwrap_or_else(CtOption<bool>, u32) -> bool`
```

--------------------------------

### Define Choice struct

Source: https://docs.rs/subtle/latest/subtle/struct.Choice.html

The internal structure definition for Choice.

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

--------------------------------

### ct_eq

Source: https://docs.rs/subtle/latest/subtle/trait.ConstantTimeEq.html?search=std%3A%3Avec

Determines if two items are equal in constant time.

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

### Description
Determine if two items are equal. This function should execute in constant time.

### Returns
- Choice(1u8) if self == other
- Choice(0u8) if self != other
```

--------------------------------

### ct_ne

Source: https://docs.rs/subtle/latest/subtle/trait.ConstantTimeEq.html?search=std%3A%3Avec

Determines if two items are not equal in constant time.

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

### Description
Determine if two items are NOT equal. This function should execute in constant time.

### Returns
- Choice(0u8) if self == other
- Choice(1u8) if self != other
```

--------------------------------

### conditional_swap

Source: https://docs.rs/subtle/latest/subtle/trait.ConditionallySelectable.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Conditionally swaps two values in constant time based on the provided Choice.

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

### Description
Swaps the values of 'a' and 'b' if the choice is 1, otherwise performs no swap.

### Parameters
- **a** (&mut Self) - First value to swap.
- **b** (&mut Self) - Second value to swap.
- **choice** (Choice) - The condition for the swap.
```

--------------------------------

### subtle::Choice::try_from

Source: https://docs.rs/subtle/latest/subtle/trait.ConditionallySelectable.html?search=u32+-%3E+bool

Converts a u32 value to a bool using the try_from method.

```APIDOC
## method subtle::Choice::try_from

### Description
Converts a u32 value to a bool.

### Signature
`try_from(u32) -> Result<bool>`
```

--------------------------------

### Use conditional_select for constant-time selection

Source: https://docs.rs/subtle/latest/subtle/trait.ConditionallySelectable.html

Selects between two values based on a Choice, returning the first if the choice is 0 and the second if it is 1.

```rust
use subtle::ConditionallySelectable;
let x: u8 = 13;
let y: u8 = 42;

let z = u8::conditional_select(&x, &y, 0.into());
assert_eq!(z, x);
let z = u8::conditional_select(&x, &y, 1.into());
assert_eq!(z, y);
```

--------------------------------

### CtOption Struct Definition

Source: https://docs.rs/subtle/latest/subtle/struct.CtOption.html?search=

The definition of the CtOption struct with private fields.

```rust
pub struct CtOption<T> { /* private fields */ }
```

--------------------------------

### ConstantTimeEq::ct_ne

Source: https://docs.rs/subtle/latest/subtle/trait.ConstantTimeEq.html?search=u32+-%3E+bool

Determines if two items are NOT equal in constant time, returning a Choice(0u8) for equality and Choice(1u8) for inequality.

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

### Description
Determine if two items are NOT equal. The function executes in constant time.

### Returns
- **Choice(0u8)** if self == other
- **Choice(1u8)** if self != other
```

--------------------------------

### fn conditional_select

Source: https://docs.rs/subtle/latest/subtle/trait.ConditionallySelectable.html?search=std%3A%3Avec

Selects between two values based on a Choice in constant time.

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

### Description
Selects `a` or `b` according to `choice`. Returns `a` if `choice == Choice(0)` and `b` if `choice == Choice(1)`. This operation executes in constant time.

### Parameters
- **a** (&Self) - The first value to select from.
- **b** (&Self) - The second value to select from.
- **choice** (Choice) - The selection condition.
```

--------------------------------

### ConstantTimeEq Trait Definition

Source: https://docs.rs/subtle/latest/subtle/trait.ConstantTimeEq.html

The trait definition showing the required ct_eq method and the provided ct_ne method.

```rust
pub trait ConstantTimeEq {
    // Required method
    fn ct_eq(&self, other: &Self) -> Choice;

    // Provided method
    fn ct_ne(&self, other: &Self) -> Choice { ... }
}
```

--------------------------------

### Use conditional_swap for constant-time swapping

Source: https://docs.rs/subtle/latest/subtle/trait.ConditionallySelectable.html

Swaps two values if the choice is 1, otherwise leaves them unchanged.

```rust
use subtle::ConditionallySelectable;
let mut x: u8 = 13;
let mut y: u8 = 42;

u8::conditional_swap(&mut x, &mut y, 0.into());
assert_eq!(x, 13);
assert_eq!(y, 42);
u8::conditional_swap(&mut x, &mut y, 1.into());
assert_eq!(x, 42);
assert_eq!(y, 13);
```

--------------------------------

### conditional_select

Source: https://docs.rs/subtle/latest/subtle/trait.ConditionallySelectable.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Selects between two values based on a Choice. Returns 'a' if choice is 0, and 'b' if choice is 1.

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

### Description
Selects between two values in constant time based on the provided Choice.

### Parameters
- **a** (&Self) - The value to return if choice is 0.
- **b** (&Self) - The value to return if choice is 1.
- **choice** (Choice) - The selection criteria.

### Returns
- **Self** - The selected value.
```

--------------------------------

### ConditionallyNegatable Generic Implementation

Source: https://docs.rs/subtle/latest/subtle/trait.ConditionallyNegatable.html?search=std%3A%3Avec

The blanket implementation for types that satisfy the ConditionallySelectable and Neg trait bounds.

```rust
impl<T> ConditionallyNegatable for T
where T: ConditionallySelectable, for<'a> &'a T: Neg<Output = T>,
```

--------------------------------

### fn conditional_assign

Source: https://docs.rs/subtle/latest/subtle/trait.ConditionallySelectable.html?search=std%3A%3Avec

Conditionally assigns another value to self in constant time.

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

### Description
Conditionally assigns `other` to `self` based on the provided `choice`. This operation executes in constant time.

### Parameters
- **other** (&Self) - The value to assign.
- **choice** (Choice) - The condition determining if the assignment occurs.
```

--------------------------------

### conditional_negate

Source: https://docs.rs/subtle/latest/subtle/trait.ConditionallyNegatable.html?search=u32+-%3E+bool

Negates the value if the provided choice is 1, otherwise leaves it unchanged. This operation is designed to execute in constant time.

```APIDOC
## fn conditional_negate(&mut self, choice: Choice)

### Description
Negate `self` if `choice == Choice(1)`; otherwise, leave it unchanged. This function is designed to execute in constant time to prevent side-channel attacks.

### Parameters
- **choice** (Choice) - The condition determining whether to negate the value.
```

--------------------------------

### Use conditional_assign for constant-time assignment

Source: https://docs.rs/subtle/latest/subtle/trait.ConditionallySelectable.html

Conditionally updates the value of self based on the provided Choice.

```rust
use subtle::ConditionallySelectable;
let mut x: u8 = 13;
let mut y: u8 = 42;

x.conditional_assign(&y, 0.into());
assert_eq!(x, 13);
x.conditional_assign(&y, 1.into());
assert_eq!(x, 42);
```

--------------------------------

### ConstantTimeLess Trait Definition

Source: https://docs.rs/subtle/latest/subtle/trait.ConstantTimeLess.html

The trait definition showing the required supertraits and the provided ct_lt method.

```rust
pub trait ConstantTimeLess: ConstantTimeEq + ConstantTimeGreater {
    // Provided method
    fn ct_lt(&self, other: &Self) -> Choice { ... }
}
```

--------------------------------

### ConditionallyNegatable Trait Definition

Source: https://docs.rs/subtle/latest/subtle/trait.ConditionallyNegatable.html

The core trait definition requiring the conditional_negate method.

```rust
pub trait ConditionallyNegatable {
    // Required method
    fn conditional_negate(&mut self, choice: Choice);
}
```

--------------------------------

### Define BlackBox struct

Source: https://docs.rs/subtle/latest/subtle/struct.BlackBox.html?search=

The definition of the BlackBox wrapper type, which requires the inner type T to implement Copy.

```rust
pub struct BlackBox<T: Copy>(/* private fields */);
```

--------------------------------

### conditional_assign

Source: https://docs.rs/subtle/latest/subtle/trait.ConditionallySelectable.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Conditionally assigns the value of 'other' to 'self' based on the provided Choice in constant time.

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

### Description
Conditionally assigns 'other' to 'self' if the choice is 1, otherwise leaves 'self' unchanged.

### Parameters
- **self** (&mut Self) - The target to be assigned to.
- **other** (&Self) - The source value.
- **choice** (Choice) - The condition for assignment.
```

--------------------------------

### Define the ConditionallySelectable trait

Source: https://docs.rs/subtle/latest/subtle/trait.ConditionallySelectable.html

The trait definition requiring a constant-time conditional_select method, with provided methods for assignment and swapping.

```rust
pub trait ConditionallySelectable: Copy {
    // Required method
    fn conditional_select(a: &Self, b: &Self, choice: Choice) -> Self;

    // Provided methods
    fn conditional_assign(&mut self, other: &Self, choice: Choice) { ... }
    fn conditional_swap(a: &mut Self, b: &mut Self, choice: Choice) { ... }
}
```

--------------------------------

### ConstantTimeGreater Trait Definition

Source: https://docs.rs/subtle/latest/subtle/trait.ConstantTimeGreater.html

The core trait definition requiring the implementation of the ct_gt method.

```rust
pub trait ConstantTimeGreater {
    // Required method
    fn ct_gt(&self, other: &Self) -> Choice;
}
```
Tokens:
Raw