13 releases (3 stable)
1.1.0  Aug 31, 2020 

0.6.0  Nov 26, 2019 
0.5.2  Mar 29, 2019 
0.3.0  Jul 27, 2018 
0.1.0 

#9 in Cryptography
57,073 downloads per month
Used in 175 crates
(51 directly)
85KB
269 lines
x25519dalek
A pureRust implementation of x25519 elliptic curve DiffieHellman key exchange, with curve operations provided by curve25519dalek.
This crate provides two levels of API: a bare byteoriented x25519
function which matches the function specified in RFC7748, as
well as a higherlevel Rust API for static and ephemeral DiffieHellman.
Examples
Alice and Bob are two adorable kittens who have lost their mittens, and they wish to be able to send secret messages to each other to coordinate finding them, otherwise—if their caretaker cat finds out—they will surely be called naughty kittens and be given no pie!
But the two kittens are quite clever. Even though their paws are still too big and the rest of them is 90% fuzziness, these clever kittens have been studying up on modern public key cryptography and have learned a nifty trick called elliptic curve DiffieHellman key exchange. With the right incantations, the kittens will be able to secretly organise to find their mittens, and then spend the rest of the afternoon nomming some yummy pie!
First, Alice uses EphemeralSecret::new()
and then
PublicKey::from()
to produce her secret and public keys:
use rand_core::OsRng;
use x25519_dalek::{EphemeralSecret, PublicKey};
let alice_secret = EphemeralSecret::new(OsRng);
let alice_public = PublicKey::from(&alice_secret);
Bob does the same:
# use rand_core::OsRng;
# use x25519_dalek::{EphemeralSecret, PublicKey};
let bob_secret = EphemeralSecret::new(OsRng);
let bob_public = PublicKey::from(&bob_secret);
Alice meows across the room, telling alice_public
to Bob, and Bob
loudly meows bob_public
back to Alice. Alice now computes her
shared 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 their meows, for example, by using it to generate a key and nonce for an authenticatedencryption cipher.
This example used the ephemeral DH API, which ensures that secret keys cannot be reused; Alice and Bob could instead use the static DH API and load a longterm secret key.
Installation
To install, add the following to your project's Cargo.toml
:
[dependencies]
x25519dalek = "1.1"
Documentation
Documentation is available here.
Note
This code matches the RFC7748 test vectors.
The elliptic curve
operations are provided by curve25519dalek
, which makes a besteffort
attempt to prevent software sidechannels.
"Secret Messages" cover image and zine copyright © Amy Wibowo (@sailorhg)
See also
 crypto_box: pure Rust publickey authenticated encryption compatible with
the NaCl family of encryption libraries (libsodium, TweetNaCl) which uses
x25519dalek
for key agreement
Dependencies
~2.5MB
~57K SLoC