mirror of
https://github.com/saymrwulf/anza-cryptography-source.git
synced 2026-09-04 20:24:04 +00:00
144 lines
4.5 KiB
Markdown
144 lines
4.5 KiB
Markdown
# curve25519 (curve25519-sol)
|
||
|
||
**A pure-Rust implementation of group operations on Ristretto and Curve25519, forked from
|
||
[curve25519-dalek] with HEEA scalar decomposition and a reduced backend set.**
|
||
|
||
> For the original curve25519-dalek documentation see [README_dalek.md](README_dalek.md).
|
||
|
||
This crate is part of the [curve25519-sol](../README.md) workspace.
|
||
|
||
---
|
||
|
||
## Changes from curve25519-dalek
|
||
|
||
### HEEA Scalar Decomposition
|
||
|
||
A new `HEEADecomposition` trait and implementation have been added in:
|
||
|
||
- [`src/scalar/heea.rs`](src/scalar/heea.rs) – `curve25519_heea_vartime`, the core
|
||
half-extended Euclidean algorithm
|
||
- [`src/traits.rs`](src/traits.rs) – `HEEADecomposition` trait (`heea_decompose`)
|
||
- [`src/backend/serial/scalar_mul/vartime_triple_base.rs`](src/backend/serial/scalar_mul/vartime_triple_base.rs) –
|
||
`mul_128_128_256`, a four-variable MSM optimised for two 128-bit and one 256-bit scalar
|
||
|
||
Given a 256-bit hash scalar `h`, `heea_decompose` returns `(ρ, τ, flip_h)` such that:
|
||
|
||
```text
|
||
ρ ≡ ±τ·h (mod ℓ) // ρ and τ are both ≤ 128 bits
|
||
```
|
||
|
||
This allows verification of `sB = R + hA` to be rewritten as a 4-point MSM over ~128-bit
|
||
scalars, reducing the number of point doublings required and yielding roughly **~15% faster**
|
||
verification in practice.
|
||
|
||
See the [TCHES 2025 paper] for the full algorithm description.
|
||
|
||
### Reduced Backends
|
||
|
||
Only the following backends are maintained in this fork:
|
||
|
||
| Backend | Selection | Notes |
|
||
|---|---|---|
|
||
| `serial` | Automatic fallback | Pure Rust, 64-bit word size on 64-bit targets |
|
||
| `simd` / AVX2 | Runtime on x86-64 | Vectorised 4-wide field arithmetic |
|
||
| CUDA | Opt-in (`curve25519-cuda` crate) | GPU MSM via SPPARK/BLST |
|
||
|
||
The `fiat` (formally-verified fiat-crypto) and `unstable_avx512` backends present in upstream
|
||
have been removed.
|
||
|
||
---
|
||
|
||
## Use
|
||
|
||
```toml
|
||
curve25519-sol = { git = "https://github.com/zz-sol/ed25519-sol" }
|
||
```
|
||
|
||
### HEEA decomposition example
|
||
|
||
```rust,ignore
|
||
use curve25519::traits::HEEADecomposition;
|
||
use curve25519::scalar::Scalar;
|
||
use sha2::{Sha512, Digest};
|
||
|
||
// h is a typical 256-bit hash scalar
|
||
let h = Scalar::from_hash(Sha512::new().chain_update(b"some message"));
|
||
|
||
// Decompose into two ~128-bit scalars
|
||
let (rho, tau, flip_h) = h.heea_decompose();
|
||
// rho ≡ ±tau·h (mod ℓ)
|
||
```
|
||
|
||
---
|
||
|
||
## Feature Flags
|
||
|
||
The feature flags are inherited from upstream with no additions:
|
||
|
||
| Feature | Default? | Description |
|
||
|---|:---:|---|
|
||
| `alloc` | ✓ | Multiscalar multiplication, batch inversion, batch compress. |
|
||
| `zeroize` | ✓ | `Zeroize` for all scalar and point types. |
|
||
| `precomputed-tables` | ✓ | Precomputed basepoint tables (~400 KB, ~4× faster basepoint mul). |
|
||
| `rand_core` | | `Scalar::random`, `RistrettoPoint::random`. |
|
||
| `digest` | | Hash-to-curve and `Scalar::from_hash`. |
|
||
| `serde` | | Serialization for all point and scalar types. |
|
||
| `legacy_compatibility` | | `Scalar::from_bits` (broken arithmetic, use only if required). |
|
||
| `group` | | `group` and `ff` crate trait impls. |
|
||
| `group-bits` | | `ff::PrimeFieldBits` for `Scalar`. |
|
||
| `lizard` | | Bytestring-to-Ristretto-point injection. |
|
||
|
||
---
|
||
|
||
## Backends
|
||
|
||
### Serial (default)
|
||
|
||
Pure-Rust, available on all targets. 64-bit arithmetic on 64-bit platforms.
|
||
|
||
### AVX2 (automatic on x86-64)
|
||
|
||
Runtime CPU-feature detection via `cpufeatures`. 4-wide vectorised field elements in
|
||
radix-25.5 representation. Automatically selected when the CPU supports AVX2; falls through to
|
||
`serial` otherwise.
|
||
|
||
To hard-code AVX2 at compile time:
|
||
|
||
```sh
|
||
RUSTFLAGS='-C target-feature=+avx2' cargo build --release
|
||
```
|
||
|
||
### CUDA (opt-in)
|
||
|
||
See the [`curve25519-cuda`](../curve25519-cuda) crate. Provides GPU-accelerated
|
||
multi-scalar multiplication using the [SPPARK] library.
|
||
|
||
---
|
||
|
||
## Safety
|
||
|
||
All point types enforce validity invariants at the type level (no invalid `EdwardsPoint` can be
|
||
constructed). All secret-operand operations use constant-time logic via the [`subtle`] crate.
|
||
Variable-time functions are explicitly marked `vartime`.
|
||
|
||
The SIMD backend uses `unsafe` internally for SIMD intrinsics, guarded by runtime CPU-feature
|
||
checks.
|
||
|
||
---
|
||
|
||
## MSRV
|
||
|
||
Rust **1.85.0** (Edition 2024).
|
||
|
||
---
|
||
|
||
## References
|
||
|
||
- [TCHES 2025 paper] – _Accelerating EdDSA Signature Verification with Faster Scalar Size Halving_
|
||
- [curve25519-dalek] – upstream library (isis lovecruft, Henry de Valence)
|
||
- [Original curve25519-dalek README](README_dalek.md)
|
||
|
||
[TCHES 2025 paper]: https://tches.iacr.org/index.php/TCHES/article/view/11971
|
||
[curve25519-dalek]: https://github.com/dalek-cryptography/curve25519-dalek
|
||
[SPPARK]: https://github.com/supranational/sppark
|
||
[subtle]: https://docs.rs/subtle
|