Public interface of curve25519-dalek

Summary

This library provides implementations for a field of scalars, a group of elliptic curve points, and scalar multiplication operations over these mathematical structures. The set of scalars and the group are large enough to offer cryptographic security, and therefore require specialized efficient implementations.

In addition, the library allows bitstring conversions to and from these mathematical structures, as well as conversions between equivalent forms of the elliptic curve group. Each form (Edwards, Montgomery, Ristretto) offers specific computational advantages for cryptographic operations.

Applications

  • Scalars can be used in protocols to store private keys and cryptographically secure random numbers.
  • Elliptic curve points can be used to represent public keys or encode private data in a secure way.
  • Scalar multiplication is used for multiple cryptographic operations, such as encoding, decoding, shared key generation, zero-knowledge proofs, private-key signing and verification.

1 Specifications

Scalar: Integers modulo a large prime number
  • Modular arithmetic: addition, subtraction, multiplication, negation
  • Inversion for nonzero values
References: Modular arithmetic · RFC 8032
Edwards: Elements of Edwards curve25519
  • Group operations: addition, subtraction, negation
  • Scalar multiplication
References: Edwards curve · RFC 8032 · ePrint 2008/013
Montgomery: Montgomery form of Edwards curve25519
  • Allows constant-time scalar multiplication (Montgomery ladder)
  • Convertible to/from Edwards form via standard maps
References: Montgomery · Ladder · RFC 7748 · ePrint 2017/212
Ristretto: Prime-order subgroup of Edwards curve25519
  • Group operations: addition, subtraction, negation
  • Scalar multiplication
References: Ristretto Group · RFC 9496 · ePrint 2015/673
Edwards Group Arithmetic Ristretto Montgomery Group Arithmetic Scalar Modular Arithmetic Equivalence Mapping Scalar Multiplication Scalar Multiplication

2 Implementations

Scalar implements:
Scalar specification 5 functions
Function
add(s₁, s₂)
sub(s₁, s₂)
mul(s₁, s₂)
neg(s)
invert(s)
Parsing and serialization 3 functions
Function
from_canonical_bytes(b)
from_bits(b)
to_bytes / as_bytes
Input conversions and reduction 3 functions
Function
from(x: u64)
from_bytes_mod_order(b)
from_bytes_mod_order_wide(b)
Hashing and key-byte preparation helpers 3 functions
Function
from_hash(h)
random
clamp_integer(b)
EdwardsPoint implements:
Edwards specification 6 functions
Function
add(P, Q)
sub(P, Q)
neg(P)
mul_by_cofactor(P)
is_small_order(P)
is_identity(P)
Scalar-multiplication variants 4 functions
Function
mul_base(s)
vartime_double_scalar_mul_basepoint(a, A, b)
random
mul_base_clamped(b)
Parsing and serialization 5 functions
Function
compress(P)
AffinePoint::compress(P)
decompress(b)
to_bytes / as_bytes
from_slice(b)
Conversions Edwards $\leftrightarrow$ Montgomery 2 functions
Function
to_montgomery(P)
AffinePoint::to_edwards(P)
MontgomeryPoint implements:
Montgomery ladder multiplication 1 function
Function
mul_clamped(P, b)
Conversion to Edwards form 1 function
Function
to_edwards(P, sign)
Parsing and serialization 1 function
Function
to_bytes / as_bytes
RistrettoPoint implements:
Ristretto specification 12 functions
Function
add(P, Q)
sub(P, Q)
neg(P)
mul(P, s)
conditional_select(a, b, c)
basepoint_mul(T, s)
mul_base(s)
vartime_double_scalar_mul_basepoint(a, A, b)
double_and_compress_batch(Ps)
RistrettoBasepointTable::create(P)
RistrettoBasepointTable::basepoint
vartime_multiscalar_mul(ss, Ps)
Parsing and serialization 4 functions
Function
compress(P)
decompress(b)
to_bytes / as_bytes
from_slice(b)
Equality checks and identity 2 functions
Function
ct_eq(c₁, c₂)
identity()
Maps into the prime-order subgroup 3 functions
Function
from_hash(h)
from_uniform_bytes(b)
random
EdwardsPoint X, Y, Z, T: FieldElement Group Arithmetic RistrettoPoint point: EdwardsPoint MontgomeryPoint bytes: [u8; 32] Montgomery Ladder Scalar bytes: [u8; 32] Modular Arithmetic Bytes compress · to_bytes · as_bytes · from_slice Conversion Functions Scalar Multiplication Scalar Multiplication Conversion Functions

3 Call Paths & Libsignal Protocol Integration

