diff options
Diffstat (limited to '')
| -rw-r--r-- | rust/vendor/subtle/README.md | 69 |
1 files changed, 69 insertions, 0 deletions
diff --git a/rust/vendor/subtle/README.md b/rust/vendor/subtle/README.md new file mode 100644 index 0000000..81ac448 --- /dev/null +++ b/rust/vendor/subtle/README.md @@ -0,0 +1,69 @@ +# 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 |