Repository files navigation

This repo has beenmoved. Please direct all issues and pull requests to the new repo.

This repo will remain here in a read-only state for historical purposes.

Fast and efficient Rust implementation of ed25519 key generation, signing, andverification.

To imported25519-dalek, add the following to the dependencies section ofyour project'sCargo.toml:

ed25519-dalek ="1"

To use the latest prerelease (see changesbelow),use the following line in your project'sCargo.toml:

ed25519-dalek ="2.0.0-rc.3"

This crate is#[no_std] compatible withdefault-features = false.

SeeCHANGELOG.md for a list of changes made in past version of this crate.

• Bump MSRV from 1.41 to 1.60.0
• Bump Rust edition
• Bumpsignature dependency to 2.0
• Makedigest an optional dependency
• Makezeroize an optional dependency
• Makerand_core an optional dependency
• Adoptcurve25519-backend selection over features
• Make all batch verification deterministic removebatch_deterministic (#256)
• RemoveExpandedSecretKey API ((#205)[#205])
• RenameKeypair →SigningKey andPublicKey →VerifyingKey
• Makehazmat feature to expose,ExpandedSecretKey,raw_sign(),raw_sign_prehashed(),raw_verify(), andraw_verify_prehashed()

Documentation is availablehere.

All on-by-default features of this library are covered bysemantic versioning (SemVer).SemVer exemptions are outlined below for MSRV and public API.

From 2.x and on, MSRV changes will be accompanied by a minor version bump.

Breaking changes to SemVer-exempted components affecting the public API will be accompanied by some version bump.

Below are the specific policies:

ed25519-dalek is designed to prevent misuse. Signing is constant-time, all signing keys are zeroed when they go out of scope (unlesszeroize is disabled), detached public keyscannot be used for signing, and extra functions likeVerifyingKey::verify_strict are made available to avoid known gotchas.

Further, this crate has no—and in fact forbids—unsafe code. You can opt in to using some highly optimized unsafe code that resides incurve25519-dalek, though. Seebelow for more information on backend selection.

Performance is a secondary goal behind correctness, safety, and clarity, but weaim to be competitive with other implementations.

Benchmarks are run usingcriterion.rs:

cargo bench --features"batch"# Uses avx2 or ifma only if compiled for an appropriate target.export RUSTFLAGS='-C target_cpu=native'cargo +nightly bench --features"batch"

On an Intel 10700K running at stock comparing between thecurve25519-dalek backends.

If your protocol or application is able to batch signatures for verification,theverify_batch function has greatly improved performance.

As you can see, there's an optimal batch size for each machine, so you'll likelywant to test the benchmarks on your target CPU to discover the best size.

Abackend refers to an implementation of elliptic curve and scalar arithmetic. Different backends have different use cases. For example, if you demand formally verified code, you want to use thefiat backend (as it was generated fromFiat Crypto).

Backend selection details and instructions can be found in thecurve25519-dalek docs.

SeeCONTRIBUTING.md

The standard variants of batch signature verification (i.e. many signatures made with potentially many different public keys over potentially many different messages) is available via thebatch feature. It uses deterministic randomness, i.e., it hashes the inputs (usingmerlin, which handles transcript item separation) and uses the result to generate random coefficients. Batch verification requires allocation, so this won't function in heapless settings.

Thevalidation criteria of a signature scheme are the criteria that signatures and public keys must satisfy in order to be accepted. Unfortunately, Ed25519 has some underspecified parts, leading to different validation criteria across implementations. For a very good overview of this, seeHenry's post.

In this section, we mention some specific details about our validation criteria, and how to navigate them.

A signature scheme is considered to producemalleable signatures if a passive attacker with knowledge of a public keyA, messagem, and valid signatureσ' can produce a distinctσ' such thatσ' is a valid signature ofm with respect toA. A scheme is only malleable if the attacker can do thiswithout knowledge of the private key corresponding toA.

ed25519-dalek is not a malleable signature scheme.

Some other Ed25519 implementations are malleable, though, such aslibsodium withED25519_COMPAT enabled,ed25519-donna,NaCl's ref10 impl, and probably a lot more.If you need to interoperate with such implementations and accept otherwise invalid signatures, you can enable thelegacy_compatibility flag.Do not enablelegacy_compatibility if you don't have to, because it will make your signatures malleable.

Note:CIRCL has no scalar range check at all. We do not have a feature flag for interoperating with the larger set of RFC-disallowed signatures that CIRCL accepts.

Asignature forgery is what it sounds like: it's when an attacker, given a public keyA, creates a signatureσ and messagem such thatσ is a valid signature ofm with respect toA. Since this is the core security definition of any signature scheme, Ed25519 signatures cannot be forged.

However, there's a much looser kind of forgery that Ed25519 permits, which we callweak key forgery. An attacker can produce a special public keyA (which we call aweak public key) and a signatureσ such thatσ is a valid signature ofany messagem, with respect toA, with high probability. This attack is acknowledged in theEd25519 paper, and caused an exploitable bug in the Scuttlebutt protocol (paper, section 7.1). TheVerifyingKey::verify() function permits weak keys.

We provideVerifyingKey::verify_strict (andverify_strict_prehashed) to help users avoid these scenarios. These functions perform an extra check onA, ensuring it's not a weak public key. In addition, we provide theVerifyingKey::is_weak to allow users to perform this check before attempting signature verification.

As mentioned above, weak public keys can be used to produce signatures for unknown messages with high probability. This means that sometimes a weak forgery attempt will fail. In fact, it can fail up to 7/8 of the time. If you callverify() twice on the same failed forgery, it will return an error both times, as expected. However, if you callverify_batch() twice on two distinct otherwise-valid batches, both of which contain the failed forgery, there's a 21% chance that one fails and the other succeeds.

Why is this? It's becauseverify_batch() does not do the weak key testing ofverify_strict(), and it multiplies each verification equation by some random coefficient. If the failed forgery gets multiplied by 8, then the weak key (which is a low-order point) becomes 0, and the verification equation on the attempted forgery will succeed.

Sinceverify_batch() is intended to be high-throughput, we think it's best not to put weak key checks in it. If you want to prevent weird behavior due to weak public keys in your batches, you should callVerifyingKey::is_weak on the inputs in advance.