The Libsignal protocol stack reaches curve25519-dalek via three paths. 51 (TBD) functions are called directly; 7 (TBD) more are reached indirectly through the x25519-dalek and ed25519-dalek wrapper crates. Each protocol module consumes a distinct subset of operations.

PROTOCOL STACK core / protocol XEdDSA, Ed25519 keytrans VRF proofs zkgroup credentials poksho proof system zkcredential endorsements x25519-dalek PublicKey, StaticSecret, diffie_hellman() ed25519-dalek VerifyingKey, Signature CURVE25519-DALEK montgomery.rs 4 fns (1D + 3I) edwards.rs 14 fns (12D + 2I) ristretto.rs 21 fns (20D + 1I) scalar.rs 15 fns (14D + 1I) lizard.rs 2 fns traits.rs: 2 fns Curve25519 / edwards25519: $-x^2 + y^2 = 1 + dx^2y^2$ over $\mathbb{F}_p$ p = 2^255 - 19 · cofactor h = 8 · group order L = 2^252 + 277423... DIRECT (51 fns) 3 fns 2 fns 1 fn 1 fn Direct (51) Indirect via wrapper (7)
Source FileDirectIndirectTotalPrimary ProtocolDominant Consumer
montgomery.rs134 X25519 XEdDSA x25519-dalek (DH), core (XEdDSA verify)
edwards.rs12214 Ed25519 VRF keytrans/vrf.rs, core/curve25519.rs
ristretto.rs20121 zkgroup zkgroup, zkcredential, poksho, svrb
scalar.rs14115 Ed25519 zkgroup universal (all crates)
lizard_ristretto.rs202 zkgroup uid_struct.rs, uid_encryption.rs
traits.rs202 VRF zkgroup keytrans/vrf.rs, endorsements.rs
Total51758
Ed25519   Signatures & Identity Keys core / protocol

Ed25519 signatures are the foundation of Signal’s identity and message authentication. The signing key is a Scalar (clamped); the verification key is a compressed Edwards point.

OperationTypeKey Call Sites
Sign (scalar mul)Scalar × Edwardsed25519-dalek → mul_base_clamped, from_bits
Verify ($[a]A + [b]B$)Edwardsvartime_double_scalar_mul_basepoint
Hash-to-scalarScalarfrom_bytes_mod_order_wide, from_hash
Key encodingEdwardscompress, decompress, as_bytes, from_slice
X25519   Diffie-Hellman Key Agreement x25519-dalek

X25519 performs Diffie-Hellman on the Montgomery curve via the constant-time ladder. Private keys are clamped scalars; public keys are $u$-coordinates.

OperationTypeKey Call Sites
DH ($[s]P$)Montgomeryx25519-dalek → mul_clamped
ClampingScalarclamp_integer
Public key extractMontgomeryas_bytes, to_bytes
x25519-dalek wrapper
pub fn diffie_hellman(secret: &StaticSecret, public: &PublicKey) -> SharedSecret {
    // clamp_integer → MontgomeryPoint::mul_clamped → as_bytes
}
XEdDSA   Signatures from X25519 Keys core/curve25519.rs

XEdDSA allows signing with an X25519 private key by converting the Montgomery public key back to Edwards form. Used in Signal’s sealed sender and key verification.

OperationTypeKey Call Sites
Curve conversionMontgomery → Edwardsto_edwards(sign)
Signature verifyEdwardsvartime_double_scalar_mul_basepoint
Cofactor checkEdwardsmul_by_cofactor, is_small_order, is_identity
zkgroup   Anonymous Credentials zkgroup / zkcredential / poksho / svrb

zkgroup uses the Ristretto group for anonymous credential issuance, presentation, and verification. Prime order eliminates cofactor issues in zero-knowledge proofs.

OperationTypeKey Call Sites
Pedersen commitRistrettomul, add, sub, mul_base
Credential MACRistrettobasepoint_mul, from_hash
Batch verifyRistrettovartime_multiscalar_mul, double_and_compress_batch
UID encodingRistrettolizard_encode, lizard_decode
Wire formatRistrettocompress, decompress, as_bytes, from_slice, ct_eq
Point constructionRistrettofrom_uniform_bytes, random, RistrettoBasepointTable::create
VRF   Verifiable Random Functions keytrans/vrf.rs

Key Transparency uses VRF proofs over both Edwards and Ristretto points for verifiable pseudorandom evaluation.

OperationTypeKey Call Sites
VRF evaluateEdwards & Ristrettomul_base, vartime_double_scalar_mul_basepoint
Multi-scalarRistrettovartime_multiscalar_mul
Scalar opsScalarinvert, mul, from_bytes_mod_order_wide