From 99921de6f3e5f30b6607648e9d60840ef0e0ec88 Mon Sep 17 00:00:00 2001 From: Henry de Valence Date: Thu, 25 Jan 2018 13:40:30 -0800 Subject: [PATCH] Use `README.md` for the crate docs, and rewrite it. --- README.md | 145 ++++++++++++++++++++++++++++++----------------------- src/lib.rs | 30 ++++------- 2 files changed, 93 insertions(+), 82 deletions(-) diff --git a/README.md b/README.md index 402924a..8320066 100644 --- a/README.md +++ b/README.md @@ -2,13 +2,81 @@ # curve25519-dalek [![](https://img.shields.io/crates/v/curve25519-dalek.svg)](https://crates.io/crates/curve25519-dalek) [![](https://docs.rs/curve25519-dalek/badge.svg)](https://docs.rs/curve25519-dalek) [![](https://travis-ci.org/dalek-cryptography/curve25519-dalek.svg?branch=master)](https://travis-ci.org/dalek-cryptography/curve25519-dalek) -**A low-level cryptographic library for point, group, field, and scalar -operations on a curve isomorphic to the twisted Edwards curve defined by -x²+y² -= 1 - 121665/121666 x²y² over GF(2²⁵⁵ - 19).** +**A pure-Rust implementation of group operations on Ristretto and Curve25519.** + +`curve25519-dalek` is a library providing group operations on the Edwards and +Montgomery forms of Curve25519, and on the prime-order Ristretto group. + +`curve25519-dalek` is not intended to provide implementations of any particular +crypto protocol. Rather, implementations of those protocols (such as +[`x25519-dalek`][x25519-dalek] and [`ed25519-dalek`][ed25519-dalek]) should use +`curve25519-dalek` as a library. + +`curve25519-dalek` is intended to provide a clean and safe _mid-level_ API for use +implementing a wide range of ECC-based crypto protocols, such as key agreement, +signatures, anonymous credentials, rangeproofs, and zero-knowledge proof +systems. + +## WARNING + +We do not yet consider this code to be production-ready. We intend to +stabilize a production-ready version `1.0` soon. + +# Documentation + +The semver-stable, public-facing `curve25519-dalek` API is documented +[here][docs-external]. In addition, the unstable internal implementation +details are documented [here][docs-internal]. + +The `curve25519-dalek` documentation requires a custom HTML header to include +KaTeX for math support. Unfortunately `cargo doc` does not currently support +this, but docs can be built using +```sh +make doc +make doc-internal +``` + +# Use + +To import `curve25519-dalek`, add the following to the dependencies section of +your project's `Cargo.toml`: +```toml +curve25519-dalek = "^0.14" +``` +Then import the crate as: +```rust,no_run +extern crate curve25519_dalek; +``` + +# Backends and Features + +Curve arithmetic is implemented using one of the following backends: + +* a `u32` backend using `u64` products; +* a `u64` backend using `u128` products, available using the `nightly` feature; +* an experimental AVX2 backend, available using the `yolocrypto` feature when compiling for a target with `target_feature=+avx2` + +By default, the benchmarks are not compiled without the `bench` +feature. Benchmarks can be run via: + +```sh +cargo bench --features="bench" # u32 backend +cargo bench --features="bench nightly" # u64 backend +cargo bench --features="bench nightly yolocrypto" # u64 or avx2 if available +``` + +# Contributing + +Please see [CONTRIBUTING.md][contributing]. + +Patches and pull requests should be make against the `develop` +branch, **not** `master`. + +# About **SPOILER ALERT:** *The Twelfth Doctor's first encounter with the Daleks is in his second full episode, "Into the Dalek". A beleaguered ship of the "Combined @@ -23,65 +91,16 @@ universe's beauty, but also his deep hatred of the Daleks. Rusty destroys the other Daleks and departs the ship, determined to track down and bring an end to the Dalek race.* -Significant portions of this code are ported from [Adam Langley's -Golang ed25519 library](https://github.com/agl/ed25519), which is in +`curve25519-dalek` is authored by Isis Agora Lovecruft and Henry de Valence. + +Portions of this library were originally a port of [Adam Langley's +Golang ed25519 library](https://github.com/agl/ed25519), which was in turn a port of the reference `ref10` implementation. -## Warning +The fast `u32` and `u64` scalar arithmetic was implemented by Andrew Moon, and +the addition chain for scalar inversion was provided by Brian Smith. The +`no_std` support was contributed by Tony Arcieri. -This code has **not** yet received sufficient peer review by other qualified -cryptographers to be considered in any way, shape, or form, safe. Further, -this library does **not** provide high-level routines such as encryption and -decryption or signing and verification. Instead, it is a low-level library, -intended for other cryptographers who would like to implement their own -primitives using this curve. (For an example of how one would implement a -signature scheme using this library, see -[ed25519-dalek](https://github.com/dalek-cryptography/ed25519-dalek).) - -**USE AT YOUR OWN RISK** - -## Documentation - -Extensive documentation is available [here](https://docs.rs/curve25519-dalek). - -# Installation - -To install, add the following to the dependencies section of your project's -`Cargo.toml`: - -```toml -curve25519-dalek = "^0.14" -``` - -Then, in your library or executable source, add: - - extern crate curve25519_dalek; - -## Features - -On nightly Rust, using the `nightly` feature enables a radix-51 field -arithmetic implementation using `u128`s, which is approximately twice as -fast. It will also enable additional developer documentation when -compiling via `make doc-internal`. - -By default, the benchmarks are not compiled without the `bench` -feature. To run the benchmarks, do: - -```sh -cargo bench --features="bench" -``` - -## TODO - -We intend to stabilise the following before curve25519-dalek-1.0.0: - -* Implement hashing to a point on the curve (Elligator). -* Finish Ristretto documentation. - -## Contributing - -Please see -[CONTRIBUTING.md](https://github.com/dalek-cryptography/curve25519-dalek/blob/master/CONTRIBUTING.md). - -Patches and pull requests should be make against the `develop` -branch, **not** `master`. +[ed25519-dalek]: https://github.com/dalek-cryptography/ed25519-dalek +[x25519-dalek]: https://github.com/dalek-cryptography/x25519-dalek +[contributing]: https://github.com/dalek-cryptography/curve25519-dalek/blob/master/CONTRIBUTING.md diff --git a/src/lib.rs b/src/lib.rs index 0baf368..c4f5d68 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -9,29 +9,21 @@ // - Henry de Valence #![cfg_attr(not(feature = "std"), no_std)] + #![cfg_attr(feature = "alloc", feature(alloc))] -#![cfg_attr(feature = "nightly", feature(i128_type))] -#![cfg_attr(feature = "nightly", feature(cfg_target_feature))] #![cfg_attr(feature = "bench", feature(test))] -#![deny(missing_docs)] // refuse to compile if documentation is missing +#![cfg_attr(feature = "nightly", feature(i128_type))] +#![cfg_attr(feature = "nightly", feature(cfg_target_feature))] +#![cfg_attr(feature = "nightly", feature(external_doc))] -//! # curve25519-dalek -//! -//! **A high-performance, pure-Rust implementation of group operations for Ristretto and Curve25519.** -//! -//! **[SPOILER ALERT]** The Twelfth Doctor's first encounter with the Daleks is -//! in his second full episode, "Into the Dalek". A beleaguered ship of the -//! "Combined Galactic Resistance" has discovered a broken Dalek that has -//! turned "good", desiring to kill all other Daleks. The Doctor, Clara and a -//! team of soldiers are miniaturized and enter the Dalek, which the Doctor -//! names Rusty. They repair the damage, but accidentally restore it to its -//! original nature, causing it to go on the rampage and alert the Dalek fleet -//! to the whereabouts of the rebel ship. However, the Doctor manages to -//! return Rusty to its previous state by linking his mind with the Dalek's: -//! Rusty shares the Doctor's view of the universe's beauty, but also his deep -//! hatred of the Daleks. Rusty destroys the other Daleks and departs the -//! ship, determined to track down and bring an end to the Dalek race. +// Refuse to compile if documentation is missing, but only on nightly. +// +// This means that missing docs will still fail CI, but means we can use +// README.md as the crate documentation. +#![cfg_attr(feature = "nightly", deny(missing_docs))] + +#![cfg_attr(feature = "nightly", doc(include = "../README.md"))] //------------------------------------------------------------------------ // External dependencies: