diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml new file mode 100644 index 0000000..2ba256c --- /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.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" 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/README.md b/README.md index dee9acc..ce9e7d8 100644 --- a/README.md +++ b/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). diff --git a/src/lib.rs b/src/lib.rs index 845538b..e4990b0 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -17,12 +17,143 @@ #![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" +//! ``` +//! +//! # 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; 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();