diff --git a/CHANGELOG.md b/CHANGELOG.md index ca3cae4..f2126ab 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,8 @@ major series. ## 4.x series +* Migrate documentation to docs.rs hosted +* Fix backend documentation generation * Deprecate `EdwardsPoint::hash_from_bytes` and rename it `EdwardsPoint::nonspect_map_to_curve` * Fix panic when `Ristretto::double_and_compress_batch` receives the identity point * Remove `byteorder` dependency diff --git a/Cargo.toml b/Cargo.toml index 6eb7361..c621a19 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -24,9 +24,8 @@ exclude = [ ] [package.metadata.docs.rs] -# Disabled for now since this is borked; tracking https://github.com/rust-lang/docs.rs/issues/302 -# rustdoc-args = ["--html-in-header", ".cargo/registry/src/github.com-1ecc6299db9ec823/curve25519-dalek-0.13.2/rustdoc-include-katex-header.html"] -features = ["nightly", "simd_backend"] +rustdoc-args = ["--html-in-header", "docs/assets/rustdoc-include-katex-header.html", "--cfg", "docsrs"] +features = ["serde", "simd_backend"] [badges] travis-ci = { repository = "dalek-cryptography/curve25519-dalek", branch = "master"} diff --git a/Makefile b/Makefile index 4228496..7eddc3c 100644 --- a/Makefile +++ b/Makefile @@ -1,8 +1,8 @@ -FEATURES := nightly simd_backend +FEATURES := simd_backend serde doc: - cargo +nightly rustdoc --features "$(FEATURES)" -- --html-in-header docs/assets/rustdoc-include-katex-header.html + cargo +nightly rustdoc --features "$(FEATURES)" -- --html-in-header docs/assets/rustdoc-include-katex-header.html --cfg docsrs doc-internal: - cargo +nightly rustdoc --features "$(FEATURES)" -- --html-in-header docs/assets/rustdoc-include-katex-header.html --document-private-items + cargo +nightly rustdoc --features "$(FEATURES)" -- --html-in-header docs/assets/rustdoc-include-katex-header.html --document-private-items --cfg docsrs diff --git a/README.md b/README.md index 43ee8b2..36f1837 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,12 @@ # curve25519-dalek [![](https://img.shields.io/crates/v/curve25519-dalek.svg)](https://crates.io/crates/curve25519-dalek) [![](https://img.shields.io/badge/dynamic/json.svg?label=docs&uri=https%3A%2F%2Fcrates.io%2Fapi%2Fv1%2Fcrates%2Fcurve25519-dalek%2Fversions&query=%24.versions%5B0%5D.num&colorB=4F74A6)](https://doc.dalek.rs) [![](https://travis-ci.org/dalek-cryptography/curve25519-dalek.svg?branch=master)](https://travis-ci.org/dalek-cryptography/curve25519-dalek) +

dalek-cryptography logo: a dalek with edwards curves as sparkles coming out of its radar-schnozzley blaster thingies +

