[][src]Crate x25519_dalek

x25519-dalek

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

This crate provides two levels of API: a bare byte-oriented x25519 function which matches the function specified in RFC7748, as well as a higher-level Rust API for ephemeral Diffie-Hellman.

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 Diffie-Hellman 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 EphemeralPublic::from() to produce her secret and public keys:

extern crate x25519_dalek;
extern crate rand_os;

use x25519_dalek::EphemeralPublic;
use x25519_dalek::EphemeralSecret;
use rand_os::OsRng;

let mut alice_csprng = OsRng::new().unwrap();
let     alice_secret = EphemeralSecret::new(&mut alice_csprng);
let     alice_public = EphemeralPublic::from(&alice_secret);

Bob does the same:

This example is not tested
let mut bob_csprng = OsRng::new().unwrap();
let     bob_secret = EphemeralSecret::new(&mut bob_csprng);
let     bob_public = EphemeralPublic::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:

This example is not tested
use x25519_dalek::EphemeralPublic;
use x25519_dalek::EphemeralSecret;

let shared_secret = EphemeralSecret::diffie_hellman(alice_secret, &bob_public);

Similarly, Bob computes the same shared secret by doing:

This example is not tested
let shared_secret = EphemeralSecret::diffie_hellman(bob_secret, &alice_public);

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 authenticated-encryption cipher.

Installation

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

[dependencies.x25519-dalek]
version = "^0.4"

Documentation

Documentation is available here.

Note

This code matches the RFC7748 test vectors. The elliptic curve operations are provided by curve25519-dalek, which makes a best-effort attempt to prevent software side-channels.

"Secret Messages" cover image and zine copyright © Amy Wibowo (@sailorhg)

Note that docs will only build on nightly Rust until feature(external_doc) is stabilized.

Structs

EphemeralPublic

A DH ephemeral public key.

EphemeralSecret

A DH ephemeral secret key.

SharedSecret

A DH SharedSecret

Constants

X25519_BASEPOINT_BYTES

The X25519 basepoint, for use with the bare, byte-oriented x25519 function. This is provided for people who cannot use the typed ephemeral DH API for some reason.

Functions

x25519

The bare, byte-oriented x25519 function, exactly as specified in RFC7748.