vendor/subtle/README.md

   1 # subtle [![](https://img.shields.io/crates/v/subtle.svg)](https://crates.io/crates/subtle) [![](https://img.shields.io/badge/dynamic/json.svg?label=docs&uri=https%3A%2F%2Fcrates.io%2Fapi%2Fv1%2Fcrates%2Fsubtle%2Fversions&query=%24.versions%5B0%5D.num&colorB=4F74A6)](https://doc.dalek.rs/subtle) [![](https://travis-ci.org/dalek-cryptography/subtle.svg?branch=master)](https://travis-ci.org/dalek-cryptography/subtle)
   2
   3 **Pure-Rust traits and utilities for constant-time cryptographic implementations.**
   4
   5 It consists of a `Choice` type, and a collection of traits using `Choice`
   6 instead of `bool` which are intended to execute in constant-time.  The `Choice`
   7 type is a wrapper around a `u8` that holds a `0` or `1`.
   8
   9 ```toml
  10 subtle = "2.4"
  11 ```
  12
  13 This crate represents a “best-effort” attempt, since side-channels
  14 are ultimately a property of a deployed cryptographic system
  15 including the hardware it runs on, not just of software.
  16
  17 The traits are implemented using bitwise operations, and should execute in
  18 constant time provided that a) the bitwise operations are constant-time and
  19 b) the bitwise operations are not recognized as a conditional assignment and
  20 optimized back into a branch.
  21
  22 For a compiler to recognize that bitwise operations represent a conditional
  23 assignment, it needs to know that the value used to generate the bitmasks is
  24 really a boolean `i1` rather than an `i8` byte value. In an attempt to
  25 prevent this refinement, the crate tries to hide the value of a `Choice`'s
  26 inner `u8` by passing it through a volatile read. For more information, see
  27 the _About_ section below.
  28
  29 Versions prior to `2.2` recommended use of the `nightly` feature to enable an
  30 optimization barrier; this is not required in versions `2.2` and above.
  31
  32 Note: the `subtle` crate contains `debug_assert`s to check invariants during
  33 debug builds. These invariant checks involve secret-dependent branches, and
  34 are not present when compiled in release mode. This crate is intended to be
  35 used in release mode.
  36
  37 ## Documentation
  38
  39 Documentation is available [here][docs].
  40
  41 ## Minimum Supported Rust Version
  42
  43 Rust **1.41** or higher.
  44
  45 Minimum supported Rust version can be changed in the future, but it will be done with a minor version bump.
  46
  47 ## About
  48
  49 This library aims to be the Rust equivalent of Go’s `crypto/subtle` module.
  50
  51 The optimization barrier in `impl From<u8> for Choice` was based on Tim
  52 Maclean's [work on `rust-timing-shield`][rust-timing-shield], which attempts to
  53 provide a more comprehensive approach for preventing software side-channels in
  54 Rust code.
  55
  56 `subtle` is authored by isis agora lovecruft and Henry de Valence.
  57
  58 ## Warning
  59
  60 This code is a low-level library, intended for specific use-cases implementing
  61 cryptographic protocols.  It represents a best-effort attempt to protect
  62 against some software side-channels.  Because side-channel resistance is not a
  63 property of software alone, but of software together with hardware, any such
  64 effort is fundamentally limited.
  65
  66 **USE AT YOUR OWN RISK**
  67
  68 [docs]: https://docs.rs/subtle
  69 [rust-timing-shield]: https://www.chosenplaintext.ca/open-source/rust-timing-shield/security