Merge branch 'release/2.3'

Author: hdevalence

.travis.yml

@@ -13,7 +13,7 @@ matrix:
       env: NAME="nightly feature"
       script: cargo test --features nightly
     # Test MSRV
-    - rust: 1.13.0
+    - rust: 1.41.0
       env: NAME="MSRV test"
       script: cargo test --no-default-features --features std
     # Test if crate can be truly built without std

CHANGELOG.md

@@ -2,6 +2,14 @@
 
 Entries are listed in reverse chronological order.
 
+## 2.3.0
+
+* Add `impl ConstantTimeEq for Choice` by @tarcieri.
+* Add `impl From<CtOption<T>> for Option<T>` by @CPerezz.  This is useful for
+  handling library code that produces `CtOption`s in contexts where timing
+  doesn't matter.
+* Introduce an MSRV policy.
+
 ## 2.2.3
 
 * Remove the `nightly`-only asm-based `black_box` barrier in favor of the

Cargo.toml

@@ -4,7 +4,7 @@ name = "subtle"
 # - update CHANGELOG
 # - update html_root_url
 # - update README if necessary by semver
-version = "2.2.3"
+version = "2.3.0"
 authors = ["Isis Lovecruft <isis@patternsinthevoid.net>",
            "Henry de Valence <hdevalence@hdevalence.ca>"]
 readme = "README.md"

README.md

@@ -7,7 +7,7 @@ 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"
+subtle = "2.3"
 ```
 
 This crate represents a “best-effort” attempt, since side-channels
@@ -38,6 +38,12 @@ used in release mode.
 
 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.

src/lib.rs

@@ -13,7 +13,7 @@
 #![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")]
+#![doc(html_root_url = "https://docs.rs/subtle/2.3.0")]
 
 //! Note that docs will only build on nightly Rust until
 //! [RFC 1990 stabilizes](https://github.com/rust-lang/rust/issues/44732).
@@ -23,22 +23,23 @@
 extern crate std;
 
 use core::ops::{BitAnd, BitAndAssign, BitOr, BitOrAssign, BitXor, BitXorAssign, Neg, Not};
+use core::option::Option;
 
 /// 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)]
@@ -136,11 +137,11 @@ 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.
-/// 
+///
 /// 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.
@@ -240,6 +241,13 @@ impl<T: ConstantTimeEq> ConstantTimeEq for [T] {
     }
 }
 
+impl ConstantTimeEq for Choice {
+    #[inline]
+    fn ct_eq(&self, rhs: &Choice) -> Choice {
+        !(*self ^ *rhs)
+    }
+}
+
 /// Given the bit-width `$bit_width` and the corresponding primitive
 /// unsigned and signed types `$t_u` and `$t_i` respectively, generate
 /// an `ConstantTimeEq` implementation.
@@ -499,6 +507,25 @@ pub struct CtOption<T> {
     is_some: Choice,
 }
 
+impl<T> From<CtOption<T>> for Option<T> {
+    /// Convert the `CtOption<T>` wrapper into an `Option<T>`, depending on whether
+    /// the underlying `is_some` `Choice` was a `0` or a `1` once unwrapped.
+    ///
+    /// # Note
+    ///
+    /// This function exists to avoid ending up with ugly, verbose and/or bad handled
+    /// conversions from the `CtOption<T>` wraps to an `Option<T>` or `Result<T, E>`.
+    /// This implementation doesn't intend to be constant-time nor try to protect the
+    /// leakage of the `T` since the `Option<T>` will do it anyways.
+    fn from(source: CtOption<T>) -> Option<T> {
+        if source.is_some().unwrap_u8() == 1u8 {
+            Option::Some(source.value)
+        } else {
+            None
+        }
+    }
+}
+
 impl<T> CtOption<T> {
     /// This method is used to construct a new `CtOption<T>` and takes
     /// a value of type `T`, and a `Choice` that determines whether
@@ -507,7 +534,10 @@ impl<T> CtOption<T> {
     /// exposed.
     #[inline]
     pub fn new(value: T, is_some: Choice) -> CtOption<T> {
-        CtOption { value: value, is_some: is_some }
+        CtOption {
+            value: value,
+            is_some: is_some,
+        }
     }
 
     /// This returns the underlying value but panics if it

tests/mod.rs

@@ -135,6 +135,14 @@ fn conditional_select_choice() {
     assert_eq!(bool::from(Choice::conditional_select(&f, &t, t)), true);
 }
 
+#[test]
+fn choice_equal() {
+    assert!(Choice::from(0).ct_eq(&Choice::from(0)).unwrap_u8() == 1);
+    assert!(Choice::from(0).ct_eq(&Choice::from(1)).unwrap_u8() == 0);
+    assert!(Choice::from(1).ct_eq(&Choice::from(0)).unwrap_u8() == 0);
+    assert!(Choice::from(1).ct_eq(&Choice::from(1)).unwrap_u8() == 1);
+}
+
 #[test]
 fn test_ctoption() {
     let a = CtOption::new(10, Choice::from(1));