Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Updates to README #453

Merged
merged 21 commits into from
Dec 9, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/rust.yml
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,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
Expand Down
30 changes: 25 additions & 5 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,20 +5,33 @@ 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
* Include README.md into crate Documentation
* 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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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`
Expand All @@ -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
Expand Down
3 changes: 1 addition & 2 deletions Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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"]
168 changes: 94 additions & 74 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@

# 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://docs.rs/curve25519-dalek) [![](https://travis-ci.org/dalek-cryptography/curve25519-dalek.svg?branch=master)](https://travis-ci.org/dalek-cryptography/curve25519-dalek)
# curve25519-dalek [![](https://img.shields.io/crates/v/curve25519-dalek.svg)](https://crates.io/crates/curve25519-dalek) [![](https://img.shields.io/docsrs/curve25519-dalek)](https://docs.rs/curve25519-dalek) [![Rust](https://github.com/dalek-cryptography/curve25519-dalek/actions/workflows/rust.yml/badge.svg?branch=main)](https://github.com/dalek-cryptography/curve25519-dalek/actions/workflows/rust.yml)

<p style="float: right">
<p align="center">
rozbb marked this conversation as resolved.
Show resolved Hide resolved
<img
width="300px"
alt="dalek-cryptography logo: a dalek with edwards curves as sparkles coming out of its radar-schnozzley blaster thingies"
width="200px"
src="https://cdn.jsdelivr.net/gh/dalek-cryptography/curve25519-dalek/docs/assets/dalek-logo-clear.png"/>
</p>

Expand All @@ -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. |
rozbb marked this conversation as resolved.
Show resolved Hide resolved
| `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. |
rozbb marked this conversation as resolved.
Show resolved Hide resolved
| `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` <br/> `u64` |
| simd_backend | [Parallel][parallel_doc], using Advanced Vector Extensions | `avx2` <br/> `avx512ifma` |
| fiat_backend | Formally verified field arithmetic from [fiat-crypto] | `fiat_u32` <br/> `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`.
If a 32-bit backend is needed on an x86-64 Linux machine then cross-compiling will work:

Backend selection has also been updated to be more automatic. See below.
* `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`

# Backends and Features
## Advanced Vector Extensions (AVX)

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.
Selection within `simd_backend` is manual by using `RUSTFLAGS` as below:

Curve arithmetic is implemented using one of the following backends:
| Target feature | `RUSTFLAGS` Environment variable value |
| :--- | :--- |
| avx2 | `-C target_feature=+avx2` |
| avx512ifma | `-C target_feature=+avx512ifma` |

* 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];
This also requires using nightly e.g. by `cargo +nightly build` to build.

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.
# Documentation

## Backend selection
The semver-stable, public-facing `curve25519-dalek` API is documented [here][docs].

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.
## Building Docs Locally

If you need a `u32` backend on a `u64` machine, then simple
cross-compiling will work on an x86-64 Linux machine:
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.

* `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`
# 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.

# Minimum Supported Rust Version
## Public API SemVer Exemptions

This crate requires Rust 1.56.1 at a minimum. 3.x releases of this crate supported an MSRV of 1.41.
Breaking changes to SemVer exempted components affecting the public API will be accompanied by
_some_ version bump. Below are the specific policies:

In the future, MSRV changes will be accompanied by a minor version bump.
| Releases | Public API Component(s) | Policy |
| :--- | :--- | :--- |
| 4.x | Dependencies `digest` and `rand_core` | Minor SemVer bump |

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I removed the line here about removing exemptions in the future. It wasn't saying much and we don't need to make those promises now imo.

# Safety

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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