Merge branch 'release/2.2.3'

Author: hdevalence

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 Entries are listed in reverse chronological order.
 
+## 2.2.3
+
+* Remove the `nightly`-only asm-based `black_box` barrier in favor of the
+  volatile-based one, fixing compilation on current nightlies.
+
 ## 2.2.2
 
 * Update README.md to clarify that 2.2 and above do not require the `nightly`

Cargo.toml

@@ -1,6 +1,10 @@
 [package]
 name = "subtle"
-version = "2.2.2"
+# Before incrementing:
+# - update CHANGELOG
+# - update html_root_url
+# - update README if necessary by semver
+version = "2.2.3"
 authors = ["Isis Lovecruft <isis@patternsinthevoid.net>",
            "Henry de Valence <hdevalence@hdevalence.ca>"]
 readme = "README.md"

README.md

@@ -6,27 +6,34 @@ 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.2"
+```
+
 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 operations are not optimized into a branch.
+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.
 
-To prevent the latter possibility, the crate attempts to hide the value of a
-`Choice`'s inner `u8` from the optimizer, by passing it through either an
-inline assembly block or a volatile read.  For more information, see the
-_About_ section below.
-
-```toml
-[dependencies.subtle]
-version = "2.2"
-```
+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].

src/lib.rs

@@ -9,11 +9,11 @@
 // - Henry de Valence <hdevalence@hdevalence.ca>
 
 #![no_std]
-#![cfg_attr(feature = "nightly", feature(asm))]
 #![cfg_attr(feature = "nightly", feature(external_doc))]
 #![cfg_attr(feature = "nightly", doc(include = "../README.md"))]
 #![cfg_attr(feature = "nightly", deny(missing_docs))]
 #![doc(html_logo_url = "https://doc.dalek.rs/assets/dalek-logo-clear.png")]
+#![doc(html_root_url = "https://docs.rs/subtle/2.2.3")]
 
 //! Note that docs will only build on nightly Rust until
 //! [RFC 1990 stabilizes](https://github.com/rust-lang/rust/issues/44732).
@@ -24,25 +24,23 @@ extern crate std;
 
 use core::ops::{BitAnd, BitAndAssign, BitOr, BitOrAssign, BitXor, BitXorAssign, Neg, Not};
 
-/// The `Choice` struct represents a choice for use in conditional
-/// assignment.
-///
-/// It is a wrapper around a `u8`, which should have the value either
-/// `1` (true) or `0` (false).
-///
-/// With the `nightly` feature enabled, the conversion from `u8` to
-/// `Choice` passes the value through an optimization barrier, as a
-/// best-effort attempt to prevent the compiler from inferring that the
-/// `Choice` value is a boolean.  This strategy is 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.
-///
-/// The `Choice` struct implements operators for AND, OR, XOR, and
-/// NOT, to allow combining `Choice` values.
-/// These operations do not short-circuit.
-///
-/// [rust-timing-shield]: https://www.chosenplaintext.ca/open-source/rust-timing-shield/security
+/// The `Choice` struct represents a choice for use in conditional assignment.
+/// 
+/// It is a wrapper around a `u8`, which should have the value either `1` (true)
+/// or `0` (false).
+/// 
+/// The conversion from `u8` to `Choice` passes the value through an optimization
+/// barrier, as a best-effort attempt to prevent the compiler from inferring that
+/// the `Choice` value is a boolean. This strategy is 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.
+/// 
+/// The `Choice` struct implements operators for AND, OR, XOR, and NOT, to allow
+/// combining `Choice` values. These operations do not short-circuit.
+/// 
+/// [rust-timing-shield]:
+/// https://www.chosenplaintext.ca/open-source/rust-timing-shield/security
 #[derive(Copy, Clone, Debug)]
 pub struct Choice(u8);
 
@@ -51,11 +49,11 @@ impl Choice {
     ///
     /// # Note
     ///
-    /// This function only exists as an escape hatch for the rare case
+    /// This function only exists as an **escape hatch** for the rare case
     /// where it's not possible to use one of the `subtle`-provided
     /// trait impls.
     ///
-    /// To convert a `Choice` to a `bool`, use the `From` implementation instead.
+    /// **To convert a `Choice` to a `bool`, use the `From` implementation instead.**
     #[inline]
     pub fn unwrap_u8(&self) -> u8 {
         self.0
@@ -136,30 +134,19 @@ impl Not for Choice {
     }
 }
 
-/// This function is a best-effort attempt to prevent the compiler
-/// from knowing anything about the value of the returned `u8`, other
-/// than its type.
-///
-/// Uses inline asm when available, otherwise it's a no-op.
-#[cfg(all(feature = "nightly", not(any(target_arch = "asmjs", target_arch = "wasm32"))))]
-#[inline(always)]
-fn black_box(mut input: u8) -> u8 {
-    debug_assert!((input == 0u8) | (input == 1u8));
-
-    // Move value through assembler, which is opaque to the compiler, even though we don't do anything.
-    unsafe { asm!("" : "=r"(input) : "0"(input) ) }
-
-    input
-}
-#[cfg(any(target_arch = "asmjs", target_arch = "wasm32", not(feature = "nightly")))]
+/// This function is a best-effort attempt to prevent the compiler from knowing
+/// anything about the value of the returned `u8`, other than its type.
+/// 
+/// Because we want to support stable Rust, we don't have access to inline
+/// assembly or test::black_box, so we use the fact that volatile values will
+/// never be elided to register values.
+/// 
+/// Note: Rust's notion of "volatile" is subject to change over time. While this
+/// code may break in a non-destructive way in the future, “constant-time” code
+/// is a continually moving target, and this is better than doing nothing.
 #[inline(never)]
 fn black_box(input: u8) -> u8 {
     debug_assert!((input == 0u8) | (input == 1u8));
-    // We don't have access to inline assembly or test::black_box, so we use the fact that
-    // volatile values will never be elided to register values.
-    //
-    // Note: Rust's notion of "volatile" is subject to change over time. While this code may break
-    // in a non-destructive way in the future, it is better than doing nothing.
 
     unsafe {
         // Optimization barrier