saymrwulf/curve25519-dalek-source
1
0
Fork 0
mirror of https://github.com/saymrwulf/curve25519-dalek-source.git synced 2026-09-09 21:10:44 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Pull source docs from README

Browse source
This commit is contained in:
Henry de Valence 2019-01-10 10:30:30 -08:00
parent 65f94124f4
commit b8716bb82b
2 changed files with 37 additions and 143 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

56
README.md
View file

@ -1,17 +1,20 @@
# x25519-dalek [![](https://img.shields.io/crates/v/x25519-dalek.svg)](https://crates.io/crates/x25519-dalek) [![](https://docs.rs/x25519-dalek/badge.svg)](https://docs.rs/x25519-dalek) [![](https://travis-ci.org/dalek-cryptography/x25519-dalek.svg?branch=master)](https://travis-ci.org/dalek-cryptography/x25519-dalek) # x25519-dalek [![](https://img.shields.io/crates/v/x25519-dalek.svg)](https://crates.io/crates/x25519-dalek) [![](https://docs.rs/x25519-dalek/badge.svg)](https://docs.rs/x25519-dalek) [![](https://travis-ci.org/dalek-cryptography/x25519-dalek.svg?branch=master)](https://travis-ci.org/dalek-cryptography/x25519-dalek)
A pure-Rust implementation of x25519 elliptic curve Diffie-Hellman key exchange, A pure-Rust implementation of x25519 elliptic curve Diffie-Hellman key exchange,
as specified by Mike Hamburg and Adam Langley in with curve operations provided by
[RFC7748](https://tools.ietf.org/html/rfc7748), using
[curve25519-dalek](https://github.com/dalek-cryptography/curve25519-dalek). [curve25519-dalek](https://github.com/dalek-cryptography/curve25519-dalek).
This crate provides two levels of API: a bare byte-oriented `x25519`
function which matches the function specified in [RFC7748][rfc7748], as
well as a higher-level Rust API for ephemeral Diffie-Hellman.
## Examples ## Examples
[![](https://raw.githubusercontent.com/dalek-cryptography/x25519-dalek/master/res/bubblesort-zines-secret-messages-cover.jpeg)](https://shop.bubblesort.io) <a href="https://shop.bubblesort.io">
<img
"Secret Messages" cover image and [zine](https://shop.bubblesort.io/products/secret-messages-zine) style="float: right; width: auto; height: 300px;"
copyright © Amy Wibowo ([@sailorhg](https://twitter.com/sailorhg)) src="https://raw.githubusercontent.com/dalek-cryptography/x25519-dalek/master/res/bubblesort-zines-secret-messages-cover.jpeg"/>
</a>
Alice and Bob are two adorable kittens who have lost their mittens, and they 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 wish to be able to send secret messages to each other to coordinate finding
@ -25,8 +28,8 @@ up on modern public key cryptography and have learned a nifty trick called
kittens will be able to secretly organise to find their mittens, and then spend kittens will be able to secretly organise to find their mittens, and then spend
the rest of the afternoon nomming some yummy pie! the rest of the afternoon nomming some yummy pie!
First, Alice uses `x25519_dalek::EphemeralSecret::new()` and then First, Alice uses `EphemeralSecret::new()` and then
`x25519_dalek::EphemeralPublic::from()` to produce her secret and public keys: `EphemeralPublic::from()` to produce her secret and public keys:
```rust ```rust
extern crate x25519_dalek; extern crate x25519_dalek;
@ -70,23 +73,6 @@ 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 meows, for example, by using it to generate a key and nonce for an
authenticated-encryption cipher. authenticated-encryption cipher.
# Warnings
[Our elliptic curve library](https://github.com/dalek-cryptography/curve25519-dalek)
(which this code uses) has received *one* formal cryptographic and security
review. It has not yet received what we would consider *sufficient* peer
review by other qualified cryptographers to be considered in any way, shape,
or form, safe.
This code matches the test vectors, as specified in
[RFC7748](https://tools.ietf.org/html/rfc7748), however:
**USE AT YOUR OWN RISK.**
# Documentation
Documentation is available [here](https://docs.rs/x25519-dalek).
# Installation # Installation
To install, add the following to your project's `Cargo.toml`: To install, add the following to your project's `Cargo.toml`:
@ -96,8 +82,18 @@ To install, add the following to your project's `Cargo.toml`:
version = "^0.3" version = "^0.3"
``` ```
Then, in your library or executable source, add: # Documentation
```rust Documentation is available [here](https://docs.rs/x25519-dalek).
extern crate x25519_dalek;
``` # Note
This code matches the [RFC7748][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](https://shop.bubblesort.io/products/secret-messages-zine)
copyright © Amy Wibowo ([@sailorhg](https://twitter.com/sailorhg))
[rfc7748]: https://tools.ietf.org/html/rfc7748

124
src/lib.rs
View file

@ -7,122 +7,20 @@
// Authors: // Authors:
// - Isis Agora Lovecruft <isis@patternsinthevoid.net> // - Isis Agora Lovecruft <isis@patternsinthevoid.net>
//! x25519 Diffie-Hellman key exchange // Refuse to compile if documentation is missing, but only on nightly.
//! //
//! A pure-Rust implementation of x25519 elliptic curve Diffie-Hellman key // This means that missing docs will still fail CI, but means we can use
//! exchange as specified by Mike Hamburg and Adam Langley in // README.md as the crate documentation.
//! [RFC7748](https://tools.ietf.org/html/rfc7748).
//!
//! # Examples
//!
//! [![](https://raw.githubusercontent.com/isislovecruft/x25519-dalek/master/res/bubblesort-zines-secret-messages-cover.jpeg)](https://shop.bubblesort.io)
//!
//! "Secret Messages" cover image and [zine](https://shop.bubblesort.io/products/secret-messages-zine)
//! copyright © Amy Wibowo ([@sailorhg](https://twitter.com/sailorhg))
//!
//! 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 `x25519_dalek::EphemeralSecret::new()` and
//! `x25519_dalek::EphemeralPublic::from()` to produce her secret and public keys:
//!
//! ```
//! extern crate x25519_dalek;
//! extern crate rand;
//!
//! # fn main() {
//! use x25519_dalek::EphemeralPublic;
//! use x25519_dalek::EphemeralSecret;
//! use rand::thread_rng;
//!
//! let mut alice_csprng = thread_rng();
//! let alice_secret = EphemeralSecret::new(&mut alice_csprng);
//! let alice_public = EphemeralPublic::from(&alice_secret);
//! # }
//! ```
//!
//! Bob does the same:
//!
//! ```
//! # extern crate x25519_dalek;
//! # extern crate rand;
//! #
//! # fn main() {
//! # use x25519_dalek::EphemeralPublic;
//! # use x25519_dalek::EphemeralSecret;
//! # use rand::thread_rng;
//! #
//! let mut bob_csprng = thread_rng();
//! 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:
//!
//! ```
//! # extern crate x25519_dalek;
//! # extern crate rand;
//! #
//! # fn main() {
//! # use x25519_dalek::EphemeralPublic;
//! # use x25519_dalek::EphemeralSecret;
//! # use rand::thread_rng;
//! #
//! # let mut alice_csprng = thread_rng();
//! # let alice_secret = EphemeralSecret::new(&mut alice_csprng);
//! # let alice_public = EphemeralPublic::from(&alice_secret);
//! #
//! # let mut bob_csprng = thread_rng();
//! # let bob_secret = EphemeralSecret::new(&mut bob_csprng);
//! # let bob_public = EphemeralPublic::from(&bob_secret);
//! #
//! #
//! let shared_secret = EphemeralSecret::diffie_hellman(alice_secret, &bob_public);
//! # }
//! ```
//!
//! Similarly, Bob computes the same shared secret by doing:
//!
//! ```
//! # extern crate x25519_dalek;
//! # extern crate rand;
//! #
//! # fn main() {
//! # use x25519_dalek::EphemeralPublic;
//! # use x25519_dalek::EphemeralSecret;
//! # use rand::thread_rng;
//! #
//! # let mut alice_csprng = thread_rng();
//! # let alice_secret = EphemeralSecret::new(&mut alice_csprng);
//! # let alice_public = EphemeralPublic::from(&alice_secret);
//! #
//! # let mut bob_csprng = thread_rng();
//! # let bob_secret = EphemeralSecret::new(&mut bob_csprng);
//! # let bob_public = EphemeralPublic::from(&bob_secret);
//! #
//! 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.
#![no_std] #![no_std]
#![cfg_attr(feature = "bench", feature(test))] #![cfg_attr(feature = "bench", feature(test))]
#![deny(missing_docs)] #![cfg_attr(feature = "nightly", feature(external_doc))]
#![cfg_attr(feature = "nightly", deny(missing_docs))]
#![cfg_attr(feature = "nightly", doc(include = "../README.md"))]
#![doc(html_logo_url = "https://doc.dalek.rs/assets/dalek-logo-clear.png")]
//! Note that docs will only build on nightly Rust until
//! `feature(external_doc)` is stabilized.
extern crate clear_on_drop; extern crate clear_on_drop;