**A pure-Rust implementation of group operations on Ristretto and Curve25519.** @@ -246,6 +248,6 @@ contributions. [docs-external]: https://doc.dalek.rs/curve25519_dalek/ [docs-internal]: https://doc-internal.dalek.rs/curve25519_dalek/ [criterion]: https://github.com/japaric/criterion.rs -[parallel_doc]: https://doc-internal.dalek.rs/curve25519_dalek/backend/vector/avx2/index.html +[parallel_doc]: https://docs.rs/curve25519-dalek/latest/curve25519_dalek/backend/vector/index.html [subtle_doc]: https://doc.dalek.rs/subtle/ [fiat-crypto]: https://github.com/mit-plv/fiat-crypto diff --git a/docs/parallel-formulas.md b/docs/parallel-formulas.md index 9472736..70aadc3 100644 --- a/docs/parallel-formulas.md +++ b/docs/parallel-formulas.md @@ -145,16 +145,16 @@ This costs \\( 2\mathbf M + 1 \mathbf D\\). ## Readdition -If the point \\( P_2 = (X\_2 : Y\_2 : Z\_2 : T\_2) \\) is fixed, we +If the point \\( P\_2 = (X\_2 : Y\_2 : Z\_2 : T\_2) \\) is fixed, we can cache the multiplication of the curve constants by computing $$ \begin{aligned} -(S\_2' &&,&& S\_3' &&,&& Z\_2' &&,&& T\_2' ) +(S\_2\' &&,&& S\_3\' &&,&& Z\_2\' &&,&& T\_2\' ) &\gets (d\_2 \cdot (Y\_2 - X\_2)&&,&& d\_2 \cdot (Y\_1 + X\_1)&&,&& 2d\_2 \cdot Z\_2 &&,&& 2d\_1 \cdot T\_2). \end{aligned} $$ -This costs \\( 1\mathbf D\\); with \\( (S\_2', S\_3', Z\_2', T\_2')\\) +This costs \\( 1\mathbf D\\); with \\( (S\_2\', S\_3\', Z\_2\', T\_2\')\\) in hand, the addition formulas above become $$ \begin{aligned} @@ -164,7 +164,7 @@ $$ \\\\ (S\_8 &&,&& S\_9 &&,&& S\_{10} &&,&& S\_{11} ) &\gets -(S\_0 \cdot S\_2' &&,&& S\_1 \cdot S\_3'&&,&& Z\_1 \cdot Z\_2' &&,&& T\_1 \cdot T\_2') +(S\_0 \cdot S\_2\' &&,&& S\_1 \cdot S\_3\'&&,&& Z\_1 \cdot Z\_2\' &&,&& T\_1 \cdot T\_2\') \\\\ (S\_{12} &&,&& S\_{13} &&,&& S\_{14} &&,&& S\_{15}) &\gets @@ -327,7 +327,7 @@ There are several directions for future improvement: [sandy2x]: https://eprint.iacr.org/2015/943.pdf [avx2trac]: https://trac.torproject.org/projects/tor/ticket/8897#comment:28 [hwcd08]: https://www.iacr.org/archive/asiacrypt2008/53500329/53500329.pdf -[curve_models]: https://doc-internal.dalek.rs/curve25519_dalek/backend/serial/curve_models/index.html +[curve_models]: https://docs.rs/curve25519-dalek/latest/curve25519-dalek/backend/serial/curve_models/index.html [bbjlp08]: https://eprint.iacr.org/2008/013 [cmo98]: https://link.springer.com/content/pdf/10.1007%2F3-540-49649-1_6.pdf [intel]: https://software.intel.com/sites/default/files/managed/9e/bc/64-ia-32-architectures-optimization-manual.pdf diff --git a/src/backend/mod.rs b/src/backend/mod.rs index 9da6983..e3b8112 100644 --- a/src/backend/mod.rs +++ b/src/backend/mod.rs @@ -9,7 +9,7 @@ // - isis agora lovecruft // - Henry de Valence -//! Pluggable implementations for different architectures. +//! **INTERNALS:** Pluggable implementations for different architectures. //! //! The backend code is split into two parts: a serial backend, //! and a vector backend. @@ -36,18 +36,5 @@ pub mod serial; -#[cfg(any( - all( - feature = "simd_backend", - any(target_feature = "avx2", target_feature = "avx512ifma") - ), - all(feature = "nightly", rustdoc) -))] -#[cfg_attr( - feature = "nightly", - doc(cfg(any(all( - feature = "simd_backend", - any(target_feature = "avx2", target_feature = "avx512ifma") - )))) -)] +#[cfg(any(feature = "simd_backend", docsrs))] pub mod vector; diff --git a/src/backend/serial/curve_models/mod.rs b/src/backend/serial/curve_models/mod.rs index e5c4f5a..5e6d86d 100644 --- a/src/backend/serial/curve_models/mod.rs +++ b/src/backend/serial/curve_models/mod.rs @@ -148,6 +148,7 @@ use crate::traits::ValidityCheck; /// /// More details on the relationships between the different curve models /// can be found in the module-level documentation. +#[allow(missing_docs)] #[derive(Copy, Clone)] pub struct ProjectivePoint { pub X: FieldElement, @@ -199,6 +200,7 @@ impl Zeroize for AffineNielsPoint { /// More details on the relationships between the different curve models /// can be found in the module-level documentation. #[derive(Copy, Clone)] +#[allow(missing_docs)] pub struct ProjectiveNielsPoint { pub Y_plus_X: FieldElement, pub Y_minus_X: FieldElement, diff --git a/src/backend/serial/scalar_mul/mod.rs b/src/backend/serial/scalar_mul/mod.rs index 8bdad1f..7747dec 100644 --- a/src/backend/serial/scalar_mul/mod.rs +++ b/src/backend/serial/scalar_mul/mod.rs @@ -17,8 +17,10 @@ //! scalar multiplication implementations, since it only uses one //! curve model. +#[allow(missing_docs)] pub mod variable_base; +#[allow(missing_docs)] pub mod vartime_double_base; #[cfg(feature = "alloc")] diff --git a/src/backend/serial/scalar_mul/pippenger.rs b/src/backend/serial/scalar_mul/pippenger.rs index 0966a9a..fc7f2a2 100644 --- a/src/backend/serial/scalar_mul/pippenger.rs +++ b/src/backend/serial/scalar_mul/pippenger.rs @@ -61,7 +61,8 @@ use crate::prelude::*; /// This algorithm is adapted from section 4 of . pub struct Pippenger; -#[cfg(any(feature = "alloc", feature = "std"))] +#[cfg(feature = "alloc")] +#[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))] impl VartimeMultiscalarMul for Pippenger { type Point = EdwardsPoint; diff --git a/src/backend/serial/scalar_mul/precomputed_straus.rs b/src/backend/serial/scalar_mul/precomputed_straus.rs index fee21c2..b6a5b52 100644 --- a/src/backend/serial/scalar_mul/precomputed_straus.rs +++ b/src/backend/serial/scalar_mul/precomputed_straus.rs @@ -25,6 +25,7 @@ use crate::window::{NafLookupTable5, NafLookupTable8}; #[allow(unused_imports)] use crate::prelude::*; +#[allow(missing_docs)] pub struct VartimePrecomputedStraus { static_lookup_tables: Vec>, } diff --git a/src/backend/vector/ifma/mod.rs b/src/backend/vector/ifma/mod.rs index dbfc2dd..79a61ff 100644 --- a/src/backend/vector/ifma/mod.rs +++ b/src/backend/vector/ifma/mod.rs @@ -9,8 +9,10 @@ #![doc = include_str!("../../../../docs/ifma-notes.md")] +#[allow(missing_docs)] pub mod field; +#[allow(missing_docs)] pub mod edwards; pub mod constants; diff --git a/src/backend/vector/mod.rs b/src/backend/vector/mod.rs index 1763899..734c442 100644 --- a/src/backend/vector/mod.rs +++ b/src/backend/vector/mod.rs @@ -11,29 +11,29 @@ #![doc = include_str!("../../../docs/parallel-formulas.md")] -#[cfg(not(any(target_feature = "avx2", target_feature = "avx512ifma", rustdoc)))] +#[cfg(not(any(target_feature = "avx2", target_feature = "avx512ifma", docsrs)))] compile_error!("simd_backend selected without target_feature=+avx2 or +avx512ifma"); #[cfg(any( all(target_feature = "avx2", not(target_feature = "avx512ifma")), - rustdoc + all(docsrs, target_arch = "x86_64") ))] -#[doc(cfg(all(target_feature = "avx2", not(target_feature = "avx512ifma"))))] pub mod avx2; #[cfg(any( all(target_feature = "avx2", not(target_feature = "avx512ifma")), - rustdoc + all(docsrs, target_arch = "x86_64") ))] pub(crate) use self::avx2::{ constants::BASEPOINT_ODD_LOOKUP_TABLE, edwards::CachedPoint, edwards::ExtendedPoint, }; -#[cfg(any(target_feature = "avx512ifma", rustdoc))] -#[doc(cfg(target_feature = "avx512ifma"))] +#[cfg(any(target_feature = "avx512ifma", all(docsrs, target_arch = "x86_64")))] pub mod ifma; #[cfg(target_feature = "avx512ifma")] pub(crate) use self::ifma::{ constants::BASEPOINT_ODD_LOOKUP_TABLE, edwards::CachedPoint, edwards::ExtendedPoint, }; +#[cfg(any(target_feature = "avx2", target_feature = "avx512ifma", all(docsrs, target_arch = "x86_64")))] +#[allow(missing_docs)] pub mod scalar_mul; diff --git a/src/backend/vector/scalar_mul/mod.rs b/src/backend/vector/scalar_mul/mod.rs index 36a7047..32fefec 100644 --- a/src/backend/vector/scalar_mul/mod.rs +++ b/src/backend/vector/scalar_mul/mod.rs @@ -14,10 +14,13 @@ pub mod variable_base; pub mod vartime_double_base; #[cfg(feature = "alloc")] +#[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))] pub mod straus; #[cfg(feature = "alloc")] +#[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))] pub mod precomputed_straus; #[cfg(feature = "alloc")] +#[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))] pub mod pippenger; diff --git a/src/backend/vector/scalar_mul/pippenger.rs b/src/backend/vector/scalar_mul/pippenger.rs index 3ed5e91..94e24f9 100644 --- a/src/backend/vector/scalar_mul/pippenger.rs +++ b/src/backend/vector/scalar_mul/pippenger.rs @@ -24,7 +24,8 @@ use crate::prelude::*; /// See the documentation in the serial `scalar_mul::pippenger` module for details. pub struct Pippenger; -#[cfg(any(feature = "alloc", feature = "std"))] +#[cfg(feature = "alloc")] +#[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))] impl VartimeMultiscalarMul for Pippenger { type Point = EdwardsPoint; diff --git a/src/edwards.rs b/src/edwards.rs index 77add9c..8dcdc2d 100644 --- a/src/edwards.rs +++ b/src/edwards.rs @@ -85,7 +85,7 @@ //! successful decompression of a compressed point, or else by //! operations on other (valid) `EdwardsPoint`s. //! -//! [curve_models]: https://doc-internal.dalek.rs/curve25519_dalek/backend/serial/curve_models/index.html +//! [curve_models]: https://docs.rs/curve25519-dalek/latest/curve25519-dalek/backend/serial/curve_models/index.html // We allow non snake_case names because coordinates in projective space are // traditionally denoted by the capitalisation of their respective @@ -134,9 +134,9 @@ use crate::traits::BasepointTable; use crate::traits::ValidityCheck; use crate::traits::{Identity, IsIdentity}; -#[cfg(any(feature = "alloc", feature = "std"))] +#[cfg(feature = "alloc")] use crate::traits::MultiscalarMul; -#[cfg(any(feature = "alloc", feature = "std"))] +#[cfg(feature = "alloc")] use crate::traits::{VartimeMultiscalarMul, VartimePrecomputedMultiscalarMul}; #[cfg(not(all( @@ -707,6 +707,7 @@ impl<'a, 'b> Mul<&'b EdwardsPoint> for &'a Scalar { // forward to a specific backend implementation. #[cfg(feature = "alloc")] +#[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))] impl MultiscalarMul for EdwardsPoint { type Point = EdwardsPoint; @@ -739,6 +740,7 @@ impl MultiscalarMul for EdwardsPoint { } #[cfg(feature = "alloc")] +#[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))] impl VartimeMultiscalarMul for EdwardsPoint { type Point = EdwardsPoint; @@ -778,9 +780,11 @@ impl VartimeMultiscalarMul for EdwardsPoint { // decouple stability of the inner type from the stability of the // outer type. #[cfg(feature = "alloc")] +#[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))] pub struct VartimeEdwardsPrecomputation(scalar_mul::precomputed_straus::VartimePrecomputedStraus); #[cfg(feature = "alloc")] +#[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))] impl VartimePrecomputedMultiscalarMul for VartimeEdwardsPrecomputation { type Point = EdwardsPoint; diff --git a/src/field.rs b/src/field.rs index 1bd7fb0..1abf952 100644 --- a/src/field.rs +++ b/src/field.rs @@ -167,6 +167,7 @@ impl FieldElement { /// /// When an input `FieldElement` is zero, its value is unchanged. #[cfg(feature = "alloc")] + #[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))] pub fn batch_invert(inputs: &mut [FieldElement]) { // Montgomery’s Trick and Fast Implementation of Masked AES // Genelle, Prouff and Quisquater diff --git a/src/lib.rs b/src/lib.rs index 52d1a1c..e831b4f 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -10,16 +10,16 @@ // - Henry de Valence #![no_std] -#![cfg_attr(feature = "nightly", feature(test))] -#![cfg_attr(feature = "nightly", feature(doc_cfg))] #![cfg_attr(feature = "simd_backend", feature(stdsimd))] - +#![cfg_attr(docsrs, feature(doc_auto_cfg, doc_cfg, doc_cfg_hide))] +#![cfg_attr(docsrs, doc(cfg_hide(docsrs)))] //------------------------------------------------------------------------ // Documentation: //------------------------------------------------------------------------ - #![deny(missing_docs)] -#![doc(html_logo_url = "https://doc.dalek.rs/assets/dalek-logo-clear.png")] +#![doc( + html_logo_url = "https://cdn.jsdelivr.net/gh/dalek-cryptography/curve25519-dalek/docs/assets/dalek-logo-clear.png" +)] #![doc(html_root_url = "https://docs.rs/curve25519-dalek/4.0.0-pre.2")] #![doc = include_str!("../README.md")] @@ -72,9 +72,13 @@ pub mod traits; pub(crate) mod field; // Arithmetic backends (using u32, u64, etc) live here +#[cfg(docsrs)] +pub mod backend; +#[cfg(not(docsrs))] pub(crate) mod backend; // Crate-local prelude (for alloc-dependent features like `Vec`) + pub(crate) mod prelude; // Generic code for window lookups diff --git a/src/ristretto.rs b/src/ristretto.rs index 38a6925..9799a99 100644 --- a/src/ristretto.rs +++ b/src/ristretto.rs @@ -190,7 +190,7 @@ use crate::scalar::Scalar; use crate::traits::BasepointTable; use crate::traits::Identity; -#[cfg(any(feature = "alloc", feature = "std"))] +#[cfg(feature = "alloc")] use crate::traits::{MultiscalarMul, VartimeMultiscalarMul, VartimePrecomputedMultiscalarMul}; #[cfg(not(all( @@ -520,6 +520,7 @@ impl RistrettoPoint { /// # } /// ``` #[cfg(feature = "alloc")] + #[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))] pub fn double_and_compress_batch<'a, I>(points: I) -> Vec where I: IntoIterator, @@ -922,6 +923,7 @@ define_mul_variants!(LHS = Scalar, RHS = RistrettoPoint, Output = RistrettoPoint // forward to the EdwardsPoint implementations. #[cfg(feature = "alloc")] +#[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))] impl MultiscalarMul for RistrettoPoint { type Point = RistrettoPoint; @@ -938,6 +940,7 @@ impl MultiscalarMul for RistrettoPoint { } #[cfg(feature = "alloc")] +#[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))] impl VartimeMultiscalarMul for RistrettoPoint { type Point = RistrettoPoint; @@ -958,9 +961,11 @@ impl VartimeMultiscalarMul for RistrettoPoint { // decouple stability of the inner type from the stability of the // outer type. #[cfg(feature = "alloc")] +#[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))] pub struct VartimeRistrettoPrecomputation(scalar_mul::precomputed_straus::VartimePrecomputedStraus); #[cfg(feature = "alloc")] +#[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))] impl VartimePrecomputedMultiscalarMul for VartimeRistrettoPrecomputation { type Point = RistrettoPoint; diff --git a/src/scalar.rs b/src/scalar.rs index 7591c2d..b0de4dc 100644 --- a/src/scalar.rs +++ b/src/scalar.rs @@ -173,6 +173,10 @@ cfg_if! { /// This is a type alias for one of the scalar types in the `backend` /// module. #[cfg(not(target_pointer_width = "64"))] + #[cfg_attr( + docsrs, + doc(cfg(all(feature = "fiat_backend", not(target_pointer_width = "64")))) + )] type UnpackedScalar = backend::serial::fiat_u32::scalar::Scalar29; /// An `UnpackedScalar` represents an element of the field GF(l), optimized for speed. @@ -180,18 +184,24 @@ cfg_if! { /// This is a type alias for one of the scalar types in the `backend` /// module. #[cfg(target_pointer_width = "64")] + #[cfg_attr( + docsrs, + doc(cfg(all(feature = "fiat_backend", target_pointer_width = "64"))) + )] type UnpackedScalar = backend::serial::fiat_u64::scalar::Scalar52; } else if #[cfg(target_pointer_width = "64")] { /// An `UnpackedScalar` represents an element of the field GF(l), optimized for speed. /// /// This is a type alias for one of the scalar types in the `backend` /// module. + #[cfg_attr(docsrs, doc(cfg(target_pointer_width = "64")))] type UnpackedScalar = backend::serial::u64::scalar::Scalar52; } else { /// An `UnpackedScalar` represents an element of the field GF(l), optimized for speed. /// /// This is a type alias for one of the scalar types in the `backend` /// module. + #[cfg_attr(docsrs, doc(cfg(not(target_pointer_width = "64"))))] type UnpackedScalar = backend::serial::u32::scalar::Scalar29; } } @@ -401,6 +411,7 @@ use serde::de::Visitor; use serde::{self, Deserialize, Deserializer, Serialize, Serializer}; #[cfg(feature = "serde")] +#[cfg_attr(docsrs, doc(cfg(feature = "serde")))] impl Serialize for Scalar { fn serialize(&self, serializer: S) -> Result where @@ -416,6 +427,7 @@ impl Serialize for Scalar { } #[cfg(feature = "serde")] +#[cfg_attr(docsrs, doc(cfg(feature = "serde")))] impl<'de> Deserialize<'de> for Scalar { fn deserialize(deserializer: D) -> Result where @@ -773,6 +785,7 @@ impl Scalar { /// # } /// ``` #[cfg(feature = "alloc")] + #[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))] pub fn batch_invert(inputs: &mut [Scalar]) -> Scalar { // This code is essentially identical to the FieldElement // implementation, and is documented there. Unfortunately,