mirror of
https://github.com/zerotier/ZeroTierOne.git
synced 2025-02-12 05:55:19 +00:00
70 lines
3.1 KiB
Markdown
70 lines
3.1 KiB
Markdown
# subtle [](https://crates.io/crates/subtle) [](https://doc.dalek.rs/subtle) [](https://travis-ci.org/dalek-cryptography/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`.
|
||
|
||
```toml
|
||
subtle = "2.4"
|
||
```
|
||
|
||
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.
|
||
|
||
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_assert`s 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][docs].
|
||
|
||
## 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.
|
||
|
||
The optimization barrier in `impl From<u8> for Choice` was based on Tim
|
||
Maclean's [work on `rust-timing-shield`][rust-timing-shield], which attempts to
|
||
provide a more comprehensive approach for preventing software side-channels in
|
||
Rust code.
|
||
|
||
`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**
|
||
|
||
[docs]: https://docs.rs/subtle
|
||
[rust-timing-shield]: https://www.chosenplaintext.ca/open-source/rust-timing-shield/security
|