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

Merge pull request #439 from pinkforest/docs-cleanup

Browse source
This commit is contained in:
Michael Rosenberg 2022-11-26 21:42:30 -05:00 committed by GitHub
commit edf6db09ab
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
19 changed files with 75 additions and 46 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
CHANGELOG.md
View file

@ -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

5
Cargo.toml
View file

@ -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"}

6
Makefile
View file

@ -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

8
README.md
View file

@ -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)
<p style="float: right">
<img
width="33%"
align="right"
width="300px"
alt="dalek-cryptography logo: a dalek with edwards curves as sparkles coming out of its radar-schnozzley blaster thingies"
src="https://doc.dalek.rs/assets/dalek-logo-clear.png"/>
</p>
**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

10
docs/parallel-formulas.md
View file

@ -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

17
src/backend/mod.rs
View file

@ -9,7 +9,7 @@
// - isis agora lovecruft <isis@patternsinthevoid.net>
// - Henry de Valence <hdevalence@hdevalence.ca>
//! 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;

2
src/backend/serial/curve_models/mod.rs
View file

@ -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,

2
src/backend/serial/scalar_mul/mod.rs
View file

@ -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")]

3
src/backend/serial/scalar_mul/pippenger.rs
View file

@ -61,7 +61,8 @@ use crate::prelude::*;
/// This algorithm is adapted from section 4 of <https://eprint.iacr.org/2012/549.pdf>.
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;

1
src/backend/serial/scalar_mul/precomputed_straus.rs
View file

@ -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<NafLookupTable8<AffineNielsPoint>>,
}

2
src/backend/vector/ifma/mod.rs
View file

@ -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;

12
src/backend/vector/mod.rs
View file

@ -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;

3
src/backend/vector/scalar_mul/mod.rs
View file

@ -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;

3
src/backend/vector/scalar_mul/pippenger.rs
View file

@ -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;

10
src/edwards.rs
View file

@ -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;

1
src/field.rs
View file

@ -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

14
src/lib.rs
View file

@ -10,16 +10,16 @@
// - Henry de Valence <hdevalence@hdevalence.ca>
#![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

7
src/ristretto.rs
View file

@ -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<CompressedRistretto>
where
I: IntoIterator<Item = &'a RistrettoPoint>,
@ -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;

13
src/scalar.rs
View file

@ -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<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
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<D>(deserializer: D) -> Result<Self, D::Error>
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,