mirror of
https://github.com/saymrwulf/risc0-curve25519-dalek-source.git
synced 2026-09-04 20:03:40 +00:00
Updates to README (#453)
* Restructure README and CHANGELOG * Explain semver policy * Specify feature flags and backends more explicitly * Remove nightly from the CI bc that didn't belong there * Add @pinkforest to thankyou list Co-authored-by: pinkforest <36498018+pinkforest@users.noreply.github.com>
This commit is contained in:
Michael Rosenberg
Michael Rosenberg
parent
1e490bd001
commit
f5dada3834
4 changed files with 127 additions and 88 deletions
2
.github/workflows/rust.yml
vendored
2
.github/workflows/rust.yml
vendored
|
|
@ -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
|
||||
|
|
|
|||
30
CHANGELOG.md
30
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
|
||||
|
|
|
|||
|
|
@ -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"]
|
||||
|
|
|
|||
180
README.md
180
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)
|
||||
|
||||
<p style="float: right">
|
||||
<p align="center">
|
||||
<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>
|
||||
|
||||
|
|
@ -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` <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`.
|
||||
|
||||
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
|
||||
|
|
|
|||
Loading…
Reference in a new issue