Crate dalek_test_curve_docs
source ·Expand description
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
and 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. In addition, the unstable internal implementation
details are documented here.
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
make doc
make doc-internal
Use
To import curve25519-dalek
, add the following to the dependencies section of
your project’s Cargo.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 the2.x
-seriesserde
implementation is used withserde-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 ofstd
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 andu64
products; - a
u64
backend using serial formulas andu128
products; - an
avx2
backend using parallel formulas andavx2
instructions (sets speed records); - an
ifma
backend using parallel formulas andifma
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.
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
:
cargo bench --no-default-features
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.
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, 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 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.
Re-exports
pub use digest;