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.

A pure-Rust implementation of x25519 elliptic curve Diffie-Hellman key exchange,with curve operations provided bycurve25519-dalek.

This crate provides two levels of API: a bare byte-orientedx25519function which matches the function specified inRFC7748, aswell as a higher-level Rust API for static and ephemeral Diffie-Hellman.

Alice and Bob are two adorable kittens who have lost their mittens, and theywish to be able to send secret messages to each other to coordinate findingthem, otherwise—if their caretaker cat finds out—they will surely be callednaughty kittens and be given no pie!

But the two kittens are quite clever. Even though their paws are still too bigand the rest of them is 90% fuzziness, these clever kittens have been studyingup on modern public key cryptography and have learned a nifty trick calledelliptic curve Diffie-Hellman key exchange. With the right incantations, thekittens will be able to secretly organise to find their mittens, and then spendthe rest of the afternoon nomming some yummy pie!

First, Alice usesEphemeralSecret::random() and thenPublicKey::from() to produce her secret and public keys:

usex25519_dalek::{EphemeralSecret,PublicKey};letalice_secret=EphemeralSecret::random();letalice_public=PublicKey::from(&alice_secret);

Bob does the same:

# use x25519_dalek::{EphemeralSecret, PublicKey};letbob_secret=EphemeralSecret::random();letbob_public=PublicKey::from(&bob_secret);

Alice meows across the room, tellingalice_public to Bob, and Bobloudly meowsbob_public back to Alice. Alice now computes hershared secret with Bob by doing:

#use rand_core::OsRng;#use x25519_dalek::{EphemeralSecret,PublicKey};#let alice_secret =EphemeralSecret::new(OsRng);#let alice_public =PublicKey::from(&alice_secret);#let bob_secret =EphemeralSecret::new(OsRng);#let bob_public =PublicKey::from(&bob_secret);let alice_shared_secret = alice_secret.diffie_hellman(&bob_public);

Similarly, Bob computes a shared secret by doing:

#use rand_core::OsRng;#use x25519_dalek::{EphemeralSecret,PublicKey};#let alice_secret =EphemeralSecret::new(OsRng);#let alice_public =PublicKey::from(&alice_secret);#let bob_secret =EphemeralSecret::new(OsRng);#let bob_public =PublicKey::from(&bob_secret);let bob_shared_secret = bob_secret.diffie_hellman(&alice_public);

These secrets are the same:

#use rand_core::OsRng;#use x25519_dalek::{EphemeralSecret,PublicKey};#let alice_secret =EphemeralSecret::new(OsRng);#let alice_public =PublicKey::from(&alice_secret);#let bob_secret =EphemeralSecret::new(OsRng);#let bob_public =PublicKey::from(&bob_secret);#let alice_shared_secret = alice_secret.diffie_hellman(&bob_public);#let bob_shared_secret = bob_secret.diffie_hellman(&alice_public);assert_eq!(alice_shared_secret.as_bytes(), bob_shared_secret.as_bytes());

Voilà! Alice and Bob can now use their shared secret to encrypt theirmeows, for example, by using it to generate a key and nonce for anauthenticated-encryption cipher.

This example used the ephemeral DH API, which ensures that secret keyscannot be reused; Alice and Bob could instead use the static DH APIand load a long-term secret key.

To install, add the following to your project'sCargo.toml:

[dependencies]x25519-dalek ="2.0.0-rc.3"

Current MSRV is 1.60.

Documentation is availablehere.

Performance is a secondary goal behind correctness, safety, and clarity, but we aim to be competitive with other implementations. To this end, we allow users to choose theirbackend, i.e., the underlying 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).

Further instructions and details regarding backends can be found in thecurve25519-dalek docs.

This code matches theRFC7748 test vectors.The elliptic curveoperations are provided bycurve25519-dalek, which makes a best-effortattempt to prevent software side-channels.

"Secret Messages" cover image andzinecopyright © Amy Wibowo (@sailorhg)

• crypto_box: pure Rust public-key authenticated encryption compatible withthe NaCl family of encryption libraries (libsodium, TweetNaCl) which usesx25519-dalek for key agreement