Expand description
§subtle 
Pure-Rust traits and utilities for constant-time cryptographic implementations.
It consists of a Choice type, and a collection of traits using Choice
instead of bool which are intended to execute in constant-time. The Choice
type is a wrapper around a u8 that holds a 0 or 1.
subtle = "2.5"This crate represents a “best-effort” attempt, since side-channels are ultimately a property of a deployed cryptographic system including the hardware it runs on, not just of software.
The traits are implemented using bitwise operations, and should execute in constant time provided that a) the bitwise operations are constant-time and b) the bitwise operations are not recognized as a conditional assignment and optimized back into a branch.
For a compiler to recognize that bitwise operations represent a conditional
assignment, it needs to know that the value used to generate the bitmasks is
really a boolean i1 rather than an i8 byte value. In an attempt to
prevent this refinement, the crate tries to hide the value of a Choice’s
inner u8 by passing it through a volatile read. For more information, see
the About section below.
Rust versions from 1.66 or higher support a new best-effort optimization
barrier (core::hint::black_box). To use the new optimization barrier,
enable the core_hint_black_box feature.
Rust versions from 1.51 or higher have const generics support. You may enable
const-generics feautre to have subtle traits implemented for arrays [T; N].
Versions prior to 2.2 recommended use of the nightly feature to enable an
optimization barrier; this is not required in versions 2.2 and above.
Note: the subtle crate contains debug_asserts to check invariants during
debug builds. These invariant checks involve secret-dependent branches, and
are not present when compiled in release mode. This crate is intended to be
used in release mode.
§Documentation
Documentation is available here.
§Minimum Supported Rust Version
Rust 1.41 or higher.
Minimum supported Rust version can be changed in the future, but it will be done with a minor version bump.
§About
This library aims to be the Rust equivalent of Go’s crypto/subtle module.
Old versions of the optimization barrier in impl From<u8> for Choice were
based on Tim Maclean’s work on rust-timing-shield,
which attempts to provide a more comprehensive approach for preventing
software side-channels in Rust code.
From version 2.2, it was based on Diane Hosfelt and Amber Sprenkels’ work on
“Secret Types in Rust”. Version 2.5 adds the core_hint_black_box feature,
which uses the original method through the core::hint::black_box function
from the Rust standard library.
subtle is authored by isis agora lovecruft and Henry de Valence.
§Warning
This code is a low-level library, intended for specific use-cases implementing cryptographic protocols. It represents a best-effort attempt to protect against some software side-channels. Because side-channel resistance is not a property of software alone, but of software together with hardware, any such effort is fundamentally limited.
USE AT YOUR OWN RISK
Structs§
- The
Choicestruct represents a choice for use in conditional assignment. - The
CtOption<T>type represents an optional value similar to theOption<T>type but is intended for use in constant time APIs.
Traits§
- A type which can be conditionally negated in constant time.
- A type which can be conditionally selected in constant time.
- An
Eq-like trait that produces aChoiceinstead of abool. - A type which can be compared in some manner and be determined to be greater than another of the same type.
- A type which can be compared in some manner and be determined to be less than another of the same type.