Merge tag '2.1.3' into HEAD

Release curve25519-dalek version 2.1.3.

CHANGELOG.md

@@ -18,6 +18,21 @@ major series.
 
 ## 2.x series
 
+### 2.1.3
+
+* Fix documentation builds on nightly due to syntax changes to
+  `#![fg_attr(feature = "nightly", doc = include_str!("../README.md"))]`.
+
+### 2.1.2
+
+* Multiple documenation typo fixes.
+* Fix `alloc` feature working with stable rust.
+
+### 2.1.1
+
+* Update the optional `packed-simd` dependency to rely on a newer,
+  maintained version of the `packed-simd-2` crate.
+
 ### 2.1.0
 
 * Make `Scalar::from_bits` a `const fn`, allowing its use in `const` contexts.

docs/avx2-notes.md

@@ -12,7 +12,7 @@ representation (which uses radix \\(2^{51}\\)) amounts to regrouping
 digits.
 
 The field element representation is oriented around the AVX2
-`vpmuluqdq` instruction, which multiplies the low 32 bits of each
+`vpmuludq` instruction, which multiplies the low 32 bits of each
 64-bit lane of each operand to produce a 64-bit result.
 
 ```text,no_run

docs/parallel-formulas.md

@@ -327,7 +327,7 @@ There are several directions for future improvement:
 [sandy2x]: https://eprint.iacr.org/2015/943.pdf
 [avx2trac]: https://trac.torproject.org/projects/tor/ticket/8897#comment:28
 [hwcd08]: https://www.iacr.org/archive/asiacrypt2008/53500329/53500329.pdf
-[curve_models]: https://doc-internal.dalek.rs/curve25519_dalek/curve_models/index.html
+[curve_models]: https://doc-internal.dalek.rs/curve25519_dalek/backend/serial/curve_models/index.html
 [bbjlp08]: https://eprint.iacr.org/2008/013
 [cmo98]: https://link.springer.com/content/pdf/10.1007%2F3-540-49649-1_6.pdf
 [intel]: https://software.intel.com/sites/default/files/managed/9e/bc/64-ia-32-architectures-optimization-manual.pdf

src/backend/serial/u64/scalar.rs

@@ -443,7 +443,6 @@ mod test {
     fn from_bytes_wide() {
         let bignum = [255u8; 64]; // 2^512 - 1
         let reduced = Scalar52::from_bytes_wide(&bignum);
-        println!("{:?}", reduced);
         for i in 0..5 {
             assert!(reduced[i] == C[i]);
         }

src/backend/vector/avx2/edwards.rs

@@ -153,7 +153,7 @@ impl ExtendedPoint {
         // Set tmp1 = ( S_9,  S_6,  S_6,  S_9)
         //        b < ( 1.6,  1.6,  1.6,  1.6)
         tmp1 = tmp0.shuffle(Shuffle::DBBD);
-        // Set tmp1 = ( S_8,  S_5,  S_8,  S_5)
+        // Set tmp0 = ( S_8,  S_5,  S_8,  S_5)
         //        b < (2.33, 1.01, 2.33, 1.01)
         tmp0 = tmp0.shuffle(Shuffle::CACA);
 
@@ -188,7 +188,7 @@ impl From<ExtendedPoint> for CachedPoint {
         let mut x = P.0;
 
         x = x.blend(x.diff_sum(), Lanes::AB);
-        // x = (X1 - Y1, X2 + Y2, Z2, T2) = (S2 S3 Z2 T2)
+        // x = (Y2 - X2, Y2 + X2, Z2, T2) = (S2 S3 Z2 T2)
 
         x = x * (121666, 121666, 2 * 121666, 2 * 121665);
         // x = (121666*S2 121666*S3 2*121666*Z2 2*121665*T2)
@@ -521,4 +521,24 @@ mod test {
         let P = &constants::ED25519_BASEPOINT_TABLE * &Scalar::from(8475983829u64);
         doubling_test_helper(P);
     }
+
+    #[test]
+    fn basepoint_odd_lookup_table_verify() {
+        use constants;
+        use backend::vector::avx2::constants::{BASEPOINT_ODD_LOOKUP_TABLE};
+
+        let basepoint_odd_table = NafLookupTable8::<CachedPoint>::from(&constants::ED25519_BASEPOINT_POINT);
+        println!("basepoint_odd_lookup_table = {:?}", basepoint_odd_table);
+
+        let table_B = &BASEPOINT_ODD_LOOKUP_TABLE;
+        for (b_vec, base_vec) in table_B.0.iter().zip(basepoint_odd_table.0.iter()) {
+            let b_splits = b_vec.0.split();
+            let base_splits = base_vec.0.split();
+
+            assert_eq!(base_splits[0], b_splits[0]);
+            assert_eq!(base_splits[1], b_splits[1]);
+            assert_eq!(base_splits[2], b_splits[2]);
+            assert_eq!(base_splits[3], b_splits[3]);
+        }
+    }
 }

src/lib.rs

@@ -10,22 +10,240 @@
 
 #![no_std]
 #![cfg_attr(feature = "nightly", feature(test))]
-#![cfg_attr(all(feature = "alloc", not(feature = "std")), feature(alloc))]
-#![cfg_attr(feature = "nightly", feature(external_doc))]
 #![cfg_attr(feature = "nightly", feature(doc_cfg))]
 #![cfg_attr(feature = "simd_backend", feature(stdsimd))]
-// Refuse to compile if documentation is missing, but only on nightly.
-//
-// This means that missing docs will still fail CI, but means we can use
-// README.md as the crate documentation.
-#![cfg_attr(feature = "nightly", deny(missing_docs))]
 
-#![cfg_attr(feature = "nightly", doc(include = "../README.md"))]
+// Refuse to compile if documentation is missing.
+#![deny(missing_docs)]
+
 #![doc(html_logo_url = "https://doc.dalek.rs/assets/dalek-logo-clear.png")]
 #![doc(html_root_url = "https://docs.rs/curve25519-dalek/3.0.0")]
 
-//! Note that docs will only build on nightly Rust until
-//! [RFC 1990 stabilizes](https://github.com/rust-lang/rust/issues/44732).
+//! # curve25519-dalek [![](https://img.shields.io/crates/v/curve25519-dalek.svg)](https://crates.io/crates/curve25519-dalek) [![](https://img.shields.io/badge/dynamic/json.svg?label=docs&uri=https%3A%2F%2Fcrates.io%2Fapi%2Fv1%2Fcrates%2Fcurve25519-dalek%2Fversions&query=%24.versions%5B0%5D.num&colorB=4F74A6)](https://doc.dalek.rs) [![](https://travis-ci.org/dalek-cryptography/curve25519-dalek.svg?branch=master)](https://travis-ci.org/dalek-cryptography/curve25519-dalek)
+//!
+//! <img
+//!  width="33%"
+//!  align="right"
+//!  src="https://doc.dalek.rs/assets/dalek-logo-clear.png"/>
+//!
+//! **A pure-Rust implementation of group operations on Ristretto and Curve25519.**
+//!
+//! `curve25519-dalek` is a library providing group operations on the Edwards and
+//! Montgomery forms of Curve25519, and on the prime-order Ristretto group.
+//!
+//! `curve25519-dalek` is not intended to provide implementations of any particular
+//! crypto protocol.  Rather, implementations of those protocols (such as
+//! [`x25519-dalek`][x25519-dalek] and [`ed25519-dalek`][ed25519-dalek]) should use
+//! `curve25519-dalek` as a library.
+//!
+//! `curve25519-dalek` is intended to provide a clean and safe _mid-level_ API for use
+//! implementing a wide range of ECC-based crypto protocols, such as key agreement,
+//! signatures, anonymous credentials, rangeproofs, and zero-knowledge proof
+//! systems.
+//!
+//! In particular, `curve25519-dalek` implements Ristretto, which constructs a
+//! prime-order group from a non-prime-order Edwards curve.  This provides the
+//! speed and safety benefits of Edwards curve arithmetic, without the pitfalls of
+//! cofactor-related abstraction mismatches.
+//!
+//! # Documentation
+//!
+//! The semver-stable, public-facing `curve25519-dalek` API is documented
+//! [here][docs-external].  In addition, the unstable internal implementation
+//! details are documented [here][docs-internal].
+//!
+//! The `curve25519-dalek` documentation requires a custom HTML header to include
+//! KaTeX for math support. Unfortunately `cargo doc` does not currently support
+//! this, but docs can be built using
+//! ```sh
+//! make doc
+//! make doc-internal
+//! ```
+//!
+//! # Use
+//!
+//! To import `curve25519-dalek`, add the following to the dependencies section of
+//! your project's `Cargo.toml`:
+//! ```toml
+//! curve25519-dalek = "3"
+//! ```
+//!
+//! The sole breaking change in the `3.x` series was an update to the `digest`
+//! version, and in terms of non-breaking changes it includes:
+//!
+//! * support for using `alloc` instead of `std` on stable Rust,
+//! * the Elligator2 encoding for Edwards points,
+//! * a fix to use `packed_simd2`,
+//! * various documentation fixes and improvements,
+//! * support for configurably-sized, precomputed lookup tables for basepoint scalar
+//!   multiplication,
+//! * two new formally-verified field arithmetic backends which use the Fiat Crypto
+//!   Rust code, which is generated from proofs of functional correctness checked by
+//!   the Coq theorem proving system, and
+//! * support for explicitly calling the `zeroize` traits for all point types.
+//!
+//! The `2.x` series has API almost entirely unchanged from the `1.x` series,
+//! except that:
+//!
+//! * an error in the data modeling for the (optional) `serde` feature was
+//!   corrected, so that when the `2.x`-series `serde` implementation is used
+//!   with `serde-bincode`, the derived serialization matches the usual X/Ed25519
+//!   formats;
+//! * the `rand` version was updated.
+//!
+//! See `CHANGELOG.md` for more details.
+//!
+//! # Backends and Features
+//!
+//! The `nightly` feature enables features available only when using a Rust nightly
+//! compiler.  In particular, it is required for rendering documentation and for
+//! the SIMD backends.
+//!
+//! Curve arithmetic is implemented using one of the following backends:
+//!
+//! * a `u32` backend using serial formulas and `u64` products;
+//! * a `u64` backend using serial formulas and `u128` products;
+//! * an `avx2` backend using [parallel formulas][parallel_doc] and `avx2` instructions (sets speed records);
+//! * an `ifma` backend using [parallel formulas][parallel_doc] and `ifma` instructions (sets speed records);
+//!
+//! By default the `u64` backend is selected.  To select a specific backend, use:
+//! ```sh
+//! cargo build --no-default-features --features "std u32_backend"
+//! cargo build --no-default-features --features "std u64_backend"
+//! # Requires nightly, RUSTFLAGS="-C target_feature=+avx2" to use avx2
+//! cargo build --no-default-features --features "std simd_backend"
+//! # Requires nightly, RUSTFLAGS="-C target_feature=+avx512ifma" to use ifma
+//! cargo build --no-default-features --features "std simd_backend"
+//! ```
+//! Crates using `curve25519-dalek` can either select a backend on behalf of their
+//! users, or expose feature flags that control the `curve25519-dalek` backend.
+//!
+//! The `std` feature is enabled by default, but it can be disabled for no-`std`
+//! builds using `--no-default-features`.  Note that this requires explicitly
+//! selecting an arithmetic backend using one of the `_backend` features.
+//! If no backend is selected, compilation will fail.
+//!
+//! # Safety
+//!
+//! The `curve25519-dalek` types are designed to make illegal states
+//! unrepresentable.  For example, any instance of an `EdwardsPoint` is
+//! guaranteed to hold a point on the Edwards curve, and any instance of a
+//! `RistrettoPoint` is guaranteed to hold a valid point in the Ristretto
+//! group.
+//!
+//! All operations are implemented using constant-time logic (no
+//! secret-dependent branches, no secret-dependent memory accesses),
+//! unless specifically marked as being variable-time code.
+//! We believe that our constant-time logic is lowered to constant-time
+//! assembly, at least on `x86_64` targets.
+//!
+//! As an additional guard against possible future compiler optimizations,
+//! the `subtle` crate places an optimization barrier before every
+//! conditional move or assignment.  More details can be found in [the
+//! documentation for the `subtle` crate][subtle_doc].
+//!
+//! Some functionality (e.g., multiscalar multiplication or batch
+//! inversion) requires heap allocation for temporary buffers.  All
+//! heap-allocated buffers of potentially secret data are explicitly
+//! zeroed before release.
+//!
+//! However, we do not attempt to zero stack data, for two reasons.
+//! First, it's not possible to do so correctly: we don't have control
+//! over stack allocations, so there's no way to know how much data to
+//! wipe.  Second, because `curve25519-dalek` provides a mid-level API,
+//! the correct place to start zeroing stack data is likely not at the
+//! entrypoints of `curve25519-dalek` functions, but at the entrypoints of
+//! functions in other crates.
+//!
+//! The implementation is memory-safe, and contains no significant
+//! `unsafe` code.  The SIMD backend uses `unsafe` internally to call SIMD
+//! intrinsics.  These are marked `unsafe` only because invoking them on an
+//! inappropriate CPU would cause `SIGILL`, but the entire backend is only
+//! compiled with appropriate `target_feature`s, so this cannot occur.
+//!
+//! # Performance
+//!
+//! Benchmarks are run using [`criterion.rs`][criterion]:
+//!
+//! ```sh
+//! cargo bench --no-default-features --features "std u32_backend"
+//! cargo bench --no-default-features --features "std u64_backend"
+//! # Uses avx2 or ifma only if compiled for an appropriate target.
+//! export RUSTFLAGS="-C target_cpu=native"
+//! cargo bench --no-default-features --features "std simd_backend"
+//! ```
+//!
+//! Performance is a secondary goal behind correctness, safety, and
+//! clarity, but we aim to be competitive with other implementations.
+//!
+//! # FFI
+//!
+//! Unfortunately, we have no plans to add FFI to `curve25519-dalek` directly.  The
+//! reason is that we use Rust features to provide an API that maintains safety
+//! invariants, which are not possible to maintain across an FFI boundary.  For
+//! instance, as described in the _Safety_ section above, invalid points are
+//! impossible to construct, and this would not be the case if we exposed point
+//! operations over FFI.
+//!
+//! However, `curve25519-dalek` is designed as a *mid-level* API, aimed at
+//! implementing other, higher-level primitives.  Instead of providing FFI at the
+//! mid-level, our suggestion is to implement the higher-level primitive (a
+//! signature, PAKE, ZKP, etc) in Rust, using `curve25519-dalek` as a dependency,
+//! and have that crate provide a minimal, byte-buffer-oriented FFI specific to
+//! that primitive.
+//!
+//! # Contributing
+//!
+//! Please see [CONTRIBUTING.md][contributing].
+//!
+//! Patches and pull requests should be make against the `develop`
+//! branch, **not** `master`.
+//!
+//! # About
+//!
+//! **SPOILER ALERT:** *The Twelfth Doctor's first encounter with the Daleks is in
+//! his second full episode, "Into the Dalek". A beleaguered ship of the "Combined
+//! Galactic Resistance" has discovered a broken Dalek that has turned "good",
+//! desiring to kill all other Daleks. The Doctor, Clara and a team of soldiers
+//! are miniaturized and enter the Dalek, which the Doctor names Rusty. They
+//! repair the damage, but accidentally restore it to its original nature, causing
+//! it to go on the rampage and alert the Dalek fleet to the whereabouts of the
+//! rebel ship. However, the Doctor manages to return Rusty to its previous state
+//! by linking his mind with the Dalek's: Rusty shares the Doctor's view of the
+//! universe's beauty, but also his deep hatred of the Daleks. Rusty destroys the
+//! other Daleks and departs the ship, determined to track down and bring an end
+//! to the Dalek race.*
+//!
+//! `curve25519-dalek` is authored by Isis Agora Lovecruft and Henry de Valence.
+//!
+//! Portions of this library were originally a port of [Adam Langley's
+//! Golang ed25519 library](https://!github.com/agl/ed25519), which was in
+//! turn a port of the reference `ref10` implementation.  Most of this code,
+//! including the 32-bit field arithmetic, has since been rewritten.
+//!
+//! The fast `u32` and `u64` scalar arithmetic was implemented by Andrew Moon, and
+//! the addition chain for scalar inversion was provided by Brian Smith.  The
+//! optimised batch inversion was contributed by Sean Bowe and Daira Hopwood.
+//!
+//! The `no_std` and `zeroize` support was contributed by Tony Arcieri.
+//!
+//! The formally verified backends, `fiat_u32_backend` and `fiat_u64_backend`, which
+//! integrate with the Rust generated by the
+//! [Fiat Crypto project](https://github.com/mit-plv/fiat-crypto) were contributed
+//! by François Garillot.
+//!
+//! Thanks also to Ashley Hauck, Lucas Salibian, Manish Goregaokar, Jack Grigg,
+//! Pratyush Mishra, Michael Rosenberg, and countless others for their
+//! contributions.
+//!
+//! [ed25519-dalek]: https://github.com/dalek-cryptography/ed25519-dalek
+//! [x25519-dalek]: https://github.com/dalek-cryptography/x25519-dalek
+//! [contributing]: https://github.com/dalek-cryptography/curve25519-dalek/blob/master/CONTRIBUTING.md
+//! [docs-external]: https://doc.dalek.rs/curve25519_dalek/
+//! [docs-internal]: https://doc-internal.dalek.rs/curve25519_dalek/
+//! [criterion]: https://github.com/japaric/criterion.rs
+//! [parallel_doc]: https://doc-internal.dalek.rs/curve25519_dalek/backend/vector/avx2/index.html
+//! [subtle_doc]: https://doc.dalek.rs/subtle/
 
 //------------------------------------------------------------------------
 // External dependencies: