Merge branch 'feature/github-actions' into main

.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.41
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - uses: actions-rs/toolchain@v1
+      with:
+        profile: minimal
+        toolchain: 1.41
+        override: true
+    - uses: actions-rs/cargo@v1
+      with:
+        command: build
+
+  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"

Cargo.toml

@@ -5,9 +5,10 @@ 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 <isis@patternsinthevoid.net>", 
+    "Isis Lovecruft <isis@patternsinthevoid.net>",
     "DebugSteven <debugsteven@gmail.com>",
     "Henry de Valence <hdevalence@hdevalence.ca>",
 ]
@@ -38,7 +39,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"
@@ -55,3 +56,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"]

README.md

@@ -105,6 +105,10 @@ To install, add the following to your project's `Cargo.toml`:
 x25519-dalek = "1.1"
 ```
 
+# MSRV
+
+Current MSRV is 1.41 for production builds, and 1.48 for running tests.
+
 # Documentation
 
 Documentation is available [here](https://docs.rs/x25519-dalek).

src/lib.rs

@@ -16,14 +16,144 @@
 
 #![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"))]
 #![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
+//! # 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)
-//! `feature(external_doc)` is stabilized.
+//!
+//! 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
+//!
+//! <a href="https://shop.bubblesort.io">
+//! <img
+//!   style="float: right; width: auto; height: 300px;"
+//!   src="https://raw.githubusercontent.com/dalek-cryptography/x25519-dalek/master/res/bubblesort-zines-secret-messages-cover.jpeg"/>
+//! </a>
+//!
+//! 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"
+//! ```
+//!
+//! # MSRV
+//!
+//! Current MSRV is 1.41 for production builds, and 1.48 for running tests.
+//!
+//! # 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;
 

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 {
@@ -192,7 +198,35 @@ fn clamp_scalar(mut scalar: [u8; 32]) -> Scalar {
 /// The bare, byte-oriented x25519 function, exactly as specified in RFC7748.
 ///
 /// This can be used with [`X25519_BASEPOINT_BYTES`] for people who
-/// cannot use the better, safer, and faster DH API.
+/// cannot use the better, safer, and faster ephemeral DH API.
+///
+/// # Example
+/// ```
+/// # extern crate rand_core;
+/// #
+/// use rand_core::OsRng;
+/// use rand_core::RngCore;
+///
+/// use x25519_dalek::x25519;
+/// use x25519_dalek::StaticSecret;
+/// use x25519_dalek::PublicKey;
+///
+/// // Generate Alice's key pair.
+/// let alice_secret = StaticSecret::new(&mut OsRng);
+/// let alice_public = PublicKey::from(&alice_secret);
+///
+/// // Generate Bob's key pair.
+/// let bob_secret = StaticSecret::new(&mut OsRng);
+/// let bob_public = PublicKey::from(&bob_secret);
+///
+/// // Alice and Bob should now exchange their public keys.
+///
+/// // 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);
+/// ```
 pub fn x25519(k: [u8; 32], u: [u8; 32]) -> [u8; 32] {
     (clamp_scalar(k) * MontgomeryPoint(u)).to_bytes()
 }
@@ -221,189 +255,3 @@ impl From<AllowUnreducedScalarBytes> for Scalar {
         clamp_scalar(bytes.0)
     }
 }
-
-#[cfg(test)]
-mod test {
-    use super::*;
-
-    use rand_core::OsRng;
-
-    #[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,
-            ]
-        );
-    }
-}

tests/x25519_tests.rs

@@ -0,0 +1,192 @@
+
+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];
+
+    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::from([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::from([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,
+        ]
+    );
+}
+