mirror of
https://github.com/saymrwulf/xous-core.git
synced 2026-11-21 09:14:34 +00:00
The *only* change is to make fiat-crypto a non-optional dependency. For some reason the .cargo/config.toml only half-activates the feature, in that in the .rs code files the feature is included but in the Cargo.toml file the dependency is, for some reason, not enabled.
325 lines
16 KiB
Markdown
325 lines
16 KiB
Markdown
|
|
# curve25519-dalek [](https://crates.io/crates/curve25519-dalek) [](https://docs.rs/curve25519-dalek) [](https://github.com/dalek-cryptography/curve25519-dalek/actions/workflows/curve25519-dalek.yml)
|
|
|
|
<p align="center">
|
|
<img
|
|
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>
|
|
|
|
**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.
|
|
|
|
# Use
|
|
|
|
## Stable
|
|
|
|
To import `curve25519-dalek`, add the following to the dependencies section of
|
|
your project's `Cargo.toml`:
|
|
```toml
|
|
curve25519-dalek = "4"
|
|
```
|
|
|
|
If opting into [SemVer-exempted features](#public-api-semver-exemptions) a range
|
|
can be used to scope the tested compatible version range e.g.:
|
|
```toml
|
|
curve25519-dalek = ">= 4.0, < 4.2"
|
|
```
|
|
|
|
## Feature Flags
|
|
|
|
| Feature | Default? | Description |
|
|
| :--- | :---: | :--- |
|
|
| `alloc` | ✓ | Enables Edwards and Ristretto multiscalar multiplication, batch scalar inversion, and batch Ristretto double-and-compress. Also enables `zeroize`. |
|
|
| `zeroize` | ✓ | Enables [`Zeroize`][zeroize-trait] for all scalar and curve point types. |
|
|
| `precomputed-tables` | ✓ | Includes precomputed basepoint multiplication tables. This speeds up `EdwardsPoint::mul_base` and `RistrettoPoint::mul_base` by ~4x, at the cost of ~30KB added to the code size. |
|
|
| `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. |
|
|
| `legacy_compatibility`| | Enables `Scalar::from_bits`, which allows the user to build unreduced scalars whose arithmetic is broken. Do not use this unless you know what you're doing. |
|
|
| `group` | | Enables external `group` and `ff` crate traits. |
|
|
| `group-bits` | | Enables `group` and impls `ff::PrimeFieldBits` for `Scalar`. |
|
|
|
|
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
|
|
|
|
Breaking changes for each major version release can be found in
|
|
[`CHANGELOG.md`](CHANGELOG.md), under the "Breaking changes" subheader. The
|
|
latest breaking changes in high level are below:
|
|
|
|
### Breaking changes in 4.0.0
|
|
|
|
* Update the MSRV from 1.41 to 1.60
|
|
* Provide SemVer policy
|
|
* Make `digest` and `rand_core` optional features
|
|
* Remove `std` and `nightly` features
|
|
* Replace backend selection - See [CHANGELOG.md](CHANGELOG.md) and [backends](#backends)
|
|
* Replace methods `Scalar::{zero, one}` with constants `Scalar::{ZERO, ONE}`
|
|
* `Scalar::from_canonical_bytes` now returns `CtOption`
|
|
* `Scalar::is_canonical` now returns `Choice`
|
|
* Remove `Scalar::from_bytes_clamped` and `Scalar::reduce`
|
|
* Deprecate and feature-gate `Scalar::from_bits` behind `legacy_compatibility`
|
|
* 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`
|
|
|
|
This release also does a lot of dependency updates and relaxations to unblock upstream build issues.
|
|
|
|
# Backends
|
|
|
|
Curve arithmetic is implemented and used by one of the following backends:
|
|
|
|
| Backend | Selection | Implementation | Bits / Word sizes |
|
|
| :--- | :--- | :--- | :--- |
|
|
| `serial` | Automatic | An optimized, non-parllel implementation | `32` and `64` |
|
|
| `fiat` | Manual | Formally verified field arithmetic from [fiat-crypto] | `32` and `64` |
|
|
| `simd` | Automatic | Intel AVX2 accelerated backend | `64` only |
|
|
| `unstable_avx512` | Manual | Intel AVX512 IFMA accelerated backend (requires nightly) | `64` only |
|
|
|
|
At runtime, `curve25519-dalek` selects an arithmetic backend from the set of backends it was compiled to support. For Intel x86-64 targets, unless otherwise specified, it will build itself with `simd` support, and default to `serial` at runtime if the appropriate CPU features aren't detected. See [SIMD backend] for more details.
|
|
|
|
In the future, `simd` backend may be extended to cover more instruction sets. This change will be non-breaking as this is considered an implementation detail.
|
|
|
|
## Manual Backend Override
|
|
|
|
You can force the crate to compile with specific backend support, e.g., `serial` for x86-64 targets to save code size, or `fiat` to force the runtime to use verified code. To do this, set the environment variable:
|
|
```sh
|
|
RUSTFLAGS='--cfg curve25519_dalek_backend="BACKEND"'
|
|
```
|
|
Equivalently, you can write to
|
|
`~/.cargo/config`:
|
|
```toml
|
|
[build]
|
|
rustflags = ['--cfg=curve25519_dalek_backend="BACKEND"']
|
|
```
|
|
More info [here](https://doc.rust-lang.org/cargo/reference/config.html#buildrustflags).
|
|
|
|
Note for contributors: The target backends are not entirely independent of each
|
|
other. The [SIMD backend] directly depends on parts of the serial backend to
|
|
function.
|
|
|
|
## Bits / Word size
|
|
|
|
`curve25519-dalek` will automatically choose the word size for the `fiat` and
|
|
`serial` backends, based on the build target.
|
|
For example, building for a 64-bit machine, the default 64 bit word size is
|
|
automatically chosen when either the `serial` or `fiat` backend is selected.
|
|
|
|
In some targets it might be required to override the word size for better
|
|
performance.
|
|
Backend word size can be overridden for `serial` and `fiat` by setting the
|
|
environment variable:
|
|
```sh
|
|
RUSTFLAGS='--cfg curve25519_dalek_bits="SIZE"'
|
|
```
|
|
`SIZE` is `32` or `64`. As in the above section, this can also be placed
|
|
in `~/.cargo/config`.
|
|
|
|
Note: The [SIMD backend] requires a word size of 64 bits. Attempting to set bits=32 and backend=`simd` will yield a compile error.
|
|
|
|
### Cross-compilation
|
|
|
|
Because backend selection is done by target, cross-compiling will select the correct word size automatically. For example, if a x86-64 Linux machine runs the following commands, `curve25519-dalek` will be compiled with the 32-bit `serial` backend.
|
|
```console
|
|
$ 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
|
|
```
|
|
|
|
## SIMD backend
|
|
|
|
When the `simd` backend is selected, the AVX2 or `serial` implementation is selected automatically at runtime, depending on the currently available CPU features. Similarly, when the `unstable_avx512` backend is selected, the AVX512 implementation is selected automatically at runtime if available, or else selection falls through to the aforementioned `simd` backend logic.
|
|
|
|
For a given CPU feature, you can also specify an appropriate `-C target_feature` to build a binary which assumes the required SIMD instructions are always available. Don't do this if you don't have a good reason.
|
|
|
|
| Backend | `RUSTFLAGS` | Requires nightly? |
|
|
| :--- | :--- | :--- |
|
|
| AVX2 | `-C target_feature=+avx2` | no |
|
|
| AVX512 | `-C target_feature=+avx512ifma,+avx512vl` | yes |
|
|
|
|
To reiterate, the `simd` backend will NOT use AVX512 code under any circumstance. The only way to enable AVX512 currently is to select the `unstable_avx512` backend and use a nightly compiler.
|
|
|
|
# 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.60.0 |
|
|
| 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 `group`, `digest` and `rand_core` | Minor SemVer bump |
|
|
|
|
# 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
|
|
invoked when the appropriate CPU features are detected at runtime, or
|
|
when the whole program is compiled with the appropriate `target_feature`s.
|
|
|
|
# Performance
|
|
|
|
Benchmarks are run using [`criterion.rs`][criterion]:
|
|
|
|
```sh
|
|
cargo bench --features "rand_core"
|
|
export RUSTFLAGS='-C target_cpu=native'
|
|
cargo +nightly bench --features "rand_core"
|
|
```
|
|
|
|
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].
|
|
|
|
# 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 `fiat_backend` integrates Rust code generated by the
|
|
[Fiat Crypto project](https://github.com/mit-plv/fiat-crypto) and was
|
|
contributed by François Garillot.
|
|
|
|
Thanks also to Ashley Hauck, Lucas Salibian, Manish Goregaokar, Jack Grigg,
|
|
Pratyush Mishra, Michael Rosenberg, @pinkforest, and countless others for their
|
|
contributions.
|
|
|
|
[ed25519-dalek]: https://github.com/dalek-cryptography/curve25519-dalek/tree/main/ed25519-dalek
|
|
[x25519-dalek]: https://github.com/dalek-cryptography/curve25519-dalek/tree/main/x25519-dalek
|
|
[docs]: https://docs.rs/curve25519-dalek/
|
|
[contributing]: https://github.com/dalek-cryptography/curve25519-dalek/blob/master/CONTRIBUTING.md
|
|
[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
|
|
[zeroize-trait]: https://docs.rs/zeroize/latest/zeroize/trait.Zeroize.html
|
|
[SIMD backend]: #simd-backend
|