Merge branch 'release/0.6'

CHANGELOG.md

@@ -2,6 +2,13 @@
 
 Entries are listed in reverse chronological order.
 
+## 0.6.0
+
+* Updates `rand_core` version to `0.5`.
+* Adds `serde` support.
+* Replaces `clear_on_drop` with `zeroize`.
+* Use Rust 2018.
+
 ## 0.5.2
 
 * Implement `Clone` for `StaticSecret`.

Cargo.toml

@@ -1,6 +1,8 @@
 [package]
 name = "x25519-dalek"
-version = "0.5.2"
+edition = "2018"
+# Be sure to update the version in README.md
+version = "0.6.0"
 authors = [
     "Isis Lovecruft <isis@patternsinthevoid.net>", 
     "DebugSteven <debugsteven@gmail.com>",
@@ -28,13 +30,16 @@ travis-ci = { repository = "dalek-cryptography/x25519-dalek", branch = "master"}
 features = ["nightly"]
 
 [dependencies]
-curve25519-dalek = { version = "1", default-features = false }
+curve25519-dalek = { version = "2", default-features = false }
-rand_core = { version = "0.3", default-features = false }
+rand_core = { version = "0.5", default-features = false }
-clear_on_drop = { version = "0.2" }
+# `serde` is renamed to `our_serde` in order to avoid a name collision between
+# importing the serde dependency and enabling the curve25519-dalek/serde feature
+our_serde = { package = "serde", version = "1", default-features = false, optional = true, features = ["derive"] }
+zeroize = { version = "1", default-features = false, features = ["zeroize_derive"] }
 
 [dev-dependencies]
+bincode = "1"
 criterion = "0.2"
-rand_os = "0.1"
 
 [[bench]]
 name = "x25519"
@@ -42,7 +47,8 @@ harness = false
 
 [features]
 default = ["std", "u64_backend"]
+serde = ["our_serde", "curve25519-dalek/serde"]
 std = ["curve25519-dalek/std"]
-nightly = ["curve25519-dalek/nightly", "clear_on_drop/nightly"]
+nightly = ["curve25519-dalek/nightly"]
 u64_backend = ["curve25519-dalek/u64_backend"]
 u32_backend = ["curve25519-dalek/u32_backend"]

README.md

@@ -87,7 +87,7 @@ To install, add the following to your project's `Cargo.toml`:
 
 ```toml
 [dependencies.x25519-dalek]
-version = "^0.5"
+version = "0.6"
 ```
 
 # Documentation

benches/x25519.rs

@@ -14,37 +14,34 @@
 #[macro_use]
 extern crate criterion;
 extern crate curve25519_dalek;
-extern crate rand_os;
+extern crate rand_core;
 extern crate x25519_dalek;
 
 use criterion::Criterion;
 
-use curve25519_dalek::montgomery::MontgomeryPoint;
+use rand_core::OsRng;
 
-use rand_os::OsRng;
-
-use x25519_dalek::PublicKey;
 use x25519_dalek::EphemeralSecret;
+use x25519_dalek::PublicKey;
 
 fn bench_diffie_hellman(c: &mut Criterion) {
-    let mut csprng: OsRng = OsRng::new().unwrap();
+    let bob_secret = EphemeralSecret::new(&mut OsRng);
-    let bob_secret = EphemeralSecret::new(&mut csprng);
     let bob_public = PublicKey::from(&bob_secret);
 
     c.bench_function("diffie_hellman", move |b| {
         b.iter_with_setup(
-            || EphemeralSecret::new(&mut csprng),
+            || EphemeralSecret::new(&mut OsRng),
             |alice_secret| alice_secret.diffie_hellman(&bob_public),
         )
     });
 }
 
-criterion_group!{
+criterion_group! {
     name = x25519_benches;
     config = Criterion::default();
     targets =
         bench_diffie_hellman,
 }
-criterion_main!{
+criterion_main! {
     x25519_benches,
 }

src/lib.rs

@@ -24,15 +24,12 @@
 //! Note that docs will only build on nightly Rust until
 //! `feature(external_doc)` is stabilized.
 
-extern crate clear_on_drop;
-
 extern crate curve25519_dalek;
 
 extern crate rand_core;
 
-#[cfg(test)]
+extern crate zeroize;
-extern crate rand_os;
 
 mod x25519;
 
-pub use x25519::*;
+pub use crate::x25519::*;

src/x25519.rs

@@ -14,19 +14,24 @@
 //! This implements x25519 key exchange as specified by Mike Hamburg
 //! and Adam Langley in [RFC7748](https://tools.ietf.org/html/rfc7748).
 
-use clear_on_drop::clear::Clear;
-
 use curve25519_dalek::constants::ED25519_BASEPOINT_TABLE;
 use curve25519_dalek::montgomery::MontgomeryPoint;
 use curve25519_dalek::scalar::Scalar;
 
-use rand_core::RngCore;
 use rand_core::CryptoRng;
+use rand_core::RngCore;
+
+use zeroize::Zeroize;
 
 /// A `PublicKey` is the corresponding public key converted from
 /// an `EphemeralSecret` or a `StaticSecret` key.
+#[cfg_attr(feature = "serde", serde(crate = "our_serde"))]
+#[cfg_attr(
+    feature = "serde",
+    derive(our_serde::Serialize, our_serde::Deserialize)
+)]
 #[derive(Copy, Clone, Debug)]
-pub struct PublicKey(pub (crate) MontgomeryPoint);
+pub struct PublicKey(pub(crate) MontgomeryPoint);
 
 impl From<[u8; 32]> for PublicKey {
     /// Given a byte array, construct a x25519 `PublicKey`.
@@ -45,14 +50,9 @@ impl PublicKey {
 
 /// A `EphemeralSecret` is a short lived Diffie-Hellman secret key
 /// used to create a `SharedSecret` when given their `PublicKey`.
-pub struct EphemeralSecret(pub (crate) Scalar);
+#[derive(Zeroize)]
-
+#[zeroize(drop)]
-/// Overwrite ephemeral secret key material with null bytes when it goes out of scope.
+pub struct EphemeralSecret(pub(crate) Scalar);
-impl Drop for EphemeralSecret {
-    fn drop(&mut self) {
-        self.0.clear();
-    }
-}
 
 impl EphemeralSecret {
     /// Perform a Diffie-Hellman key agreement between `self` and
@@ -63,7 +63,8 @@ impl EphemeralSecret {
 
     /// Generate an x25519 `EphemeralSecret` key.
     pub fn new<T>(csprng: &mut T) -> Self
-        where T: RngCore + CryptoRng
+    where
+        T: RngCore + CryptoRng,
     {
         let mut bytes = [0u8; 32];
 
@@ -71,7 +72,6 @@ impl EphemeralSecret {
 
         EphemeralSecret(clamp_scalar(bytes))
     }
-
 }
 
 impl<'a> From<&'a EphemeralSecret> for PublicKey {
@@ -80,21 +80,21 @@ impl<'a> From<&'a EphemeralSecret> for PublicKey {
     fn from(secret: &'a EphemeralSecret) -> PublicKey {
         PublicKey((&ED25519_BASEPOINT_TABLE * &secret.0).to_montgomery())
     }
-
 }
 
 /// A `StaticSecret` is a static Diffie-Hellman secret key that
 /// can be saved and loaded to create a `SharedSecret` when given
 /// their `PublicKey`.
-#[derive(Clone)]
+#[cfg_attr(feature = "serde", serde(crate = "our_serde"))]
-pub struct StaticSecret(pub (crate) Scalar);
+#[cfg_attr(
-
+    feature = "serde",
-/// Overwrite static secret key material with null bytes when it goes out of scope.
+    derive(our_serde::Serialize, our_serde::Deserialize)
-impl Drop for StaticSecret {
+)]
-    fn drop(&mut self) {
+#[derive(Clone, Zeroize)]
-        self.0.clear();
+#[zeroize(drop)]
-    }
+pub struct StaticSecret(
-}
+    #[cfg_attr(feature = "serde", serde(with = "AllowUnreducedScalarBytes"))] pub(crate) Scalar,
+);
 
 impl StaticSecret {
     /// Perform a Diffie-Hellman key agreement between `self` and
@@ -105,7 +105,8 @@ impl StaticSecret {
 
     /// Generate a x25519 `StaticSecret` key.
     pub fn new<T>(csprng: &mut T) -> Self
-        where T: RngCore + CryptoRng
+    where
+        T: RngCore + CryptoRng,
     {
         let mut bytes = [0u8; 32];
 
@@ -118,7 +119,6 @@ impl StaticSecret {
     pub fn to_bytes(&self) -> [u8; 32] {
         self.0.to_bytes()
     }
-
 }
 
 impl From<[u8; 32]> for StaticSecret {
@@ -134,19 +134,13 @@ impl<'a> From<&'a StaticSecret> for PublicKey {
     fn from(secret: &'a StaticSecret) -> PublicKey {
         PublicKey((&ED25519_BASEPOINT_TABLE * &secret.0).to_montgomery())
     }
-
 }
 
 /// A `SharedSecret` is a Diffie-Hellman shared secret that’s generated
 /// from your `EphemeralSecret` or `StaticSecret` and their `PublicKey`.
-pub struct SharedSecret(pub (crate) MontgomeryPoint);
+#[derive(Zeroize)]
-
+#[zeroize(drop)]
-/// Overwrite shared secret material with null bytes when it goes out of scope.
+pub struct SharedSecret(pub(crate) MontgomeryPoint);
-impl Drop for SharedSecret {
-    fn drop(&mut self) {
-        self.0.clear();
-    }
-}
 
 impl SharedSecret {
     /// View this shared secret key as a byte array.
@@ -164,14 +158,12 @@ impl SharedSecret {
 /// # Returns
 ///
 /// A `Scalar`.
-fn clamp_scalar(scalar: [u8; 32]) -> Scalar {
+fn clamp_scalar(mut scalar: [u8; 32]) -> Scalar {
-    let mut s: [u8; 32] = scalar.clone();
+    scalar[0] &= 248;
+    scalar[31] &= 127;
+    scalar[31] |= 64;
 
-    s[0]  &= 248;
+    Scalar::from_bits(scalar)
-    s[31] &= 127;
-    s[31] |= 64;
-
-    Scalar::from_bits(s)
 }
 
 /// The bare, byte-oriented x25519 function, exactly as specified in RFC7748.
@@ -189,21 +181,38 @@ pub const X25519_BASEPOINT_BYTES: [u8; 32] = [
     9, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
 ];
 
+/// Derived serialization methods will not work on a StaticSecret because x25519 requires
+/// non-canonical scalars which are rejected by curve25519-dalek. Thus we provide a way to convert
+/// the bytes directly to a scalar using Serde's remote derive functionality.
+#[cfg_attr(feature = "serde", serde(crate = "our_serde"))]
+#[cfg_attr(
+    feature = "serde",
+    derive(our_serde::Serialize, our_serde::Deserialize)
+)]
+#[cfg_attr(feature = "serde", serde(remote = "Scalar"))]
+struct AllowUnreducedScalarBytes(
+    #[cfg_attr(feature = "serde", serde(getter = "Scalar::to_bytes"))] [u8; 32],
+);
+impl From<AllowUnreducedScalarBytes> for Scalar {
+    fn from(bytes: AllowUnreducedScalarBytes) -> Scalar {
+        clamp_scalar(bytes.0)
+    }
+}
+
 #[cfg(test)]
 mod test {
     use super::*;
 
-    use rand_os::OsRng;
+    use rand_core::OsRng;
 
     // This was previously a doctest but it got moved to the README to
     // avoid duplication where it then wasn't being run, so now it
     // lives here.
     #[test]
     fn alice_and_bob() {
-        let mut csprng = OsRng::new().unwrap();
+        let alice_secret = EphemeralSecret::new(&mut OsRng);
-        let alice_secret = EphemeralSecret::new(&mut csprng);
         let alice_public = PublicKey::from(&alice_secret);
-        let bob_secret = EphemeralSecret::new(&mut csprng);
+        let bob_secret = EphemeralSecret::new(&mut OsRng);
         let bob_public = PublicKey::from(&bob_secret);
         let alice_shared_secret = alice_secret.diffie_hellman(&bob_public);
         let bob_shared_secret = bob_secret.diffie_hellman(&alice_public);
@@ -228,6 +237,57 @@ mod test {
         }
     }
 
+    #[test]
+    #[cfg(feature = "serde")]
+    fn serde_bincode_public_key_roundtrip() {
+        use bincode;
+
+        let public_key = PublicKey::from(X25519_BASEPOINT_BYTES);
+
+        let encoded = bincode::serialize(&public_key).unwrap();
+        let decoded: PublicKey = bincode::deserialize(&encoded).unwrap();
+
+        assert_eq!(encoded.len(), 32);
+        assert_eq!(decoded.as_bytes(), public_key.as_bytes());
+    }
+
+    #[test]
+    #[cfg(feature = "serde")]
+    fn serde_bincode_public_key_matches_from_bytes() {
+        use bincode;
+
+        let expected = PublicKey::from(X25519_BASEPOINT_BYTES);
+        let decoded: PublicKey = bincode::deserialize(&X25519_BASEPOINT_BYTES).unwrap();
+
+        assert_eq!(decoded.as_bytes(), expected.as_bytes());
+    }
+
+    #[test]
+    #[cfg(feature = "serde")]
+    fn serde_bincode_static_secret_roundtrip() {
+        use bincode;
+
+        let static_secret = StaticSecret(clamp_scalar([0x24; 32]));
+
+        let encoded = bincode::serialize(&static_secret).unwrap();
+        let decoded: StaticSecret = bincode::deserialize(&encoded).unwrap();
+
+        assert_eq!(encoded.len(), 32);
+        assert_eq!(decoded.to_bytes(), static_secret.to_bytes());
+    }
+
+    #[test]
+    #[cfg(feature = "serde")]
+    fn serde_bincode_static_secret_matches_from_bytes() {
+        use bincode;
+
+        let expected = StaticSecret(clamp_scalar([0x24; 32]));
+        let clamped_bytes = clamp_scalar([0x24; 32]).to_bytes();
+        let decoded: StaticSecret = bincode::deserialize(&clamped_bytes).unwrap();
+
+        assert_eq!(decoded.to_bytes(), expected.to_bytes());
+    }
+
     fn do_rfc7748_ladder_test1(input_scalar: [u8; 32], input_point: [u8; 32], expected: [u8; 32]) {
         let result = x25519(input_scalar, input_point);
 
@@ -237,20 +297,20 @@ mod test {
     #[test]
     fn rfc7748_ladder_test1_vectorset1() {
         let input_scalar: [u8; 32] = [
-            0xa5, 0x46, 0xe3, 0x6b, 0xf0, 0x52, 0x7c, 0x9d,
+            0xa5, 0x46, 0xe3, 0x6b, 0xf0, 0x52, 0x7c, 0x9d, 0x3b, 0x16, 0x15, 0x4b, 0x82, 0x46,
-            0x3b, 0x16, 0x15, 0x4b, 0x82, 0x46, 0x5e, 0xdd,
+            0x5e, 0xdd, 0x62, 0x14, 0x4c, 0x0a, 0xc1, 0xfc, 0x5a, 0x18, 0x50, 0x6a, 0x22, 0x44,
-            0x62, 0x14, 0x4c, 0x0a, 0xc1, 0xfc, 0x5a, 0x18,
+            0xba, 0x44, 0x9a, 0xc4,
-            0x50, 0x6a, 0x22, 0x44, 0xba, 0x44, 0x9a, 0xc4, ];
+        ];
         let input_point: [u8; 32] = [
-            0xe6, 0xdb, 0x68, 0x67, 0x58, 0x30, 0x30, 0xdb,
+            0xe6, 0xdb, 0x68, 0x67, 0x58, 0x30, 0x30, 0xdb, 0x35, 0x94, 0xc1, 0xa4, 0x24, 0xb1,
-            0x35, 0x94, 0xc1, 0xa4, 0x24, 0xb1, 0x5f, 0x7c,
+            0x5f, 0x7c, 0x72, 0x66, 0x24, 0xec, 0x26, 0xb3, 0x35, 0x3b, 0x10, 0xa9, 0x03, 0xa6,
-            0x72, 0x66, 0x24, 0xec, 0x26, 0xb3, 0x35, 0x3b,
+            0xd0, 0xab, 0x1c, 0x4c,
-            0x10, 0xa9, 0x03, 0xa6, 0xd0, 0xab, 0x1c, 0x4c, ];
+        ];
         let expected: [u8; 32] = [
-            0xc3, 0xda, 0x55, 0x37, 0x9d, 0xe9, 0xc6, 0x90,
+            0xc3, 0xda, 0x55, 0x37, 0x9d, 0xe9, 0xc6, 0x90, 0x8e, 0x94, 0xea, 0x4d, 0xf2, 0x8d,
-            0x8e, 0x94, 0xea, 0x4d, 0xf2, 0x8d, 0x08, 0x4f,
+            0x08, 0x4f, 0x32, 0xec, 0xcf, 0x03, 0x49, 0x1c, 0x71, 0xf7, 0x54, 0xb4, 0x07, 0x55,
-            0x32, 0xec, 0xcf, 0x03, 0x49, 0x1c, 0x71, 0xf7,
+            0x77, 0xa2, 0x85, 0x52,
-            0x54, 0xb4, 0x07, 0x55, 0x77, 0xa2, 0x85, 0x52, ];
+        ];
 
         do_rfc7748_ladder_test1(input_scalar, input_point, expected);
     }
@@ -258,20 +318,20 @@ mod test {
     #[test]
     fn rfc7748_ladder_test1_vectorset2() {
         let input_scalar: [u8; 32] = [
-            0x4b, 0x66, 0xe9, 0xd4, 0xd1, 0xb4, 0x67, 0x3c,
+            0x4b, 0x66, 0xe9, 0xd4, 0xd1, 0xb4, 0x67, 0x3c, 0x5a, 0xd2, 0x26, 0x91, 0x95, 0x7d,
-            0x5a, 0xd2, 0x26, 0x91, 0x95, 0x7d, 0x6a, 0xf5,
+            0x6a, 0xf5, 0xc1, 0x1b, 0x64, 0x21, 0xe0, 0xea, 0x01, 0xd4, 0x2c, 0xa4, 0x16, 0x9e,
-            0xc1, 0x1b, 0x64, 0x21, 0xe0, 0xea, 0x01, 0xd4,
+            0x79, 0x18, 0xba, 0x0d,
-            0x2c, 0xa4, 0x16, 0x9e, 0x79, 0x18, 0xba, 0x0d, ];
+        ];
         let input_point: [u8; 32] = [
-            0xe5, 0x21, 0x0f, 0x12, 0x78, 0x68, 0x11, 0xd3,
+            0xe5, 0x21, 0x0f, 0x12, 0x78, 0x68, 0x11, 0xd3, 0xf4, 0xb7, 0x95, 0x9d, 0x05, 0x38,
-            0xf4, 0xb7, 0x95, 0x9d, 0x05, 0x38, 0xae, 0x2c,
+            0xae, 0x2c, 0x31, 0xdb, 0xe7, 0x10, 0x6f, 0xc0, 0x3c, 0x3e, 0xfc, 0x4c, 0xd5, 0x49,
-            0x31, 0xdb, 0xe7, 0x10, 0x6f, 0xc0, 0x3c, 0x3e,
+            0xc7, 0x15, 0xa4, 0x93,
-            0xfc, 0x4c, 0xd5, 0x49, 0xc7, 0x15, 0xa4, 0x93, ];
+        ];
         let expected: [u8; 32] = [
-            0x95, 0xcb, 0xde, 0x94, 0x76, 0xe8, 0x90, 0x7d,
+            0x95, 0xcb, 0xde, 0x94, 0x76, 0xe8, 0x90, 0x7d, 0x7a, 0xad, 0xe4, 0x5c, 0xb4, 0xb8,
-            0x7a, 0xad, 0xe4, 0x5c, 0xb4, 0xb8, 0x73, 0xf8,
+            0x73, 0xf8, 0x8b, 0x59, 0x5a, 0x68, 0x79, 0x9f, 0xa1, 0x52, 0xe6, 0xf8, 0xf7, 0x64,
-            0x8b, 0x59, 0x5a, 0x68, 0x79, 0x9f, 0xa1, 0x52,
+            0x7a, 0xac, 0x79, 0x57,
-            0xe6, 0xf8, 0xf7, 0x64, 0x7a, 0xac, 0x79, 0x57, ];
+        ];
 
         do_rfc7748_ladder_test1(input_scalar, input_point, expected);
     }
@@ -286,7 +346,7 @@ mod test {
         let mut result: [u8; 32];
 
         macro_rules! do_iterations {
-            ($n:expr) => (
+            ($n:expr) => {
                 for _ in 0..$n {
                     result = x25519(k, u);
                     // OBVIOUS THING THAT I'M GOING TO NOTE ANYWAY BECAUSE I'VE
@@ -300,7 +360,7 @@ mod test {
                     u = k.clone();
                     k = result;
                 }
-            )
+            };
         }
 
         // After one iteration:
@@ -311,19 +371,31 @@ mod test {
         //     7c3911e0ab2586fd864497297e575e6f3bc601c0883c30df5f4dd2d24f665424
 
         do_iterations!(1);
-        assert_eq!(k, [ 0x42, 0x2c, 0x8e, 0x7a, 0x62, 0x27, 0xd7, 0xbc,
+        assert_eq!(
-                        0xa1, 0x35, 0x0b, 0x3e, 0x2b, 0xb7, 0x27, 0x9f,
+            k,
-                        0x78, 0x97, 0xb8, 0x7b, 0xb6, 0x85, 0x4b, 0x78,
+            [
-                        0x3c, 0x60, 0xe8, 0x03, 0x11, 0xae, 0x30, 0x79, ]);
+                0x42, 0x2c, 0x8e, 0x7a, 0x62, 0x27, 0xd7, 0xbc, 0xa1, 0x35, 0x0b, 0x3e, 0x2b, 0xb7,
+                0x27, 0x9f, 0x78, 0x97, 0xb8, 0x7b, 0xb6, 0x85, 0x4b, 0x78, 0x3c, 0x60, 0xe8, 0x03,
+                0x11, 0xae, 0x30, 0x79,
+            ]
+        );
         do_iterations!(999);
-        assert_eq!(k, [ 0x68, 0x4c, 0xf5, 0x9b, 0xa8, 0x33, 0x09, 0x55,
+        assert_eq!(
-                        0x28, 0x00, 0xef, 0x56, 0x6f, 0x2f, 0x4d, 0x3c,
+            k,
-                        0x1c, 0x38, 0x87, 0xc4, 0x93, 0x60, 0xe3, 0x87,
+            [
-                        0x5f, 0x2e, 0xb9, 0x4d, 0x99, 0x53, 0x2c, 0x51, ]);
+                0x68, 0x4c, 0xf5, 0x9b, 0xa8, 0x33, 0x09, 0x55, 0x28, 0x00, 0xef, 0x56, 0x6f, 0x2f,
+                0x4d, 0x3c, 0x1c, 0x38, 0x87, 0xc4, 0x93, 0x60, 0xe3, 0x87, 0x5f, 0x2e, 0xb9, 0x4d,
+                0x99, 0x53, 0x2c, 0x51,
+            ]
+        );
         do_iterations!(999_000);
-        assert_eq!(k, [ 0x7c, 0x39, 0x11, 0xe0, 0xab, 0x25, 0x86, 0xfd,
+        assert_eq!(
-                        0x86, 0x44, 0x97, 0x29, 0x7e, 0x57, 0x5e, 0x6f,
+            k,
-                        0x3b, 0xc6, 0x01, 0xc0, 0x88, 0x3c, 0x30, 0xdf,
+            [
-                        0x5f, 0x4d, 0xd2, 0xd2, 0x4f, 0x66, 0x54, 0x24, ]);
+                0x7c, 0x39, 0x11, 0xe0, 0xab, 0x25, 0x86, 0xfd, 0x86, 0x44, 0x97, 0x29, 0x7e, 0x57,
+                0x5e, 0x6f, 0x3b, 0xc6, 0x01, 0xc0, 0x88, 0x3c, 0x30, 0xdf, 0x5f, 0x4d, 0xd2, 0xd2,
+                0x4f, 0x66, 0x54, 0x24,
+            ]
+        );
     }
 }