Skip to content

Commit 79c0963

Browse files
tarcieritarcieri
authored
Documentation improvements (#475)
- Use `doc = include_str!` attribute to include README.md - Add documentation for `serde` features
1 parent 6942b22 commit 79c0963

File tree

11 files changed

+80
-106
lines changed

11 files changed

+80
-106
lines changed

‎bp256/src/lib.rs‎

Lines changed: 1 addition & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,6 @@
1-
//! Brainpool P-256 elliptic curves: brainpoolP256r1 and brainpoolP256t1
2-
//!
3-
//! ## Minimum Supported Rust Version
4-
//!
5-
//! Rust **1.56** or higher.
6-
//!
7-
//! Minimum supported Rust version may be changed in the future, but it will be
8-
//! accompanied with a minor version bump.
9-
101
#![no_std]
112
#![cfg_attr(docsrs, feature(doc_cfg))]
3+
#![doc = include_str!("../README.md")]
124
#![doc(
135
html_logo_url = "https://raw.githubusercontent.com/RustCrypto/meta/master/logo.svg",
146
html_favicon_url = "https://raw.githubusercontent.com/RustCrypto/meta/master/logo.svg",

‎bp384/src/lib.rs‎

Lines changed: 1 addition & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,6 @@
1-
//! Brainpool P-384 elliptic curves: brainpoolP384r1 and brainpoolP384t1
2-
//!
3-
//! ## Minimum Supported Rust Version
4-
//!
5-
//! Rust **1.56** or higher.
6-
//!
7-
//! Minimum supported Rust version may be changed in the future, but it will be
8-
//! accompanied with a minor version bump.
9-
101
#![no_std]
112
#![cfg_attr(docsrs, feature(doc_cfg))]
3+
#![doc = include_str!("../README.md")]
124
#![doc(
135
html_logo_url = "https://raw.githubusercontent.com/RustCrypto/meta/master/logo.svg",
146
html_favicon_url = "https://raw.githubusercontent.com/RustCrypto/meta/master/logo.svg",

‎k256/README.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# RustCrypto: secp256k1 (K-256) elliptic curve
1+
# [RustCrypto]: secp256k1 (K-256) elliptic curve
22

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

104104
[//]: # (general links)
105105

106+
[RustCrypto]: https://github.com/RustCrypto/
106107
[secp256k1]: https://en.bitcoin.it/wiki/Secp256k1
107108
[`elliptic-curve`]: https://github.com/RustCrypto/traits/tree/master/elliptic-curve
108109
[`arithmetic`]: https://docs.rs/k256/latest/k256/arithmetic/index.html

‎k256/src/arithmetic/affine.rs‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,20 @@ impl AffineArithmetic for Secp256k1 {
1919
#[cfg(feature = "serde")]
2020
use elliptic_curve::serde::{de, ser, Deserialize, Serialize};
2121

22-
/// A point on the secp256k1 curve in affine coordinates.
22+
/// secp256k1 curve point expressed in affine coordinates.
23+
///
24+
/// # `serde` support
25+
///
26+
/// When the `serde` feature of this crate is enabled, the `Serialize` and
27+
/// `Deserialize` traits are impl'd for this type.
28+
///
29+
/// The serialization uses the [SEC1] `Elliptic-Curve-Point-to-Octet-String`
30+
/// encoding, serialized as binary.
31+
///
32+
/// When serialized with a text-based format, the SEC1 representation is
33+
/// subsequently hex encoded.
34+
///
35+
/// [SEC1]: https://www.secg.org/sec1-v2.pdf
2336
#[derive(Clone, Copy, Debug)]
2437
#[cfg_attr(docsrs, doc(cfg(feature = "arithmetic")))]
2538
pub struct AffinePoint {

‎k256/src/arithmetic/scalar.rs‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,14 @@ const FRAC_MODULUS_2: U256 = ORDER.shr_vartime(1);
6565
/// operations over field elements represented as bits (requires `bits` feature)
6666
///
6767
/// Please see the documentation for the relevant traits for more information.
68+
///
69+
/// # `serde` support
70+
///
71+
/// When the `serde` feature of this crate is enabled, the `Serialize` and
72+
/// `Deserialize` traits are impl'd for this type.
73+
///
74+
/// The serialization is a fixed-width big endian encoding. When used with
75+
/// textual formats, the binary data is encoded as hexadecimal.
6876
#[derive(Clone, Copy, Debug, Default)]
6977
#[cfg_attr(docsrs, doc(cfg(feature = "arithmetic")))]
7078
pub struct Scalar(U256);
@@ -106,7 +114,7 @@ impl Field for Scalar {
106114
}
107115

108116
/// Tonelli-Shank's algorithm for q mod 16 = 1
109-
/// https://eprint.iacr.org/2012/685.pdf (page 12, algorithm 5)
117+
/// <https://eprint.iacr.org/2012/685.pdf> (page 12, algorithm 5)
110118
#[allow(clippy::many_single_char_names)]
111119
fn sqrt(&self) -> CtOption<Self> {
112120
// Note: `pow_vartime` is constant-time with respect to `self`

‎k256/src/ecdsa/verify.rs‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,17 @@ use core::str::FromStr;
2929
use elliptic_curve::serde::{de, ser, Deserialize, Serialize};
3030

3131
/// ECDSA/secp256k1 verification key (i.e. public key)
32+
///
33+
/// # `serde` support
34+
///
35+
/// When the `serde` feature of this crate is enabled, the `Serialize` and
36+
/// `Deserialize` traits are impl'd for this type.
37+
///
38+
/// The serialization is binary-oriented and supports ASN.1 DER-encoded
39+
/// X.509 Subject Public Key Info (SPKI) as the encoding format.
40+
///
41+
/// For a more text-friendly encoding of public keys, use
42+
/// [`elliptic_curve::JwkEcKey`] instead.
3243
#[cfg_attr(docsrs, doc(cfg(feature = "ecdsa")))]
3344
#[derive(Copy, Clone, Debug, Eq, PartialEq, PartialOrd, Ord)]
3445
pub struct VerifyingKey {

‎k256/src/lib.rs‎

Lines changed: 9 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,43 +1,15 @@
1-
//! Pure Rust implementation of the [secp256k1] (K-256) elliptic curve,
2-
//! including support for the
3-
//! [Elliptic Curve Digital Signature Algorithm (ECDSA)][ECDSA],
4-
//! [Elliptic Curve Diffie-Hellman (ECDH)][ECDH], and general purpose
5-
//! elliptic curve/field arithmetic which can be used to implement
6-
//! protocols based on group operations.
7-
//!
8-
//! ## About secp256k1 (K-256)
9-
//!
10-
//! secp256k1 is a Koblitz curve commonly used in cryptocurrency applications.
11-
//! The "K-256" name follows NIST notation where P = prime fields,
12-
//! B = binary fields, and K = Koblitz curves.
13-
//!
14-
//! The curve is specified as `secp256k1` by Certicom's SECG in
15-
//! "SEC 2: Recommended Elliptic Curve Domain Parameters":
16-
//!
17-
//! <https://www.secg.org/sec2-v2.pdf>
18-
//!
19-
//! ## ⚠️ Security Warning
20-
//!
21-
//! The elliptic curve arithmetic contained in this crate has never been
22-
//! independently audited!
23-
//!
24-
//! This crate has been designed with the goal of ensuring that secret-dependent
25-
//! operations are performed in constant time (using the `subtle` crate and
26-
//! constant-time formulas). However, it has not been thoroughly assessed to ensure
27-
//! that generated assembly is constant time on common CPU architectures.
28-
//!
29-
//! USE AT YOUR OWN RISK!
30-
//!
31-
//! ## Minimum Supported Rust Version
1+
#![doc = include_str!("../README.md")]
2+
3+
//! ## `serde` support
324
//!
33-
//! Rust **1.56** or higher.
5+
//! When the `serde` feature of this crate is enabled, `Serialize` and
6+
//! `Deserialize` are impl'd for the following types:
347
//!
35-
//! Minimum supported Rust version may be changed in the future, but it will be
36-
//! accompanied with a minor version bump.
8+
//! - [`AffinePoint`]
9+
//! - [`Scalar`]
10+
//! - [`ecdsa::VerifyingKey`]
3711
//!
38-
//! [secp256k1]: https://en.bitcoin.it/wiki/Secp256k1
39-
//! [ECDSA]: https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm
40-
//! [ECDH]: https://en.wikipedia.org/wiki/Elliptic-curve_Diffie%E2%80%93Hellman
12+
//! Please see type-specific documentation for more information.
4113
4214
#![no_std]
4315
#![cfg_attr(docsrs, feature(doc_cfg))]

‎p256/src/arithmetic/affine.rs‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,20 @@ impl AffineArithmetic for NistP256 {
2121
type AffinePoint = AffinePoint;
2222
}
2323

24-
/// A point on the secp256r1 curve in affine coordinates.
24+
/// NIST P-256 (secp256r1) curve point expressed in affine coordinates.
25+
///
26+
/// # `serde` support
27+
///
28+
/// When the `serde` feature of this crate is enabled, the `Serialize` and
29+
/// `Deserialize` traits are impl'd for this type.
30+
///
31+
/// The serialization uses the [SEC1] `Elliptic-Curve-Point-to-Octet-String`
32+
/// encoding, serialized as binary.
33+
///
34+
/// When serialized with a text-based format, the SEC1 representation is
35+
/// subsequently hex encoded.
36+
///
37+
/// [SEC1]: https://www.secg.org/sec1-v2.pdf
2538
#[derive(Clone, Copy, Debug)]
2639
#[cfg_attr(docsrs, doc(cfg(feature = "arithmetic")))]
2740
pub struct AffinePoint {

‎p256/src/arithmetic/scalar.rs‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,14 @@ impl ScalarArithmetic for NistP256 {
7575
/// operations over field elements represented as bits (requires `bits` feature)
7676
///
7777
/// Please see the documentation for the relevant traits for more information.
78+
///
79+
/// # `serde` support
80+
///
81+
/// When the `serde` feature of this crate is enabled, the `Serialize` and
82+
/// `Deserialize` traits are impl'd for this type.
83+
///
84+
/// The serialization is a fixed-width big endian encoding. When used with
85+
/// textual formats, the binary data is encoded as hexadecimal.
7886
#[derive(Clone, Copy, Debug, Default)]
7987
#[cfg_attr(docsrs, doc(cfg(feature = "arithmetic")))]
8088
pub struct Scalar(pub(crate) U256);
@@ -123,7 +131,7 @@ impl Field for Scalar {
123131
}
124132

125133
/// Tonelli-Shank's algorithm for q mod 16 = 1
126-
/// https://eprint.iacr.org/2012/685.pdf (page 12, algorithm 5)
134+
/// <https://eprint.iacr.org/2012/685.pdf> (page 12, algorithm 5)
127135
#[allow(clippy::many_single_char_names)]
128136
fn sqrt(&self) -> CtOption<Self> {
129137
// Note: `pow_vartime` is constant-time with respect to `self`

‎p256/src/lib.rs‎

Lines changed: 9 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,43 +1,15 @@
1-
//! Pure Rust implementation of the NIST P-256 elliptic curve,
2-
//! including support for the
3-
//! [Elliptic Curve Digital Signature Algorithm (ECDSA)][ECDSA],
4-
//! [Elliptic Curve Diffie-Hellman (ECDH)][ECDH], and general purpose
5-
//! elliptic curve/field arithmetic which can be used to implement
6-
//! protocols based on group operations.
7-
//!
8-
//! ## About NIST P-256
9-
//!
10-
//! NIST P-256 is a Weierstrass curve specified in FIPS 186-4:
11-
//! Digital Signature Standard (DSS):
12-
//!
13-
//! <https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf>
14-
//!
15-
//! Also known as `prime256v1` (ANSI X9.62) and `secp256r1` (SECG), P-256 is
16-
//! included in the US National Security Agency's "Suite B" and is widely used
17-
//! in Internet and connected device protocols like TLS, the X.509 PKI, and
18-
//! Bluetooth.
19-
//!
20-
//! ## ⚠️ Security Warning
21-
//!
22-
//! The elliptic curve arithmetic contained in this crate has never been
23-
//! independently audited!
24-
//!
25-
//! This crate has been designed with the goal of ensuring that secret-dependent
26-
//! operations are performed in constant time (using the `subtle` crate and
27-
//! constant-time formulas). However, it has not been thoroughly assessed to ensure
28-
//! that generated assembly is constant time on common CPU architectures.
29-
//!
30-
//! USE AT YOUR OWN RISK!
31-
//!
32-
//! ## Minimum Supported Rust Version
1+
#![doc = include_str!("../README.md")]
2+
3+
//! ## `serde` support
334
//!
34-
//! Rust **1.56** or higher.
5+
//! When the `serde` feature of this crate is enabled, `Serialize` and
6+
//! `Deserialize` are impl'd for the following types:
357
//!
36-
//! Minimum supported Rust version may be changed in the future, but it will be
37-
//! accompanied with a minor version bump.
8+
//! - [`AffinePoint`]
9+
//! - [`Scalar`]
10+
//! - [`ecdsa::VerifyingKey`]
3811
//!
39-
//! [ECDSA]: https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm
40-
//! [ECDH]: https://en.wikipedia.org/wiki/Elliptic-curve_Diffie%E2%80%93Hellman
12+
//! Please see type-specific documentation for more information.
4113
4214
#![no_std]
4315
#![cfg_attr(docsrs, feature(doc_cfg))]

0 commit comments

Comments
 (0)