From 1d23a1d30d50dfc5f390b82eb118980a8f933473 Mon Sep 17 00:00:00 2001 From: Philippe Dugre Date: Fri, 25 Jan 2019 17:08:48 -0500 Subject: [PATCH 01/13] Added doc example for x25519() --- src/x25519.rs | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/src/x25519.rs b/src/x25519.rs index f3c6870..edd3adf 100644 --- a/src/x25519.rs +++ b/src/x25519.rs @@ -121,6 +121,37 @@ fn clamp_scalar(scalar: [u8; 32]) -> Scalar { /// /// This can be used with [`X25519_BASEPOINT_BYTES`] for people who /// cannot use the better, safer, and faster ephemeral DH API. +/// # Example +/// ``` +/// extern crate rand_os; +/// +/// use x25519_dalek::{ x25519, X25519_BASEPOINT_BYTES }; +/// use rand_os::OsRng; +/// use rand_os::rand_core::RngCore; +/// +/// let mut rng = OsRng::new().unwrap(); +/// +/// // Generate Alice key pair +/// let mut alice_private = [0u8; 32]; +/// rng.fill_bytes(&mut alice_private); +/// +/// let alice_public = x25519(alice_private.clone(), X25519_BASEPOINT_BYTES); +/// +/// // Generate bob key pair +/// let mut bob_private = [0u8; 32]; +/// rng.fill_bytes(&mut bob_private); +/// +/// let bob_public = x25519(bob_private.clone(), X25519_BASEPOINT_BYTES); +/// +/// // Exchange the public keys +/// // ... +/// // Generate shared secret +/// +/// let alice_shared = x25519(alice_private, bob_public); +/// let bob_shared = x25519(bob_private, alice_public); +/// +/// assert_eq!(alice_shared, bob_shared); +/// ``` pub fn x25519(k: [u8; 32], u: [u8; 32]) -> [u8; 32] { (clamp_scalar(k) * MontgomeryPoint(u)).to_bytes() } @@ -128,6 +159,7 @@ pub fn x25519(k: [u8; 32], u: [u8; 32]) -> [u8; 32] { /// The X25519 basepoint, for use with the bare, byte-oriented x25519 /// function. This is provided for people who cannot use the typed /// ephemeral DH API for some reason. +/// See [`x25519`] for example usage. 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, ]; From fc945778ab43428b9efdff61b8a963d01615c6ec Mon Sep 17 00:00:00 2001 From: Isis Lovecruft Date: Wed, 14 Apr 2021 05:05:54 +0000 Subject: [PATCH 02/13] Fixups for doctest from #33. --- src/x25519.rs | 39 ++++++++++++++++++--------------------- 1 file changed, 18 insertions(+), 21 deletions(-) diff --git a/src/x25519.rs b/src/x25519.rs index 064cb60..1c0c46f 100644 --- a/src/x25519.rs +++ b/src/x25519.rs @@ -193,34 +193,31 @@ fn clamp_scalar(mut scalar: [u8; 32]) -> Scalar { /// /// This can be used with [`X25519_BASEPOINT_BYTES`] for people who /// cannot use the better, safer, and faster ephemeral DH API. +/// /// # Example /// ``` -/// extern crate rand_os; +/// # extern crate rand_core; +/// # +/// use rand_core::OsRng; +/// use rand_core::RngCore; /// -/// use x25519_dalek::{ x25519, X25519_BASEPOINT_BYTES }; -/// use rand_os::OsRng; -/// use rand_os::rand_core::RngCore; +/// use x25519_dalek::x25519; +/// use x25519_dalek::StaticSecret; +/// use x25519_dalek::PublicKey; /// -/// let mut rng = OsRng::new().unwrap(); +/// // Generate Alice's key pair. +/// let alice_secret = StaticSecret::new(&mut OsRng); +/// let alice_public = PublicKey::from(&alice_secret); /// -/// // Generate Alice key pair -/// let mut alice_private = [0u8; 32]; -/// rng.fill_bytes(&mut alice_private); +/// // Generate Bob's key pair. +/// let bob_secret = StaticSecret::new(&mut OsRng); +/// let bob_public = PublicKey::from(&bob_secret); /// -/// let alice_public = x25519(alice_private.clone(), X25519_BASEPOINT_BYTES); +/// // Alice and Bob should now exchange their public keys. /// -/// // Generate bob key pair -/// let mut bob_private = [0u8; 32]; -/// rng.fill_bytes(&mut bob_private); -/// -/// let bob_public = x25519(bob_private.clone(), X25519_BASEPOINT_BYTES); -/// -/// // Exchange the public keys -/// // ... -/// // Generate shared secret -/// -/// let alice_shared = x25519(alice_private, bob_public); -/// let bob_shared = x25519(bob_private, alice_public); +/// // Once they've done so, they may generate a shared secret. +/// let alice_shared = x25519(alice_secret.to_bytes(), bob_public.to_bytes()); +/// let bob_shared = x25519(bob_secret.to_bytes(), alice_public.to_bytes()); /// /// assert_eq!(alice_shared, bob_shared); /// ``` From 0cca7977fcc9c6ecf7a8d75d70d7ce3e75f9a87f Mon Sep 17 00:00:00 2001 From: Isis Lovecruft Date: Wed, 14 Apr 2021 19:29:09 +0000 Subject: [PATCH 03/13] Derive Zeroize for PublicKey. --- src/x25519.rs | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/src/x25519.rs b/src/x25519.rs index 1c0c46f..12a262c 100644 --- a/src/x25519.rs +++ b/src/x25519.rs @@ -23,13 +23,19 @@ use rand_core::RngCore; use zeroize::Zeroize; -/// A Diffie-Hellman public key, corresponding to an [`EphemeralSecret`] or [`StaticSecret`] key. +/// A Diffie-Hellman public key, corresponding to an [`EphemeralSecret`] or +/// [`StaticSecret`] key. +/// +/// We implement `Zeroize` so that downstream consumers may derive it for `Drop` +/// should they wish to erase public keys from memory. Note that this erasure +/// (in this crate) does *not* automatically happen, but either must be derived +/// for Drop or explicitly called. #[cfg_attr(feature = "serde", serde(crate = "our_serde"))] #[cfg_attr( feature = "serde", derive(our_serde::Serialize, our_serde::Deserialize) )] -#[derive(PartialEq, Eq, Hash, Copy, Clone, Debug)] +#[derive(PartialEq, Eq, Hash, Copy, Clone, Debug, Zeroize)] pub struct PublicKey(pub(crate) MontgomeryPoint); impl From<[u8; 32]> for PublicKey { From 9e387372e62177caa6c0b41aa2ec72655d9d0f6d Mon Sep 17 00:00:00 2001 From: Isis Lovecruft Date: Wed, 14 Apr 2021 19:33:11 +0000 Subject: [PATCH 04/13] Remove unused import from test suite. --- src/x25519.rs | 2 -- 1 file changed, 2 deletions(-) diff --git a/src/x25519.rs b/src/x25519.rs index 12a262c..4043076 100644 --- a/src/x25519.rs +++ b/src/x25519.rs @@ -260,8 +260,6 @@ impl From for Scalar { mod test { use super::*; - use rand_core::OsRng; - #[test] fn byte_basepoint_matches_edwards_scalar_mul() { let mut scalar_bytes = [0x37; 32]; From 2333b526981fd3db7b0cc55f826028d45a8425b2 Mon Sep 17 00:00:00 2001 From: Isis Lovecruft Date: Wed, 14 Apr 2021 19:45:36 +0000 Subject: [PATCH 05/13] Move tests to a separate directory. --- src/x25519.rs | 184 ------------------------------------------- test/x25519_tests.rs | 182 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 182 insertions(+), 184 deletions(-) create mode 100644 test/x25519_tests.rs diff --git a/src/x25519.rs b/src/x25519.rs index 4043076..538af36 100644 --- a/src/x25519.rs +++ b/src/x25519.rs @@ -255,187 +255,3 @@ impl From for Scalar { clamp_scalar(bytes.0) } } - -#[cfg(test)] -mod test { - use super::*; - - #[test] - fn byte_basepoint_matches_edwards_scalar_mul() { - let mut scalar_bytes = [0x37; 32]; - - for i in 0..32 { - scalar_bytes[i] += 2; - - let result = x25519(scalar_bytes, X25519_BASEPOINT_BYTES); - - let expected = (&ED25519_BASEPOINT_TABLE * &clamp_scalar(scalar_bytes)) - .to_montgomery() - .to_bytes(); - - assert_eq!(result, expected); - } - } - - #[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); - - assert_eq!(result, expected); - } - - #[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, - ]; - 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, - ]; - 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, - ]; - - do_rfc7748_ladder_test1(input_scalar, input_point, expected); - } - - #[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, - ]; - 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, - ]; - 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, - ]; - - do_rfc7748_ladder_test1(input_scalar, input_point, expected); - } - - #[test] - #[ignore] // Run only if you want to burn a lot of CPU doing 1,000,000 DH operations - fn rfc7748_ladder_test2() { - use curve25519_dalek::constants::X25519_BASEPOINT; - - let mut k: [u8; 32] = X25519_BASEPOINT.0; - let mut u: [u8; 32] = X25519_BASEPOINT.0; - let mut result: [u8; 32]; - - macro_rules! do_iterations { - ($n:expr) => { - for _ in 0..$n { - result = x25519(k, u); - // OBVIOUS THING THAT I'M GOING TO NOTE ANYWAY BECAUSE I'VE - // SEEN PEOPLE DO THIS WITH GOLANG'S STDLIB AND YOU SURE AS - // HELL SHOULDN'T DO HORRIBLY STUPID THINGS LIKE THIS WITH - // MY LIBRARY: - // - // NEVER EVER TREAT SCALARS AS POINTS AND/OR VICE VERSA. - // - // ↓↓ DON'T DO THIS ↓↓ - u = k.clone(); - k = result; - } - }; - } - - // After one iteration: - // 422c8e7a6227d7bca1350b3e2bb7279f7897b87bb6854b783c60e80311ae3079 - // After 1,000 iterations: - // 684cf59ba83309552800ef566f2f4d3c1c3887c49360e3875f2eb94d99532c51 - // After 1,000,000 iterations: - // 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, - ] - ); - 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, - ] - ); - 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, - ] - ); - } -} diff --git a/test/x25519_tests.rs b/test/x25519_tests.rs new file mode 100644 index 0000000..c7cc6e2 --- /dev/null +++ b/test/x25519_tests.rs @@ -0,0 +1,182 @@ + +use x25519_dalek::*; + +#[test] +fn byte_basepoint_matches_edwards_scalar_mul() { + let mut scalar_bytes = [0x37; 32]; + + for i in 0..32 { + scalar_bytes[i] += 2; + + let result = x25519(scalar_bytes, X25519_BASEPOINT_BYTES); + + let expected = (&ED25519_BASEPOINT_TABLE * &clamp_scalar(scalar_bytes)) + .to_montgomery() + .to_bytes(); + + assert_eq!(result, expected); + } +} + +#[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); + + assert_eq!(result, expected); +} + +#[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, + ]; + 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, + ]; + 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, + ]; + + do_rfc7748_ladder_test1(input_scalar, input_point, expected); +} + +#[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, + ]; + 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, + ]; + 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, + ]; + + do_rfc7748_ladder_test1(input_scalar, input_point, expected); +} + +#[test] +#[ignore] // Run only if you want to burn a lot of CPU doing 1,000,000 DH operations +fn rfc7748_ladder_test2() { + use curve25519_dalek::constants::X25519_BASEPOINT; + + let mut k: [u8; 32] = X25519_BASEPOINT.0; + let mut u: [u8; 32] = X25519_BASEPOINT.0; + let mut result: [u8; 32]; + + macro_rules! do_iterations { + ($n:expr) => { + for _ in 0..$n { + result = x25519(k, u); + // OBVIOUS THING THAT I'M GOING TO NOTE ANYWAY BECAUSE I'VE + // SEEN PEOPLE DO THIS WITH GOLANG'S STDLIB AND YOU SURE AS + // HELL SHOULDN'T DO HORRIBLY STUPID THINGS LIKE THIS WITH + // MY LIBRARY: + // + // NEVER EVER TREAT SCALARS AS POINTS AND/OR VICE VERSA. + // + // ↓↓ DON'T DO THIS ↓↓ + u = k.clone(); + k = result; + } + }; + } + + // After one iteration: + // 422c8e7a6227d7bca1350b3e2bb7279f7897b87bb6854b783c60e80311ae3079 + // After 1,000 iterations: + // 684cf59ba83309552800ef566f2f4d3c1c3887c49360e3875f2eb94d99532c51 + // After 1,000,000 iterations: + // 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, + ] + ); + 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, + ] + ); + 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, + ] + ); +} + From 893e0506a3b9795b933f1df3a63a06aa28b46a8b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Garillot?= Date: Mon, 3 May 2021 16:31:32 -0700 Subject: [PATCH 06/13] Threads the `fiat_{u32,u64}_backend` features through the feature set This allows the fiat backends introduced in [curve25519-dalek/#342](https://github.com/dalek-cryptography/curve25519-dalek/pull/342) to be used from an x25519 import without cumbersome overrides. --- Cargo.toml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Cargo.toml b/Cargo.toml index 78a2004..2173705 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -7,7 +7,7 @@ edition = "2018" # - update CHANGELOG version = "1.1.0" authors = [ - "Isis Lovecruft ", + "Isis Lovecruft ", "DebugSteven ", "Henry de Valence ", ] @@ -55,3 +55,5 @@ std = ["curve25519-dalek/std"] nightly = ["curve25519-dalek/nightly"] u64_backend = ["curve25519-dalek/u64_backend"] u32_backend = ["curve25519-dalek/u32_backend"] +fiat_u64_backend = ["curve25519-dalek/fiat_u64_backend"] +fiat_u32_backend = ["curve25519-dalek/fiat_u32_backend"] From ee2500db750ab170209e6fb192568e2697b034dd Mon Sep 17 00:00:00 2001 From: exfalso <0slemi0@gmail.com> Date: Tue, 17 Aug 2021 09:49:02 +0200 Subject: [PATCH 07/13] feature(external_doc) -> doc = include_str --- src/lib.rs | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index de5ef19..845538b 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -16,9 +16,8 @@ #![no_std] #![cfg_attr(feature = "bench", feature(test))] -#![cfg_attr(feature = "nightly", feature(external_doc))] #![cfg_attr(feature = "nightly", deny(missing_docs))] -#![cfg_attr(feature = "nightly", doc(include = "../README.md"))] +#![cfg_attr(feature = "nightly", doc = include_str!("../README.md"))] #![doc(html_logo_url = "https://doc.dalek.rs/assets/dalek-logo-clear.png")] #![doc(html_root_url = "https://docs.rs/x25519-dalek/1.1.1")] From 4f0ad7780529d89569a0111382faefd8557e3723 Mon Sep 17 00:00:00 2001 From: Isis Lovecruft Date: Mon, 13 Sep 2021 21:40:13 +0000 Subject: [PATCH 08/13] Fix test errors from #70. --- {test => tests}/x25519_tests.rs | 11 +++++++++++ 1 file changed, 11 insertions(+) rename {test => tests}/x25519_tests.rs (96%) diff --git a/test/x25519_tests.rs b/tests/x25519_tests.rs similarity index 96% rename from test/x25519_tests.rs rename to tests/x25519_tests.rs index c7cc6e2..6194612 100644 --- a/test/x25519_tests.rs +++ b/tests/x25519_tests.rs @@ -1,6 +1,17 @@ +use curve25519_dalek::constants::ED25519_BASEPOINT_TABLE; +use curve25519_dalek::scalar::Scalar; + use x25519_dalek::*; +fn clamp_scalar(mut scalar: [u8; 32]) -> Scalar { + scalar[0] &= 248; + scalar[31] &= 127; + scalar[31] |= 64; + + Scalar::from_bits(scalar) +} + #[test] fn byte_basepoint_matches_edwards_scalar_mul() { let mut scalar_bytes = [0x37; 32]; From adbd0e37a414d2c8ce2e6008bf688101347f10ce Mon Sep 17 00:00:00 2001 From: Isis Lovecruft Date: Mon, 13 Sep 2021 21:44:15 +0000 Subject: [PATCH 09/13] Pin zeroize to 1.3 for now to support older MSRVs. I reserve the right to change this between minor version changes in x25519-dalek. This closes https://github.com/dalek-cryptography/x25519-dalek/issues/74 --- Cargo.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Cargo.toml b/Cargo.toml index 5cf3945..2604de3 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -38,7 +38,7 @@ 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"] } +zeroize = { version = "=1.3", default-features = false, features = ["zeroize_derive"] } [dev-dependencies] bincode = "1" From 02fc85ea218912a25fe43b258dd3a91ab7d5a03a Mon Sep 17 00:00:00 2001 From: Isis Lovecruft Date: Mon, 13 Sep 2021 21:54:44 +0000 Subject: [PATCH 10/13] Enable CI via github actions. --- .github/workflows/rust.yml | 101 +++++++++++++++++++++++++++++++++++++ 1 file changed, 101 insertions(+) create mode 100644 .github/workflows/rust.yml diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml new file mode 100644 index 0000000..8df1723 --- /dev/null +++ b/.github/workflows/rust.yml @@ -0,0 +1,101 @@ +name: Rust + +on: + push: + branches: [ '*' ] + pull_request: + branches: [ main, develop ] + +env: + CARGO_TERM_COLOR: always + +jobs: + test-u32: + name: Test u32 backend + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - uses: actions-rs/toolchain@v1 + with: + profile: minimal + toolchain: stable + override: true + - uses: actions-rs/cargo@v1 + with: + command: test + args: --no-default-features --features "std u32_backend" + + test-u64: + name: Test u64 backend + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - uses: actions-rs/toolchain@v1 + with: + profile: minimal + toolchain: stable + override: true + - uses: actions-rs/cargo@v1 + with: + command: test + args: --no-default-features --features "std u64_backend" + + nightly: + name: Test nightly compiler + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - uses: actions-rs/toolchain@v1 + with: + profile: minimal + toolchain: nightly + override: true + - uses: actions-rs/cargo@v1 + with: + command: test + args: --features "nightly" + + test-defaults-serde: + name: Test default feature selection and serde + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - uses: actions-rs/toolchain@v1 + with: + profile: minimal + toolchain: stable + override: true + - uses: actions-rs/cargo@v1 + with: + command: test + args: --features "serde" + + msrv: + name: Current MSRV is 1.54 + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - uses: actions-rs/toolchain@v1 + with: + profile: minimal + toolchain: 1.54 + override: true + - uses: actions-rs/cargo@v1 + with: + command: test + + bench: + name: Check that benchmarks compile + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - uses: actions-rs/toolchain@v1 + with: + profile: minimal + toolchain: stable + override: true + - uses: actions-rs/cargo@v1 + with: + command: bench + # This filter selects no benchmarks, so we don't run any, only build them. + args: "DONTRUNBENCHMARKS" From 84094ba9ea9f32389c535f1e0478e9508c614527 Mon Sep 17 00:00:00 2001 From: Isis Lovecruft Date: Mon, 13 Sep 2021 22:33:05 +0000 Subject: [PATCH 11/13] Fix serde tests. --- tests/x25519_tests.rs | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/tests/x25519_tests.rs b/tests/x25519_tests.rs index 6194612..9fce935 100644 --- a/tests/x25519_tests.rs +++ b/tests/x25519_tests.rs @@ -59,8 +59,7 @@ fn serde_bincode_public_key_matches_from_bytes() { fn serde_bincode_static_secret_roundtrip() { use bincode; - let static_secret = StaticSecret(clamp_scalar([0x24; 32])); - + let static_secret = StaticSecret::from([0x24; 32]); let encoded = bincode::serialize(&static_secret).unwrap(); let decoded: StaticSecret = bincode::deserialize(&encoded).unwrap(); @@ -73,7 +72,7 @@ fn serde_bincode_static_secret_roundtrip() { fn serde_bincode_static_secret_matches_from_bytes() { use bincode; - let expected = StaticSecret(clamp_scalar([0x24; 32])); + let expected = StaticSecret::from([0x24; 32]); let clamped_bytes = clamp_scalar([0x24; 32]).to_bytes(); let decoded: StaticSecret = bincode::deserialize(&clamped_bytes).unwrap(); From a32a92798a4944e032b72a333d333424f0d0cc22 Mon Sep 17 00:00:00 2001 From: Isis Lovecruft Date: Mon, 13 Sep 2021 22:37:52 +0000 Subject: [PATCH 12/13] Get rid of the include_str!() docs to support earlier MSRVs. --- Cargo.toml | 1 + src/lib.rs | 133 +++++++++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 131 insertions(+), 3 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index 2604de3..0871841 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -5,6 +5,7 @@ edition = "2018" # - update version in README.md # - update html_root_url # - update CHANGELOG +# - if any changes were made to README.md, mirror them in src/lib.rs docs version = "1.1.1" authors = [ "Isis Lovecruft ", diff --git a/src/lib.rs b/src/lib.rs index 845538b..e5f7bfe 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -17,12 +17,139 @@ #![no_std] #![cfg_attr(feature = "bench", feature(test))] #![cfg_attr(feature = "nightly", deny(missing_docs))] -#![cfg_attr(feature = "nightly", doc = include_str!("../README.md"))] #![doc(html_logo_url = "https://doc.dalek.rs/assets/dalek-logo-clear.png")] #![doc(html_root_url = "https://docs.rs/x25519-dalek/1.1.1")] -//! Note that docs will only build on nightly Rust until -//! `feature(external_doc)` is stabilized. +//! # x25519-dalek [![](https://img.shields.io/crates/v/x25519-dalek.svg)](https://crates.io/crates/x25519-dalek) [![](https://docs.rs/x25519-dalek/badge.svg)](https://docs.rs/x25519-dalek) [![](https://travis-ci.org/dalek-cryptography/x25519-dalek.svg?branch=master)](https://travis-ci.org/dalek-cryptography/x25519-dalek) +//! +//! A pure-Rust implementation of x25519 elliptic curve Diffie-Hellman key exchange, +//! with curve operations provided by +//! [curve25519-dalek](https://github.com/dalek-cryptography/curve25519-dalek). +//! +//! This crate provides two levels of API: a bare byte-oriented `x25519` +//! function which matches the function specified in [RFC7748][rfc7748], as +//! well as a higher-level Rust API for static and ephemeral Diffie-Hellman. +//! +//! ## Examples +//! +//! +//! +//! +//! +//! Alice and Bob are two adorable kittens who have lost their mittens, and they +//! wish to be able to send secret messages to each other to coordinate finding +//! them, otherwise—if their caretaker cat finds out—they will surely be called +//! naughty kittens and be given no pie! +//! +//! But the two kittens are quite clever. Even though their paws are still too big +//! and the rest of them is 90% fuzziness, these clever kittens have been studying +//! up on modern public key cryptography and have learned a nifty trick called +//! *elliptic curve Diffie-Hellman key exchange*. With the right incantations, the +//! kittens will be able to secretly organise to find their mittens, and then spend +//! the rest of the afternoon nomming some yummy pie! +//! +//! First, Alice uses `EphemeralSecret::new()` and then +//! `PublicKey::from()` to produce her secret and public keys: +//! +//! ```rust +//! use rand_core::OsRng; +//! use x25519_dalek::{EphemeralSecret, PublicKey}; +//! +//! let alice_secret = EphemeralSecret::new(OsRng); +//! let alice_public = PublicKey::from(&alice_secret); +//! ``` +//! +//! Bob does the same: +//! +//! ```rust +//! # use rand_core::OsRng; +//! # use x25519_dalek::{EphemeralSecret, PublicKey}; +//! let bob_secret = EphemeralSecret::new(OsRng); +//! let bob_public = PublicKey::from(&bob_secret); +//! ``` +//! +//! Alice meows across the room, telling `alice_public` to Bob, and Bob +//! loudly meows `bob_public` back to Alice. Alice now computes her +//! shared secret with Bob by doing: +//! +//! ```rust +//! # use rand_core::OsRng; +//! # use x25519_dalek::{EphemeralSecret, PublicKey}; +//! # let alice_secret = EphemeralSecret::new(OsRng); +//! # let alice_public = PublicKey::from(&alice_secret); +//! # let bob_secret = EphemeralSecret::new(OsRng); +//! # let bob_public = PublicKey::from(&bob_secret); +//! let alice_shared_secret = alice_secret.diffie_hellman(&bob_public); +//! ``` +//! +//! Similarly, Bob computes a shared secret by doing: +//! +//! ```rust +//! # use rand_core::OsRng; +//! # use x25519_dalek::{EphemeralSecret, PublicKey}; +//! # let alice_secret = EphemeralSecret::new(OsRng); +//! # let alice_public = PublicKey::from(&alice_secret); +//! # let bob_secret = EphemeralSecret::new(OsRng); +//! # let bob_public = PublicKey::from(&bob_secret); +//! let bob_shared_secret = bob_secret.diffie_hellman(&alice_public); +//! ``` +//! +//! These secrets are the same: +//! +//! ```rust +//! # use rand_core::OsRng; +//! # use x25519_dalek::{EphemeralSecret, PublicKey}; +//! # let alice_secret = EphemeralSecret::new(OsRng); +//! # let alice_public = PublicKey::from(&alice_secret); +//! # let bob_secret = EphemeralSecret::new(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); +//! assert_eq!(alice_shared_secret.as_bytes(), bob_shared_secret.as_bytes()); +//! ``` +//! +//! Voilà! Alice and Bob can now use their shared secret to encrypt their +//! meows, for example, by using it to generate a key and nonce for an +//! authenticated-encryption cipher. +//! +//! This example used the ephemeral DH API, which ensures that secret keys +//! cannot be reused; Alice and Bob could instead use the static DH API +//! and load a long-term secret key. +//! +//! # Installation +//! +//! To install, add the following to your project's `Cargo.toml`: +//! +//! ```toml +//! [dependencies] +//! x25519-dalek = "1.1" +//! ``` +//! +//! # Documentation +//! +//! Documentation is available [here](https://docs.rs/x25519-dalek). +//! +//! # Note +//! +//! This code matches the [RFC7748][rfc7748] test vectors. +//! The elliptic curve +//! operations are provided by `curve25519-dalek`, which makes a best-effort +//! attempt to prevent software side-channels. +//! +//! "Secret Messages" cover image and [zine](https://shop.bubblesort.io/products/secret-messages-zine) +//! copyright © Amy Wibowo ([@sailorhg](https://twitter.com/sailorhg)) +//! +//! [rfc7748]: https://tools.ietf.org/html/rfc7748 +//! +//! # See also +//! +//! - [crypto_box]: pure Rust public-key authenticated encryption compatible with +//! the NaCl family of encryption libraries (libsodium, TweetNaCl) which uses +//! `x25519-dalek` for key agreement +//! +//! [crypto_box]: https://github.com/RustCrypto/AEADs/tree/master/crypto_box extern crate curve25519_dalek; From a0a6c57f9e3ac036c68f5ac08ca8e4280ed9ada9 Mon Sep 17 00:00:00 2001 From: Isis Lovecruft Date: Mon, 13 Sep 2021 22:38:34 +0000 Subject: [PATCH 13/13] Bisect to determine MSRV. --- .github/workflows/rust.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml index 8df1723..2846856 100644 --- a/.github/workflows/rust.yml +++ b/.github/workflows/rust.yml @@ -71,14 +71,14 @@ jobs: args: --features "serde" msrv: - name: Current MSRV is 1.54 + name: Current MSRV is 1.41 runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - uses: actions-rs/toolchain@v1 with: profile: minimal - toolchain: 1.54 + toolchain: 1.41 override: true - uses: actions-rs/cargo@v1 with: