Merge pull request #79 from isislovecruft/feature/github-actions

Add GitHub actions for CI and MSRV testing

.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,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 <isis@patternsinthevoid.net>",

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

@@ -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
+//! # 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;
 

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();