From 4abe7fe638968bf84c774b929eec45102c0a8438 Mon Sep 17 00:00:00 2001 From: Conrado Gouvea Date: Mon, 4 Sep 2023 16:38:48 -0300 Subject: [PATCH] document features (#512) --- frost-core/Cargo.toml | 12 ++++++++++-- frost-core/src/frost.rs | 5 +++++ frost-core/src/frost/round1.rs | 1 + frost-core/src/frost/round2.rs | 2 ++ frost-core/src/lib.rs | 7 ++++++- frost-ed25519/Cargo.toml | 8 +++++++- frost-ed25519/src/lib.rs | 3 +++ frost-ed448/Cargo.toml | 8 +++++++- frost-ed448/src/lib.rs | 3 +++ frost-p256/Cargo.toml | 8 +++++++- frost-p256/src/lib.rs | 3 +++ frost-rerandomized/Cargo.toml | 8 +++++++- frost-ristretto255/Cargo.toml | 8 +++++++- frost-secp256k1/Cargo.toml | 8 +++++++- frost-secp256k1/src/lib.rs | 3 +++ 15 files changed, 78 insertions(+), 9 deletions(-) diff --git a/frost-core/Cargo.toml b/frost-core/Cargo.toml index b7cf0aa..f67f036 100644 --- a/frost-core/Cargo.toml +++ b/frost-core/Cargo.toml @@ -18,10 +18,12 @@ keywords = ["cryptography", "crypto", "threshold", "signature", "schnorr"] description = "Types and traits to support implementing Flexible Round-Optimized Schnorr Threshold signature schemes (FROST)." [package.metadata.docs.rs] -features = ["nightly"] +features = ["serde"] +rustdoc-args = ["--cfg", "docsrs"] [dependencies] byteorder = "1.4" +document-features = "0.2.7" debugless-unwrap = "0.0.4" derive-getters = "0.3.0" hex = "0.4.3" @@ -46,9 +48,15 @@ rand_chacha = "0.3" serde_json = "1.0" [features] -nightly = [] default = [] +#! ## Features +## Expose internal types, which do not have SemVer guarantees. This is an advanced +## feature which can be useful if you need to build a modified version of FROST. +## The docs won't list them, you will need to check the source code. internals = [] +## Enable `serde` support for types that need to be communicated. You +## can use `serde` to serialize structs with any encoder that supports +## `serde` (e.g. JSON with `serde_json`). serde = ["dep:serde", "dep:serdect"] # Exposes ciphersuite-generic tests for other crates to use test-impl = ["proptest", "serde_json", "criterion"] diff --git a/frost-core/src/frost.rs b/frost-core/src/frost.rs index cd5f000..f1ea47e 100644 --- a/frost-core/src/frost.rs +++ b/frost-core/src/frost.rs @@ -97,6 +97,7 @@ where /// /// [`compute_binding_factors`]: https://www.ietf.org/archive/id/draft-irtf-cfrg-frost-14.html#section-4.4 #[cfg_attr(feature = "internals", visibility::make(pub))] +#[cfg_attr(docsrs, doc(cfg(feature = "internals")))] pub(crate) fn compute_binding_factor_list( signing_package: &SigningPackage, group_public: &VerifyingKey, @@ -146,6 +147,7 @@ where /// /// If `x` is None, it uses 0 for it (since Identifiers can't be 0) #[cfg_attr(feature = "internals", visibility::make(pub))] +#[cfg_attr(docsrs, doc(cfg(feature = "internals")))] fn compute_lagrange_coefficient( x_set: &BTreeSet>, x: Option>, @@ -190,6 +192,7 @@ fn compute_lagrange_coefficient( /// /// [`derive_interpolating_value()`]: https://www.ietf.org/archive/id/draft-irtf-cfrg-frost-14.html#name-polynomials #[cfg_attr(feature = "internals", visibility::make(pub))] +#[cfg_attr(docsrs, doc(cfg(feature = "internals")))] fn derive_interpolating_value( signer_id: &Identifier, signing_package: &SigningPackage, @@ -268,6 +271,7 @@ where /// Compute the preimages to H1 to compute the per-signer binding factors // We separate this out into its own method so it can be tested #[cfg_attr(feature = "internals", visibility::make(pub))] + #[cfg_attr(docsrs, doc(cfg(feature = "internals")))] pub fn binding_factor_preimages( &self, group_public: &VerifyingKey, @@ -325,6 +329,7 @@ where /// /// [`compute_group_commitment`]: https://www.ietf.org/archive/id/draft-irtf-cfrg-frost-14.html#section-4.5 #[cfg_attr(feature = "internals", visibility::make(pub))] +#[cfg_attr(docsrs, doc(cfg(feature = "internals")))] fn compute_group_commitment( signing_package: &SigningPackage, binding_factor_list: &BindingFactorList, diff --git a/frost-core/src/frost/round1.rs b/frost-core/src/frost/round1.rs index 47d3544..7ce34c2 100644 --- a/frost-core/src/frost/round1.rs +++ b/frost-core/src/frost/round1.rs @@ -302,6 +302,7 @@ where /// /// [signature commitment share]: https://www.ietf.org/archive/id/draft-irtf-cfrg-frost-14.html#name-signature-share-verificatio #[cfg_attr(feature = "internals", visibility::make(pub))] + #[cfg_attr(docsrs, doc(cfg(feature = "internals")))] pub(super) fn to_group_commitment_share( self, binding_factor: &frost::BindingFactor, diff --git a/frost-core/src/frost/round2.rs b/frost-core/src/frost/round2.rs index 2272477..55d72b2 100644 --- a/frost-core/src/frost/round2.rs +++ b/frost-core/src/frost/round2.rs @@ -81,6 +81,7 @@ where /// /// [`verify_signature_share`]: https://www.ietf.org/archive/id/draft-irtf-cfrg-frost-14.html#name-signature-share-verificatio #[cfg_attr(feature = "internals", visibility::make(pub))] + #[cfg_attr(docsrs, doc(cfg(feature = "internals")))] pub(crate) fn verify( &self, identifier: Identifier, @@ -156,6 +157,7 @@ where /// Compute the signature share for a signing operation. #[cfg_attr(feature = "internals", visibility::make(pub))] +#[cfg_attr(docsrs, doc(cfg(feature = "internals")))] fn compute_signature_share( signer_nonces: &round1::SigningNonces, binding_factor: BindingFactor, diff --git a/frost-core/src/lib.rs b/frost-core/src/lib.rs index bb4d928..de02aaa 100644 --- a/frost-core/src/lib.rs +++ b/frost-core/src/lib.rs @@ -2,10 +2,13 @@ // It's emitting false positives; see https://github.com/rust-lang/rust-clippy/issues/9413 #![allow(clippy::derive_partial_eq_without_eq)] #![deny(missing_docs)] -#![doc = include_str!("../README.md")] #![forbid(unsafe_code)] #![deny(clippy::indexing_slicing)] #![deny(clippy::unwrap_used)] +#![cfg_attr(docsrs, feature(doc_auto_cfg))] +#![cfg_attr(docsrs, feature(doc_cfg))] +#![doc = include_str!("../README.md")] +#![doc = document_features::document_features!()] use std::{ default::Default, @@ -98,6 +101,7 @@ pub type Scalar = <<::Group as Group>::Field as Field>::Sca #[cfg(feature = "serde")] #[cfg_attr(feature = "internals", visibility::make(pub))] +#[cfg_attr(docsrs, doc(cfg(feature = "internals")))] /// Helper struct to serialize a Scalar. pub(crate) struct ScalarSerialization( pub <<::Group as Group>::Field as Field>::Serialization, @@ -374,6 +378,7 @@ where /// [FROST]: https://www.ietf.org/archive/id/draft-irtf-cfrg-frost-14.html#name-signature-challenge-computa /// [RFC]: https://www.ietf.org/archive/id/draft-irtf-cfrg-frost-14.html#section-3.2 #[cfg_attr(feature = "internals", visibility::make(pub))] +#[cfg_attr(docsrs, doc(cfg(feature = "internals")))] fn challenge(R: &Element, verifying_key: &Element, msg: &[u8]) -> Challenge where C: Ciphersuite, diff --git a/frost-ed25519/Cargo.toml b/frost-ed25519/Cargo.toml index c45a444..3f4b837 100644 --- a/frost-ed25519/Cargo.toml +++ b/frost-ed25519/Cargo.toml @@ -19,10 +19,12 @@ keywords = ["cryptography", "crypto", "ed25519", "threshold", "signature"] description = "A Schnorr signature scheme over Ed25519 that supports FROST." [package.metadata.docs.rs] -features = ["nightly"] +features = ["serde"] +rustdoc-args = ["--cfg", "docsrs"] [dependencies] curve25519-dalek = { version = "=4.0.0", features = ["rand_core"] } +document-features = "0.2.7" frost-core = { path = "../frost-core", version = "0.6.0" } rand_core = "0.6" sha2 = "0.10.2" @@ -42,6 +44,10 @@ serde_json = "1.0" [features] nightly = [] default = [] +#! ## Features +## Enable `serde` support for types that need to be communicated. You +## can use `serde` to serialize structs with any encoder that supports +## `serde` (e.g. JSON with `serde_json`). serde = ["frost-core/serde"] [lib] diff --git a/frost-ed25519/src/lib.rs b/frost-ed25519/src/lib.rs index e199d5f..bfa982f 100644 --- a/frost-ed25519/src/lib.rs +++ b/frost-ed25519/src/lib.rs @@ -1,6 +1,9 @@ #![allow(non_snake_case)] #![deny(missing_docs)] +#![cfg_attr(docsrs, feature(doc_auto_cfg))] +#![cfg_attr(docsrs, feature(doc_cfg))] #![doc = include_str!("../README.md")] +#![doc = document_features::document_features!()] use std::collections::HashMap; diff --git a/frost-ed448/Cargo.toml b/frost-ed448/Cargo.toml index af918d1..32ef230 100644 --- a/frost-ed448/Cargo.toml +++ b/frost-ed448/Cargo.toml @@ -18,9 +18,11 @@ keywords = ["cryptography", "crypto", "ed448", "threshold", "signature"] description = "A Schnorr signature scheme over Ed448 that supports FROST." [package.metadata.docs.rs] -features = ["nightly"] +features = ["serde"] +rustdoc-args = ["--cfg", "docsrs"] [dependencies] +document-features = "0.2.7" ed448-goldilocks = { version = "0.9.0" } frost-core = { path = "../frost-core", version = "0.6.0" } rand_core = "0.6" @@ -40,6 +42,10 @@ serde_json = "1.0" [features] nightly = [] default = [] +#! ## Features +## Enable `serde` support for types that need to be communicated. You +## can use `serde` to serialize structs with any encoder that supports +## `serde` (e.g. JSON with `serde_json`). serde = ["frost-core/serde"] [lib] diff --git a/frost-ed448/src/lib.rs b/frost-ed448/src/lib.rs index 78188c4..d62f818 100644 --- a/frost-ed448/src/lib.rs +++ b/frost-ed448/src/lib.rs @@ -1,6 +1,9 @@ #![allow(non_snake_case)] #![deny(missing_docs)] +#![cfg_attr(docsrs, feature(doc_auto_cfg))] +#![cfg_attr(docsrs, feature(doc_cfg))] #![doc = include_str!("../README.md")] +#![doc = document_features::document_features!()] use std::collections::HashMap; diff --git a/frost-p256/Cargo.toml b/frost-p256/Cargo.toml index d5f9d3a..36c6084 100644 --- a/frost-p256/Cargo.toml +++ b/frost-p256/Cargo.toml @@ -19,9 +19,11 @@ keywords = ["cryptography", "crypto", "threshold", "signature"] description = "A Schnorr signature scheme over the NIST P-256 curve that supports FROST." [package.metadata.docs.rs] -features = ["nightly"] +features = ["serde"] +rustdoc-args = ["--cfg", "docsrs"] [dependencies] +document-features = "0.2.7" p256 = { version = "0.13.0", features = ["hash2curve"] } frost-core = { path = "../frost-core", version = "0.6.0" } rand_core = "0.6" @@ -41,6 +43,10 @@ serde_json = "1.0" [features] nightly = [] default = [] +#! ## Features +## Enable `serde` support for types that need to be communicated. You +## can use `serde` to serialize structs with any encoder that supports +## `serde` (e.g. JSON with `serde_json`). serde = ["frost-core/serde"] [lib] diff --git a/frost-p256/src/lib.rs b/frost-p256/src/lib.rs index 84e62a0..7e3a90b 100644 --- a/frost-p256/src/lib.rs +++ b/frost-p256/src/lib.rs @@ -1,6 +1,9 @@ #![allow(non_snake_case)] #![deny(missing_docs)] +#![cfg_attr(docsrs, feature(doc_auto_cfg))] +#![cfg_attr(docsrs, feature(doc_cfg))] #![doc = include_str!("../README.md")] +#![doc = document_features::document_features!()] use std::collections::HashMap; diff --git a/frost-rerandomized/Cargo.toml b/frost-rerandomized/Cargo.toml index 2cf2c42..7fabf5f 100644 --- a/frost-rerandomized/Cargo.toml +++ b/frost-rerandomized/Cargo.toml @@ -16,10 +16,12 @@ keywords = ["cryptography", "threshold", "signature", "schnorr", "randomized"] description = "Types and traits to support implementing a re-randomized variant of Flexible Round-Optimized Schnorr Threshold signature schemes (FROST)." [package.metadata.docs.rs] -features = ["nightly"] +features = ["serde"] +rustdoc-args = ["--cfg", "docsrs"] [dependencies] derive-getters = "0.3.0" +document-features = "0.2.7" frost-core = { path = "../frost-core", version = "0.6.0", features = ["internals"] } rand_core = "0.6" @@ -28,6 +30,10 @@ rand_core = "0.6" [features] nightly = [] default = [] +#! ## Features +## Enable `serde` support for types that need to be communicated. You +## can use `serde` to serialize structs with any encoder that supports +## `serde` (e.g. JSON with `serde_json`). serde = ["frost-core/serde"] # Exposes ciphersuite-generic tests for other crates to use test-impl = ["frost-core/test-impl"] diff --git a/frost-ristretto255/Cargo.toml b/frost-ristretto255/Cargo.toml index 31f87a6..8033566 100644 --- a/frost-ristretto255/Cargo.toml +++ b/frost-ristretto255/Cargo.toml @@ -15,10 +15,12 @@ keywords = ["cryptography", "crypto", "ristretto", "threshold", "signature"] description = "A Schnorr signature scheme over the prime-order Ristretto group that supports FROST." [package.metadata.docs.rs] -features = ["nightly"] +features = ["serde"] +rustdoc-args = ["--cfg", "docsrs"] [dependencies] curve25519-dalek = { version = "=4.0.0", features = ["serde", "rand_core"] } +document-features = "0.2.7" frost-core = { path = "../frost-core", version = "0.6.0" } rand_core = "0.6" sha2 = "0.10.2" @@ -37,6 +39,10 @@ serde_json = "1.0" [features] nightly = [] default = [] +#! ## Features +## Enable `serde` support for types that need to be communicated. You +## can use `serde` to serialize structs with any encoder that supports +## `serde` (e.g. JSON with `serde_json`). serde = ["frost-core/serde"] [lib] diff --git a/frost-secp256k1/Cargo.toml b/frost-secp256k1/Cargo.toml index 82dbfc0..5ddc5c6 100644 --- a/frost-secp256k1/Cargo.toml +++ b/frost-secp256k1/Cargo.toml @@ -18,9 +18,11 @@ keywords = ["cryptography", "crypto", "threshold", "signature"] description = "A Schnorr signature scheme over the secp256k1 curve that supports FROST." [package.metadata.docs.rs] -features = ["nightly"] +features = ["serde"] +rustdoc-args = ["--cfg", "docsrs"] [dependencies] +document-features = "0.2.7" frost-core = { path = "../frost-core", version = "0.6.0" } k256 = { version = "0.13.0", features = ["arithmetic", "expose-field", "hash2curve"] } rand_core = "0.6" @@ -40,6 +42,10 @@ serde_json = "1.0" [features] nightly = [] default = [] +#! ## Features +## Enable `serde` support for types that need to be communicated. You +## can use `serde` to serialize structs with any encoder that supports +## `serde` (e.g. JSON with `serde_json`). serde = ["frost-core/serde"] [lib] diff --git a/frost-secp256k1/src/lib.rs b/frost-secp256k1/src/lib.rs index 794a8e7..a7a6edb 100644 --- a/frost-secp256k1/src/lib.rs +++ b/frost-secp256k1/src/lib.rs @@ -1,6 +1,9 @@ #![allow(non_snake_case)] #![deny(missing_docs)] +#![cfg_attr(docsrs, feature(doc_auto_cfg))] +#![cfg_attr(docsrs, feature(doc_cfg))] #![doc = include_str!("../README.md")] +#![doc = document_features::document_features!()] use std::collections::HashMap;