Skip to content

Commit

Permalink
Documentation improvements (#475)
Browse files Browse the repository at this point in the history 
- Use `doc = include_str!` attribute to include README.md
- Add documentation for `serde` features
  • Loading branch information
@tarcieri
tarcieri committed Dec 4, 2021
1 parent 6942b22 commit 79c0963
Show file tree
Hide file tree
Showing 11 changed files with 80 additions and 106 deletions.
10 changes: 1 addition & 9 deletions bp256/src/lib.rs
View file
@@ -1,14 +1,6 @@
//! Brainpool P-256 elliptic curves: brainpoolP256r1 and brainpoolP256t1
//!
//! ## Minimum Supported Rust Version
//!
//! Rust **1.56** or higher.
//!
//! Minimum supported Rust version may be changed in the future, but it will be
//! accompanied with a minor version bump.

#![no_std]
#![cfg_attr(docsrs, feature(doc_cfg))]
#![doc = include_str!("../README.md")]
#![doc(
html_logo_url = "https://raw.githubusercontent.com/RustCrypto/meta/master/logo.svg",
html_favicon_url = "https://raw.githubusercontent.com/RustCrypto/meta/master/logo.svg",
Expand Down
10 changes: 1 addition & 9 deletions bp384/src/lib.rs
View file
@@ -1,14 +1,6 @@
//! Brainpool P-384 elliptic curves: brainpoolP384r1 and brainpoolP384t1
//!
//! ## Minimum Supported Rust Version
//!
//! Rust **1.56** or higher.
//!
//! Minimum supported Rust version may be changed in the future, but it will be
//! accompanied with a minor version bump.

#![no_std]
#![cfg_attr(docsrs, feature(doc_cfg))]
#![doc = include_str!("../README.md")]
#![doc(
html_logo_url = "https://raw.githubusercontent.com/RustCrypto/meta/master/logo.svg",
html_favicon_url = "https://raw.githubusercontent.com/RustCrypto/meta/master/logo.svg",
Expand Down
3 changes: 2 additions & 1 deletion k256/README.md
View file
@@ -1,4 +1,4 @@
# RustCrypto: secp256k1 (K-256) elliptic curve
# [RustCrypto]: secp256k1 (K-256) elliptic curve

[![crate][crate-image]][crate-link]
[![Docs][docs-image]][docs-link]
Expand Down Expand Up @@ -103,6 +103,7 @@ dual licensed as above, without any additional terms or conditions.

[//]: # (general links)

[RustCrypto]: https://github.com/RustCrypto/
[secp256k1]: https://en.bitcoin.it/wiki/Secp256k1
[`elliptic-curve`]: https://github.com/RustCrypto/traits/tree/master/elliptic-curve
[`arithmetic`]: https://docs.rs/k256/latest/k256/arithmetic/index.html
Expand Down
15 changes: 14 additions & 1 deletion k256/src/arithmetic/affine.rs
View file
Expand Up @@ -19,7 +19,20 @@ impl AffineArithmetic for Secp256k1 {
#[cfg(feature = "serde")]
use elliptic_curve::serde::{de, ser, Deserialize, Serialize};

/// A point on the secp256k1 curve in affine coordinates.
/// secp256k1 curve point expressed in affine coordinates.
///
/// # `serde` support
///
/// When the `serde` feature of this crate is enabled, the `Serialize` and
/// `Deserialize` traits are impl'd for this type.
///
/// The serialization uses the [SEC1] `Elliptic-Curve-Point-to-Octet-String`
/// encoding, serialized as binary.
///
/// When serialized with a text-based format, the SEC1 representation is
/// subsequently hex encoded.
///
/// [SEC1]: https://www.secg.org/sec1-v2.pdf
#[derive(Clone, Copy, Debug)]
#[cfg_attr(docsrs, doc(cfg(feature = "arithmetic")))]
pub struct AffinePoint {
Expand Down
10 changes: 9 additions & 1 deletion k256/src/arithmetic/scalar.rs
View file
Expand Up @@ -65,6 +65,14 @@ const FRAC_MODULUS_2: U256 = ORDER.shr_vartime(1);
/// operations over field elements represented as bits (requires `bits` feature)
///
/// Please see the documentation for the relevant traits for more information.
///
/// # `serde` support
///
/// When the `serde` feature of this crate is enabled, the `Serialize` and
/// `Deserialize` traits are impl'd for this type.
///
/// The serialization is a fixed-width big endian encoding. When used with
/// textual formats, the binary data is encoded as hexadecimal.
#[derive(Clone, Copy, Debug, Default)]
#[cfg_attr(docsrs, doc(cfg(feature = "arithmetic")))]
pub struct Scalar(U256);
Expand Down Expand Up @@ -106,7 +114,7 @@ impl Field for Scalar {
}

/// Tonelli-Shank's algorithm for q mod 16 = 1
/// https://eprint.iacr.org/2012/685.pdf (page 12, algorithm 5)
/// <https://eprint.iacr.org/2012/685.pdf> (page 12, algorithm 5)
#[allow(clippy::many_single_char_names)]
fn sqrt(&self) -> CtOption<Self> {
// Note: `pow_vartime` is constant-time with respect to `self`
Expand Down
11 changes: 11 additions & 0 deletions k256/src/ecdsa/verify.rs
View file
Expand Up @@ -29,6 +29,17 @@ use core::str::FromStr;
use elliptic_curve::serde::{de, ser, Deserialize, Serialize};

/// ECDSA/secp256k1 verification key (i.e. public key)
///
/// # `serde` support
///
/// When the `serde` feature of this crate is enabled, the `Serialize` and
/// `Deserialize` traits are impl'd for this type.
///
/// The serialization is binary-oriented and supports ASN.1 DER-encoded
/// X.509 Subject Public Key Info (SPKI) as the encoding format.
///
/// For a more text-friendly encoding of public keys, use
/// [`elliptic_curve::JwkEcKey`] instead.
#[cfg_attr(docsrs, doc(cfg(feature = "ecdsa")))]
#[derive(Copy, Clone, Debug, Eq, PartialEq, PartialOrd, Ord)]
pub struct VerifyingKey {
Expand Down
46 changes: 9 additions & 37 deletions k256/src/lib.rs
View file
@@ -1,43 +1,15 @@
//! Pure Rust implementation of the [secp256k1] (K-256) elliptic curve,
//! including support for the
//! [Elliptic Curve Digital Signature Algorithm (ECDSA)][ECDSA],
//! [Elliptic Curve Diffie-Hellman (ECDH)][ECDH], and general purpose
//! elliptic curve/field arithmetic which can be used to implement
//! protocols based on group operations.
//!
//! ## About secp256k1 (K-256)
//!
//! secp256k1 is a Koblitz curve commonly used in cryptocurrency applications.
//! The "K-256" name follows NIST notation where P = prime fields,
//! B = binary fields, and K = Koblitz curves.
//!
//! The curve is specified as `secp256k1` by Certicom's SECG in
//! "SEC 2: Recommended Elliptic Curve Domain Parameters":
//!
//! <https://www.secg.org/sec2-v2.pdf>
//!
//! ## ⚠️ Security Warning
//!
//! The elliptic curve arithmetic contained in this crate has never been
//! independently audited!
//!
//! This crate has been designed with the goal of ensuring that secret-dependent
//! operations are performed in constant time (using the `subtle` crate and
//! constant-time formulas). However, it has not been thoroughly assessed to ensure
//! that generated assembly is constant time on common CPU architectures.
//!
//! USE AT YOUR OWN RISK!
//!
//! ## Minimum Supported Rust Version
#![doc = include_str!("../README.md")]

//! ## `serde` support
//!
//! Rust **1.56** or higher.
//! When the `serde` feature of this crate is enabled, `Serialize` and
//! `Deserialize` are impl'd for the following types:
//!
//! Minimum supported Rust version may be changed in the future, but it will be
//! accompanied with a minor version bump.
//! - [`AffinePoint`]
//! - [`Scalar`]
//! - [`ecdsa::VerifyingKey`]
//!
//! [secp256k1]: https://en.bitcoin.it/wiki/Secp256k1
//! [ECDSA]: https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm
//! [ECDH]: https://en.wikipedia.org/wiki/Elliptic-curve_Diffie%E2%80%93Hellman
//! Please see type-specific documentation for more information.

#![no_std]
#![cfg_attr(docsrs, feature(doc_cfg))]
Expand Down
15 changes: 14 additions & 1 deletion p256/src/arithmetic/affine.rs
View file
Expand Up @@ -21,7 +21,20 @@ impl AffineArithmetic for NistP256 {
type AffinePoint = AffinePoint;
}

/// A point on the secp256r1 curve in affine coordinates.
/// NIST P-256 (secp256r1) curve point expressed in affine coordinates.
///
/// # `serde` support
///
/// When the `serde` feature of this crate is enabled, the `Serialize` and
/// `Deserialize` traits are impl'd for this type.
///
/// The serialization uses the [SEC1] `Elliptic-Curve-Point-to-Octet-String`
/// encoding, serialized as binary.
///
/// When serialized with a text-based format, the SEC1 representation is
/// subsequently hex encoded.
///
/// [SEC1]: https://www.secg.org/sec1-v2.pdf
#[derive(Clone, Copy, Debug)]
#[cfg_attr(docsrs, doc(cfg(feature = "arithmetic")))]
pub struct AffinePoint {
Expand Down
10 changes: 9 additions & 1 deletion p256/src/arithmetic/scalar.rs
View file
Expand Up @@ -75,6 +75,14 @@ impl ScalarArithmetic for NistP256 {
/// operations over field elements represented as bits (requires `bits` feature)
///
/// Please see the documentation for the relevant traits for more information.
///
/// # `serde` support
///
/// When the `serde` feature of this crate is enabled, the `Serialize` and
/// `Deserialize` traits are impl'd for this type.
///
/// The serialization is a fixed-width big endian encoding. When used with
/// textual formats, the binary data is encoded as hexadecimal.
#[derive(Clone, Copy, Debug, Default)]
#[cfg_attr(docsrs, doc(cfg(feature = "arithmetic")))]
pub struct Scalar(pub(crate) U256);
Expand Down Expand Up @@ -123,7 +131,7 @@ impl Field for Scalar {
}

/// Tonelli-Shank's algorithm for q mod 16 = 1
/// https://eprint.iacr.org/2012/685.pdf (page 12, algorithm 5)
/// <https://eprint.iacr.org/2012/685.pdf> (page 12, algorithm 5)
#[allow(clippy::many_single_char_names)]
fn sqrt(&self) -> CtOption<Self> {
// Note: `pow_vartime` is constant-time with respect to `self`
Expand Down
46 changes: 9 additions & 37 deletions p256/src/lib.rs
View file
@@ -1,43 +1,15 @@
//! Pure Rust implementation of the NIST P-256 elliptic curve,
//! including support for the
//! [Elliptic Curve Digital Signature Algorithm (ECDSA)][ECDSA],
//! [Elliptic Curve Diffie-Hellman (ECDH)][ECDH], and general purpose
//! elliptic curve/field arithmetic which can be used to implement
//! protocols based on group operations.
//!
//! ## About NIST P-256
//!
//! NIST P-256 is a Weierstrass curve specified in FIPS 186-4:
//! Digital Signature Standard (DSS):
//!
//! <https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf>
//!
//! Also known as `prime256v1` (ANSI X9.62) and `secp256r1` (SECG), P-256 is
//! included in the US National Security Agency's "Suite B" and is widely used
//! in Internet and connected device protocols like TLS, the X.509 PKI, and
//! Bluetooth.
//!
//! ## ⚠️ Security Warning
//!
//! The elliptic curve arithmetic contained in this crate has never been
//! independently audited!
//!
//! This crate has been designed with the goal of ensuring that secret-dependent
//! operations are performed in constant time (using the `subtle` crate and
//! constant-time formulas). However, it has not been thoroughly assessed to ensure
//! that generated assembly is constant time on common CPU architectures.
//!
//! USE AT YOUR OWN RISK!
//!
//! ## Minimum Supported Rust Version
#![doc = include_str!("../README.md")]

//! ## `serde` support
//!
//! Rust **1.56** or higher.
//! When the `serde` feature of this crate is enabled, `Serialize` and
//! `Deserialize` are impl'd for the following types:
//!
//! Minimum supported Rust version may be changed in the future, but it will be
//! accompanied with a minor version bump.
//! - [`AffinePoint`]
//! - [`Scalar`]
//! - [`ecdsa::VerifyingKey`]
//!
//! [ECDSA]: https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm
//! [ECDH]: https://en.wikipedia.org/wiki/Elliptic-curve_Diffie%E2%80%93Hellman
//! Please see type-specific documentation for more information.

#![no_std]
#![cfg_attr(docsrs, feature(doc_cfg))]
Expand Down
10 changes: 1 addition & 9 deletions p384/src/lib.rs
View file
@@ -1,14 +1,6 @@
//! NIST P-384 elliptic curve (a.k.a. secp384r1)
//!
//! ## Minimum Supported Rust Version
//!
//! Rust **1.56** or higher.
//!
//! Minimum supported Rust version may be changed in the future, but it will be
//! accompanied with a minor version bump.

#![no_std]
#![cfg_attr(docsrs, feature(doc_cfg))]
#![doc = include_str!("../README.md")]
#![doc(
html_logo_url = "https://raw.githubusercontent.com/RustCrypto/meta/master/logo.svg",
html_favicon_url = "https://raw.githubusercontent.com/RustCrypto/meta/master/logo.svg",
Expand Down

0 comments on commit 79c0963

Please sign in to comment.