diff --git a/CHANGELOG.md b/CHANGELOG.md index 756ecfd..66b1ed1 100644 --- a/CHANGELOG.md +++ b/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`. diff --git a/Cargo.toml b/Cargo.toml index 41976ff..e86eb01 100644 --- a/Cargo.toml +++ b/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 ", "DebugSteven ", @@ -28,13 +30,16 @@ travis-ci = { repository = "dalek-cryptography/x25519-dalek", branch = "master"} features = ["nightly"] [dependencies] -curve25519-dalek = { version = "1", default-features = false } -rand_core = { version = "0.3", default-features = false } -clear_on_drop = { version = "0.2" } +curve25519-dalek = { version = "2", default-features = false } +rand_core = { version = "0.5", default-features = false } +# `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"] diff --git a/README.md b/README.md index e1c37df..be90d5a 100644 --- a/README.md +++ b/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 diff --git a/benches/x25519.rs b/benches/x25519.rs index cfded70..e5d77d2 100644 --- a/benches/x25519.rs +++ b/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 csprng); + let bob_secret = EphemeralSecret::new(&mut OsRng); 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, } diff --git a/src/lib.rs b/src/lib.rs index 8c1916f..0f80f7e 100644 --- a/src/lib.rs +++ b/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 rand_os; +extern crate zeroize; mod x25519; -pub use x25519::*; +pub use crate::x25519::*; diff --git a/src/x25519.rs b/src/x25519.rs index 30f5bdb..e95d0e3 100644 --- a/src/x25519.rs +++ b/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); - -/// Overwrite ephemeral secret key material with null bytes when it goes out of scope. -impl Drop for EphemeralSecret { - fn drop(&mut self) { - self.0.clear(); - } -} +#[derive(Zeroize)] +#[zeroize(drop)] +pub struct EphemeralSecret(pub(crate) Scalar); 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(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)] -pub struct StaticSecret(pub (crate) Scalar); - -/// Overwrite static secret key material with null bytes when it goes out of scope. -impl Drop for StaticSecret { - fn drop(&mut self) { - self.0.clear(); - } -} +#[cfg_attr(feature = "serde", serde(crate = "our_serde"))] +#[cfg_attr( + feature = "serde", + derive(our_serde::Serialize, our_serde::Deserialize) +)] +#[derive(Clone, Zeroize)] +#[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(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); - -/// Overwrite shared secret material with null bytes when it goes out of scope. -impl Drop for SharedSecret { - fn drop(&mut self) { - self.0.clear(); - } -} +#[derive(Zeroize)] +#[zeroize(drop)] +pub struct SharedSecret(pub(crate) MontgomeryPoint); 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 { - let mut s: [u8; 32] = scalar.clone(); +fn clamp_scalar(mut scalar: [u8; 32]) -> Scalar { + scalar[0] &= 248; + scalar[31] &= 127; + scalar[31] |= 64; - s[0] &= 248; - s[31] &= 127; - s[31] |= 64; - - Scalar::from_bits(s) + Scalar::from_bits(scalar) } /// 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 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 csprng); + let alice_secret = EphemeralSecret::new(&mut OsRng); 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, - 0x3b, 0x16, 0x15, 0x4b, 0x82, 0x46, 0x5e, 0xdd, - 0x62, 0x14, 0x4c, 0x0a, 0xc1, 0xfc, 0x5a, 0x18, - 0x50, 0x6a, 0x22, 0x44, 0xba, 0x44, 0x9a, 0xc4, ]; + 0xa5, 0x46, 0xe3, 0x6b, 0xf0, 0x52, 0x7c, 0x9d, 0x3b, 0x16, 0x15, 0x4b, 0x82, 0x46, + 0x5e, 0xdd, 0x62, 0x14, 0x4c, 0x0a, 0xc1, 0xfc, 0x5a, 0x18, 0x50, 0x6a, 0x22, 0x44, + 0xba, 0x44, 0x9a, 0xc4, + ]; let input_point: [u8; 32] = [ - 0xe6, 0xdb, 0x68, 0x67, 0x58, 0x30, 0x30, 0xdb, - 0x35, 0x94, 0xc1, 0xa4, 0x24, 0xb1, 0x5f, 0x7c, - 0x72, 0x66, 0x24, 0xec, 0x26, 0xb3, 0x35, 0x3b, - 0x10, 0xa9, 0x03, 0xa6, 0xd0, 0xab, 0x1c, 0x4c, ]; + 0xe6, 0xdb, 0x68, 0x67, 0x58, 0x30, 0x30, 0xdb, 0x35, 0x94, 0xc1, 0xa4, 0x24, 0xb1, + 0x5f, 0x7c, 0x72, 0x66, 0x24, 0xec, 0x26, 0xb3, 0x35, 0x3b, 0x10, 0xa9, 0x03, 0xa6, + 0xd0, 0xab, 0x1c, 0x4c, + ]; let expected: [u8; 32] = [ - 0xc3, 0xda, 0x55, 0x37, 0x9d, 0xe9, 0xc6, 0x90, - 0x8e, 0x94, 0xea, 0x4d, 0xf2, 0x8d, 0x08, 0x4f, - 0x32, 0xec, 0xcf, 0x03, 0x49, 0x1c, 0x71, 0xf7, - 0x54, 0xb4, 0x07, 0x55, 0x77, 0xa2, 0x85, 0x52, ]; + 0xc3, 0xda, 0x55, 0x37, 0x9d, 0xe9, 0xc6, 0x90, 0x8e, 0x94, 0xea, 0x4d, 0xf2, 0x8d, + 0x08, 0x4f, 0x32, 0xec, 0xcf, 0x03, 0x49, 0x1c, 0x71, 0xf7, 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, - 0x5a, 0xd2, 0x26, 0x91, 0x95, 0x7d, 0x6a, 0xf5, - 0xc1, 0x1b, 0x64, 0x21, 0xe0, 0xea, 0x01, 0xd4, - 0x2c, 0xa4, 0x16, 0x9e, 0x79, 0x18, 0xba, 0x0d, ]; + 0x4b, 0x66, 0xe9, 0xd4, 0xd1, 0xb4, 0x67, 0x3c, 0x5a, 0xd2, 0x26, 0x91, 0x95, 0x7d, + 0x6a, 0xf5, 0xc1, 0x1b, 0x64, 0x21, 0xe0, 0xea, 0x01, 0xd4, 0x2c, 0xa4, 0x16, 0x9e, + 0x79, 0x18, 0xba, 0x0d, + ]; let input_point: [u8; 32] = [ - 0xe5, 0x21, 0x0f, 0x12, 0x78, 0x68, 0x11, 0xd3, - 0xf4, 0xb7, 0x95, 0x9d, 0x05, 0x38, 0xae, 0x2c, - 0x31, 0xdb, 0xe7, 0x10, 0x6f, 0xc0, 0x3c, 0x3e, - 0xfc, 0x4c, 0xd5, 0x49, 0xc7, 0x15, 0xa4, 0x93, ]; + 0xe5, 0x21, 0x0f, 0x12, 0x78, 0x68, 0x11, 0xd3, 0xf4, 0xb7, 0x95, 0x9d, 0x05, 0x38, + 0xae, 0x2c, 0x31, 0xdb, 0xe7, 0x10, 0x6f, 0xc0, 0x3c, 0x3e, 0xfc, 0x4c, 0xd5, 0x49, + 0xc7, 0x15, 0xa4, 0x93, + ]; let expected: [u8; 32] = [ - 0x95, 0xcb, 0xde, 0x94, 0x76, 0xe8, 0x90, 0x7d, - 0x7a, 0xad, 0xe4, 0x5c, 0xb4, 0xb8, 0x73, 0xf8, - 0x8b, 0x59, 0x5a, 0x68, 0x79, 0x9f, 0xa1, 0x52, - 0xe6, 0xf8, 0xf7, 0x64, 0x7a, 0xac, 0x79, 0x57, ]; + 0x95, 0xcb, 0xde, 0x94, 0x76, 0xe8, 0x90, 0x7d, 0x7a, 0xad, 0xe4, 0x5c, 0xb4, 0xb8, + 0x73, 0xf8, 0x8b, 0x59, 0x5a, 0x68, 0x79, 0x9f, 0xa1, 0x52, 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, - 0xa1, 0x35, 0x0b, 0x3e, 0x2b, 0xb7, 0x27, 0x9f, - 0x78, 0x97, 0xb8, 0x7b, 0xb6, 0x85, 0x4b, 0x78, - 0x3c, 0x60, 0xe8, 0x03, 0x11, 0xae, 0x30, 0x79, ]); + assert_eq!( + k, + [ + 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, - 0x28, 0x00, 0xef, 0x56, 0x6f, 0x2f, 0x4d, 0x3c, - 0x1c, 0x38, 0x87, 0xc4, 0x93, 0x60, 0xe3, 0x87, - 0x5f, 0x2e, 0xb9, 0x4d, 0x99, 0x53, 0x2c, 0x51, ]); + assert_eq!( + k, + [ + 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, - 0x86, 0x44, 0x97, 0x29, 0x7e, 0x57, 0x5e, 0x6f, - 0x3b, 0xc6, 0x01, 0xc0, 0x88, 0x3c, 0x30, 0xdf, - 0x5f, 0x4d, 0xd2, 0xd2, 0x4f, 0x66, 0x54, 0x24, ]); + assert_eq!( + k, + [ + 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, + ] + ); } }