test_x25519_dalek/lib.rs
1// -*- mode: rust; -*-
2//
3// This file is part of x25519-dalek.
4// Copyright (c) 2017-2021 isis lovecruft
5// Copyright (c) 2019-2021 DebugSteven
6// See LICENSE for licensing information.
7//
8// Authors:
9// - isis agora lovecruft <isis@patternsinthevoid.net>
10// - DebugSteven <debugsteven@gmail.com>
11
12// Refuse to compile if documentation is missing, but only on nightly.
13//
14// This means that missing docs will still fail CI, but means we can use
15// README.md as the crate documentation.
16
17#![no_std]
18#![cfg_attr(feature = "bench", feature(test))]
19#![cfg_attr(feature = "nightly", deny(missing_docs))]
20#![doc(html_logo_url = "https://doc.dalek.rs/assets/dalek-logo-clear.png")]
21#![doc(html_root_url = "https://docs.rs/x25519-dalek/2.0.0-pre.1")]
22
23//! # x25519-dalek [](https://crates.io/crates/x25519-dalek) [](https://docs.rs/x25519-dalek) [](https://travis-ci.org/dalek-cryptography/x25519-dalek)
24//!
25//! A pure-Rust implementation of x25519 elliptic curve Diffie-Hellman key exchange,
26//! with curve operations provided by
27//! [curve25519-dalek](https://github.com/dalek-cryptography/curve25519-dalek).
28//!
29//! This crate provides two levels of API: a bare byte-oriented `x25519`
30//! function which matches the function specified in [RFC7748][rfc7748], as
31//! well as a higher-level Rust API for static and ephemeral Diffie-Hellman.
32//!
33//! ## Examples
34//!
35//! <a href="https://shop.bubblesort.io">
36//! <img
37//! style="float: right; width: auto; height: 300px;"
38//! src="https://raw.githubusercontent.com/dalek-cryptography/x25519-dalek/master/res/bubblesort-zines-secret-messages-cover.jpeg"/>
39//! </a>
40//!
41//! Alice and Bob are two adorable kittens who have lost their mittens, and they
42//! wish to be able to send secret messages to each other to coordinate finding
43//! them, otherwise—if their caretaker cat finds out—they will surely be called
44//! naughty kittens and be given no pie!
45//!
46//! But the two kittens are quite clever. Even though their paws are still too big
47//! and the rest of them is 90% fuzziness, these clever kittens have been studying
48//! up on modern public key cryptography and have learned a nifty trick called
49//! *elliptic curve Diffie-Hellman key exchange*. With the right incantations, the
50//! kittens will be able to secretly organise to find their mittens, and then spend
51//! the rest of the afternoon nomming some yummy pie!
52//!
53//! First, Alice uses `EphemeralSecret::new()` and then
54//! `PublicKey::from()` to produce her secret and public keys:
55//!
56//! ```rust
57//! use rand_core::OsRng;
58//! use x25519_dalek::{EphemeralSecret, PublicKey};
59//!
60//! let alice_secret = EphemeralSecret::new(OsRng);
61//! let alice_public = PublicKey::from(&alice_secret);
62//! ```
63//!
64//! Bob does the same:
65//!
66//! ```rust
67//! # use rand_core::OsRng;
68//! # use x25519_dalek::{EphemeralSecret, PublicKey};
69//! let bob_secret = EphemeralSecret::new(OsRng);
70//! let bob_public = PublicKey::from(&bob_secret);
71//! ```
72//!
73//! Alice meows across the room, telling `alice_public` to Bob, and Bob
74//! loudly meows `bob_public` back to Alice. Alice now computes her
75//! shared secret with Bob by doing:
76//!
77//! ```rust
78//! # use rand_core::OsRng;
79//! # use x25519_dalek::{EphemeralSecret, PublicKey};
80//! # let alice_secret = EphemeralSecret::new(OsRng);
81//! # let alice_public = PublicKey::from(&alice_secret);
82//! # let bob_secret = EphemeralSecret::new(OsRng);
83//! # let bob_public = PublicKey::from(&bob_secret);
84//! let alice_shared_secret = alice_secret.diffie_hellman(&bob_public);
85//! ```
86//!
87//! Similarly, Bob computes a shared secret by doing:
88//!
89//! ```rust
90//! # use rand_core::OsRng;
91//! # use x25519_dalek::{EphemeralSecret, PublicKey};
92//! # let alice_secret = EphemeralSecret::new(OsRng);
93//! # let alice_public = PublicKey::from(&alice_secret);
94//! # let bob_secret = EphemeralSecret::new(OsRng);
95//! # let bob_public = PublicKey::from(&bob_secret);
96//! let bob_shared_secret = bob_secret.diffie_hellman(&alice_public);
97//! ```
98//!
99//! These secrets are the same:
100//!
101//! ```rust
102//! # use rand_core::OsRng;
103//! # use x25519_dalek::{EphemeralSecret, PublicKey};
104//! # let alice_secret = EphemeralSecret::new(OsRng);
105//! # let alice_public = PublicKey::from(&alice_secret);
106//! # let bob_secret = EphemeralSecret::new(OsRng);
107//! # let bob_public = PublicKey::from(&bob_secret);
108//! # let alice_shared_secret = alice_secret.diffie_hellman(&bob_public);
109//! # let bob_shared_secret = bob_secret.diffie_hellman(&alice_public);
110//! assert_eq!(alice_shared_secret.as_bytes(), bob_shared_secret.as_bytes());
111//! ```
112//!
113//! Voilà! Alice and Bob can now use their shared secret to encrypt their
114//! meows, for example, by using it to generate a key and nonce for an
115//! authenticated-encryption cipher.
116//!
117//! This example used the ephemeral DH API, which ensures that secret keys
118//! cannot be reused; Alice and Bob could instead use the static DH API
119//! and load a long-term secret key.
120//!
121//! # Installation
122//!
123//! To install, add the following to your project's `Cargo.toml`:
124//!
125//! ```toml
126//! [dependencies]
127//! x25519-dalek = "2.0.0-pre.0"
128//! ```
129//!
130//! # MSRV
131//!
132//! Current MSRV is 1.60.
133//!
134//! # Documentation
135//!
136//! Documentation is available [here](https://docs.rs/x25519-dalek).
137//!
138//! # Note
139//!
140//! This code matches the [RFC7748][rfc7748] test vectors.
141//! The elliptic curve
142//! operations are provided by `curve25519-dalek`, which makes a best-effort
143//! attempt to prevent software side-channels.
144//!
145//! "Secret Messages" cover image and [zine](https://shop.bubblesort.io/products/secret-messages-zine)
146//! copyright © Amy Wibowo ([@sailorhg](https://twitter.com/sailorhg))
147//!
148//! [rfc7748]: https://tools.ietf.org/html/rfc7748
149//!
150//! # See also
151//!
152//! - [crypto_box]: pure Rust public-key authenticated encryption compatible with
153//! the NaCl family of encryption libraries (libsodium, TweetNaCl) which uses
154//! `x25519-dalek` for key agreement
155//!
156//! [crypto_box]: https://github.com/RustCrypto/AEADs/tree/master/crypto_box
157
158mod x25519;
159
160pub use crate::x25519::*;