# 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) **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 = "4.0.0-pre.2" ``` ## Major Version API Changes See `CHANGELOG.md` for more details. ### 2.x 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. ### 3.x (current stable) 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. ### 4.x (current alpha) The `4.x` series has an API largely unchanged from `3.x`, with a breaking change to update the `rand` dependency crates. 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: * `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 This crate requires Rust 1.56.1 at a minimum. 3.x releases of this crate supported an MSRV of 1.41. In the future, MSRV changes will be accompanied by a minor version 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 compiled with appropriate `target_feature`s, so this cannot occur. # Performance Benchmarks are run using [`criterion.rs`][criterion]: ```sh cargo bench --no-default-features # 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 ``` 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** `main`. # 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, 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/ [fiat-crypto]: https://github.com/mit-plv/fiat-crypto