diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml
index d294b3d..f427ac3 100644
--- a/.github/workflows/rust.yml
+++ b/.github/workflows/rust.yml
@@ -52,7 +52,7 @@ jobs:
steps:
- uses: actions/checkout@v3
- uses: dtolnay/rust-toolchain@nightly
- - run: cargo test --features "nightly"
+ - run: cargo test
clippy:
name: Check that clippy is happy
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d6c083f..841d380 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,12 +5,26 @@ major series.
## 4.x series
+### 4.0.0
+
+#### Breaking changes
+
+* Update the MSRV from 1.41 to 1.56.1
* Make `digest` an optional feature
* Make `rand_core` an optional feature
* Add target u32/u64 backend overrides
+* Update backend selection to be more automatic
+* Remove `std` feature flag
+* Remove `nightly` feature flag
+* Deprecate `EdwardsPoint::hash_from_bytes` and rename it `EdwardsPoint::nonspec_map_to_curve`
+* Require including a new trait, `use curve25519_dalek::traits::BasepointTable`
+ whenever using `EdwardsBasepointTable` or `RistrettoBasepointTable`
+
+#### Other changes
+
+* Update Maintenance Policies for SemVer
* Migrate documentation to docs.rs hosted
* Fix backend documentation generation
-* Deprecate `EdwardsPoint::hash_from_bytes` and rename it `EdwardsPoint::nonspect_map_to_curve`
* Fix panic when `Ristretto::double_and_compress_batch` receives the identity point
* Remove `byteorder` dependency
* Update the `criterion` dependency to 0.4.0
@@ -18,7 +32,6 @@ major series.
* Update the `rand_core` dependency version and the `rand` dev-dependency
version.
* Relax the `zeroize` dependency to `^1`
-* Update the MSRV from 1.41 to 1.56.1
* Update the edition from 2015 to 2021
## 3.x series
@@ -71,6 +84,8 @@ major series.
### 3.0.0
+#### Breaking changes
+
* Update the `digest` dependency to `0.9`. This requires a major version
because the `digest` traits are part of the public API, but there are
otherwise no changes to the API.
@@ -98,12 +113,20 @@ major series.
### 2.0.0
+The only significant change is the data model change to the `serde` feature;
+besides the `rand_core` version bump, there are no other user-visible changes.
+
+#### Breaking changes
+
* Fix a data modeling error in the `serde` feature pointed out by Trevor Perrin
which caused points and scalars to be serialized with length fields rather
than as fixed-size 32-byte arrays. This is a breaking change, but it fixes
compatibility with `serde-json` and ensures that the `serde-bincode` encoding
matches the conventional encoding for X/Ed25519.
* Update `rand_core` to `0.5`, allowing use with new `rand` versions.
+
+#### Other changes
+
* Switch from `clear_on_drop` to `zeroize` (by Tony Arcieri).
* Require `subtle = ^2.2.1` and remove the note advising nightly Rust, which is
no longer required as of that version of `subtle`. See the `subtle`
@@ -112,9 +135,6 @@ major series.
* Remove the `build.rs` hack which loaded the entire crate into its own
`build.rs` to generate constants, and keep the constants in the source code.
-The only significant change is the data model change to the `serde` feature;
-besides the `rand_core` version bump, there are no other user-visible changes.
-
## 1.x series
### 1.2.6
diff --git a/Cargo.toml b/Cargo.toml
index 8b8bbf3..4c37168 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -56,11 +56,10 @@ zeroize = { version = "1", default-features = false }
fiat-crypto = { version = "0.1.6", optional = true}
[features]
-nightly = ["subtle/nightly"]
default = ["alloc"]
alloc = ["zeroize/alloc"]
# fiat-crypto backend with formally-verified field arithmetic
fiat_backend = ["fiat-crypto"]
# The SIMD backend uses parallel formulas, using either AVX2 or AVX512-IFMA.
-simd_backend = ["nightly", "packed_simd"]
+simd_backend = ["packed_simd"]
diff --git a/README.md b/README.md
index 7dddb5d..6bc357f 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,10 @@
-# curve25519-dalek [](https://crates.io/crates/curve25519-dalek) [](https://docs.rs/curve25519-dalek) [](https://travis-ci.org/dalek-cryptography/curve25519-dalek)
+# curve25519-dalek [](https://crates.io/crates/curve25519-dalek) [](https://docs.rs/curve25519-dalek) [](https://github.com/dalek-cryptography/curve25519-dalek/actions/workflows/rust.yml)
-
+
@@ -28,104 +28,122 @@ 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 `curve25519-dalek` public API and the backends are documented [here][docs-external].
-
-In addition, the unstable internal implementation can be generated locally as below.
-
-```sh
-make doc-internal
-```
-
# Use
To import `curve25519-dalek`, add the following to the dependencies section of
your project's `Cargo.toml`:
```toml
-curve25519-dalek = "4.0.0-pre.2"
+curve25519-dalek = "4"
```
+## Feature Flags
+
+| Feature | Default? | Description |
+| :--- | :---: | :--- |
+| `alloc` | ✓ | Enables Edwards and Ristretto multiscalar multiplication, batch scalar inversion, and batch Ristretto double-and-compress. |
+| `rand_core` | | Enables `Scalar::random` and `RistrettoPoint::random`. This is an optional dependency whose version is not subject to SemVer. See [below](#public-api-semver-exemptions) for more details. |
+| `digest` | | Enables `RistrettoPoint::{from_hash, hash_from_bytes}` and `Scalar::{from_hash, hash_from_bytes}`. This is an optional dependency whose version is not subject to SemVer. See [below](#public-api-semver-exemptions) for more details. |
+| `serde` | | Enables `serde` serialization/deserialization for all the point and scalar types. |
+| `simd_backend` | | See [backends](#backends). Requires nightly. |
+| `fiat_backend` | | See [backends](#backends). |
+
+To disable the default features when using `curve25519-dalek` as a dependency,
+add `default-features = false` to the dependency in your `Cargo.toml`. To
+disable it when running `cargo`, add the `--no-default-features` CLI flag.
+
## Major Version API Changes
-See `CHANGELOG.md` for more details.
+Breaking changes for each major version release can be found in
+[`CHANGELOG.md`](CHANGELOG.md), under the "Breaking changes" subheader. The
+latest breaking changes are below:
-### 2.x
+### Breaking changes in 4.0.0
-The `2.x` series has API almost entirely unchanged from the `1.x` series,
-except that:
+* Update the MSRV from 1.41 to 1.56.1
+* Update backend selection to be more automatic. See [backends](#backends)
+* Remove `std` feature flag
+* Remove `nightly` feature flag
+* Deprecate `EdwardsPoint::hash_from_bytes` and rename it
+ `EdwardsPoint::nonspec_map_to_curve`
+* Require including a new trait, `use curve25519_dalek::traits::BasepointTable`
+ whenever using `EdwardsBasepointTable` or `RistrettoBasepointTable`
-* 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.
+This release also does a lot of dependency updates and relaxations to unblock upstream build issues.
-### 3.x (current stable)
+# Backends
-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:
+Curve arithmetic is implemented and used by selecting one of the following backend features:
-* 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.
+| Feature | Implementation | Target backends |
+| :--- | :--- | :--- |
+| serial - [default] | Serial formulas | `u32`
`u64` |
+| simd_backend | [Parallel][parallel_doc], using Advanced Vector Extensions | `avx2`
`avx512ifma` |
+| fiat_backend | Formally verified field arithmetic from [fiat-crypto] | `fiat_u32`
`fiat_u64` |
-### 4.x (current alpha)
+## Target backends
-The `4.x` series has an API largely unchanged from `3.x`, with a breaking change
-to update the `rand` dependency crates.
+Target backend selection via `serial` and `fiat_backend` features is automatic based on the build target.
+E.g., building with the serial backend on a 64-bit machine the `u64` backend is automatically chosen.
+And with the `fiat_backend` feature, the `fiat_u64` backend is automatically chosen.
-It also requires including a new trait,
-`use curve25519_dalek::traits::BasepointTable`, whenever using
-`EdwardsBasepointTable` or `RistrettoBasepointTable`.
-
-Backend selection has also been updated to be more automatic. See below.
-
-# 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);
-* a `fiat` backend using formally verified field arithmetic from [fiat-crypto];
-
-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.
-
-## Backend selection
-
-Backend selection is done automatically. E.g., if you're compiling on a
-64-bit machine, then the `u64` backend is automatically chosen. And
-if the `fiat_backend` feature is set, then the fiat `u64` backend is
-chosen.
-
-If you need a `u32` backend on a `u64` machine, then simple
-cross-compiling will work on an x86-64 Linux machine:
+If a 32-bit backend is needed on an x86-64 Linux machine then cross-compiling will work:
* `sudo apt install gcc-multilib` (or whatever package manager you use)
* `rustup target add i686-unknown-linux-gnu`
* `cargo build --target i686-unknown-linux-gnu`
-# Minimum Supported Rust Version
+## Advanced Vector Extensions (AVX)
-This crate requires Rust 1.56.1 at a minimum. 3.x releases of this crate supported an MSRV of 1.41.
+Selection within `simd_backend` is manual by using `RUSTFLAGS` as below:
-In the future, MSRV changes will be accompanied by a minor version bump.
+| Target feature | `RUSTFLAGS` Environment variable value |
+| :--- | :--- |
+| avx2 | `-C target_feature=+avx2` |
+| avx512ifma | `-C target_feature=+avx512ifma` |
+
+This also requires using nightly e.g. by `cargo +nightly build` to build.
+
+# Documentation
+
+The semver-stable, public-facing `curve25519-dalek` API is documented [here][docs].
+
+## Building Docs Locally
+
+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
+```
+for regular docs, and
+```sh
+make doc-internal
+```
+for docs that include private items.
+
+# Maintenance Policies
+
+All on-by-default features of this library are covered by
+[semantic versioning][semver] (SemVer). SemVer exemptions are outlined below
+for MSRV and public API.
+
+## Minimum Supported Rust Version
+
+| Releases | MSRV |
+| :--- | :--- |
+| 4.x | 1.56.1 |
+| 3.x | 1.41.0 |
+
+From 4.x and on, MSRV changes will be accompanied by a minor version bump.
+
+## Public API SemVer Exemptions
+
+Breaking changes to SemVer exempted components affecting the public API will be accompanied by
+_some_ version bump. Below are the specific policies:
+
+| Releases | Public API Component(s) | Policy |
+| :--- | :--- | :--- |
+| 4.x | Dependencies `digest` and `rand_core` | Minor SemVer bump |
# Safety
@@ -170,10 +188,10 @@ compiled with appropriate `target_feature`s, so this cannot occur.
Benchmarks are run using [`criterion.rs`][criterion]:
```sh
-cargo bench --no-default-features
+cargo bench --features "alloc"
# Uses avx2 or ifma only if compiled for an appropriate target.
export RUSTFLAGS="-C target_cpu=native"
-cargo +nightly bench --no-default-features --features simd_backend
+cargo +nightly bench --features "alloc simd_backend"
```
Performance is a secondary goal behind correctness, safety, and
@@ -235,14 +253,16 @@ The formally verified `fiat_backend` integrates Rust code generated by the
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
+Pratyush Mishra, Michael Rosenberg, @pinkforest, and countless others for their
contributions.
[ed25519-dalek]: https://github.com/dalek-cryptography/ed25519-dalek
[x25519-dalek]: https://github.com/dalek-cryptography/x25519-dalek
+[docs]: https://docs.rs/curve25519-dalek/
[contributing]: https://github.com/dalek-cryptography/curve25519-dalek/blob/master/CONTRIBUTING.md
-[docs-external]: https://docs.rs/curve25519-dalek
[criterion]: https://github.com/japaric/criterion.rs
[parallel_doc]: https://docs.rs/curve25519-dalek/latest/curve25519_dalek/backend/vector/index.html
[subtle_doc]: https://docs.rs/subtle
[fiat-crypto]: https://github.com/mit-plv/fiat-crypto
+[semver]: https://semver.org/spec/v2.0.0.html
+[rngcorestd]: https://github.com/rust-random/rand/tree/7aa25d577e2df84a5156f824077bb7f6bdf28d97/rand_core#crate-features