From 19cd777b15ddc54a5fe40a3db28087f6d23e193e Mon Sep 17 00:00:00 2001 From: Tony Arcieri Date: Sun, 31 Jul 2022 19:47:29 -0600 Subject: [PATCH] Include README.md in rustdoc (#461) The rustdocs all contained copy-paste of the README.mds, often out of date or with typos, which this commit corrects. --- aes-gcm-siv/Cargo.toml | 1 + aes-gcm-siv/src/lib.rs | 1 + aes-gcm/src/lib.rs | 41 +++++++++------------------------- aes-siv/src/lib.rs | 26 ++++++++-------------- ccm/src/lib.rs | 21 ++++++++---------- chacha20poly1305/src/lib.rs | 44 +++++++++---------------------------- deoxys/src/lib.rs | 33 +++++++--------------------- eax/src/lib.rs | 28 ++++++++++------------- mgm/src/lib.rs | 24 +++++++++----------- xsalsa20poly1305/src/lib.rs | 40 +++++++++------------------------ 10 files changed, 79 insertions(+), 180 deletions(-) diff --git a/aes-gcm-siv/Cargo.toml b/aes-gcm-siv/Cargo.toml index a30135f7..ef57bc82 100644 --- a/aes-gcm-siv/Cargo.toml +++ b/aes-gcm-siv/Cargo.toml @@ -38,3 +38,4 @@ stream = ["aead/stream"] [package.metadata.docs.rs] all-features = true +rustdoc-args = ["--cfg", "docsrs"] diff --git a/aes-gcm-siv/src/lib.rs b/aes-gcm-siv/src/lib.rs index 02fa7eae..97d47052 100644 --- a/aes-gcm-siv/src/lib.rs +++ b/aes-gcm-siv/src/lib.rs @@ -1,4 +1,5 @@ #![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", diff --git a/aes-gcm/src/lib.rs b/aes-gcm/src/lib.rs index 4582b5cd..c8595e05 100644 --- a/aes-gcm/src/lib.rs +++ b/aes-gcm/src/lib.rs @@ -1,20 +1,13 @@ -//! AES-auth tag: [Authenticated Encryption and Associated Data (AEAD)][1] cipher -//! based on AES in [Galois/Counter Mode][2]. -//! -//! ## Security Notes -//! -//! This crate has received one [security audit by NCC Group][3], with no significant -//! findings. We would like to thank [MobileCoin][4] for funding the audit. -//! -//! All implementations contained in the crate are designed to execute in constant -//! time, either by relying on hardware intrinsics (i.e. AES-NI and CLMUL on -//! x86/x86_64), or using a portable implementation which is only constant time -//! on processors which implement constant-time multiplication. -//! -//! It is not suitable for use on processors with a variable-time multiplication -//! operation (e.g. short circuit on multiply-by-zero / multiply-by-one, such as -//! certain 32-bit PowerPC CPUs and some non-ARM microcontrollers). -//! +#![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" +)] +#![deny(unsafe_code)] +#![warn(missing_docs, rust_2018_idioms)] + //! # Usage //! //! Simple usage (allocating, no associated data): @@ -85,20 +78,6 @@ //! # Ok(()) //! # } //! ``` -//! -//! [1]: https://en.wikipedia.org/wiki/Authenticated_encryption -//! [2]: https://en.wikipedia.org/wiki/Galois/Counter_Mode -//! [3]: https://research.nccgroup.com/2020/02/26/public-report-rustcrypto-aes-gcm-and-chacha20poly1305-implementation-review/ -//! [4]: https://www.mobilecoin.com/ - -#![no_std] -#![cfg_attr(docsrs, feature(doc_cfg))] -#![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" -)] -#![deny(unsafe_code)] -#![warn(missing_docs, rust_2018_idioms)] pub use aead::{self, AeadCore, AeadInPlace, Error, Key, KeyInit, KeySizeUser}; diff --git a/aes-siv/src/lib.rs b/aes-siv/src/lib.rs index d1ed2754..2792c3d9 100644 --- a/aes-siv/src/lib.rs +++ b/aes-siv/src/lib.rs @@ -1,7 +1,12 @@ -//! [AES-SIV][1] ([RFC 5297][2]): -//! [Authenticated Encryption with Associated Data (AEAD)][3] cipher which also -//! provides [nonce reuse misuse resistance][4]. -//! +#![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" +)] +#![warn(missing_docs, rust_2018_idioms, unused_qualifications)] + //! # Usage //! //! Simple usage (allocating, no associated data): @@ -72,19 +77,6 @@ //! # Ok(()) //! # } //! ``` -//! -//! [1]: https://github.com/miscreant/meta/wiki/AES-SIV -//! [2]: https://tools.ietf.org/html/rfc5297 -//! [3]: https://en.wikipedia.org/wiki/Authenticated_encryption -//! [4]: https://github.com/miscreant/meta/wiki/Nonce-Reuse-Misuse-Resistance - -#![no_std] -#![cfg_attr(docsrs, feature(doc_cfg))] -#![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" -)] -#![warn(missing_docs, rust_2018_idioms, unused_qualifications)] #[cfg(feature = "alloc")] extern crate alloc; diff --git a/ccm/src/lib.rs b/ccm/src/lib.rs index 36fb6ead..5277526b 100644 --- a/ccm/src/lib.rs +++ b/ccm/src/lib.rs @@ -1,7 +1,12 @@ -//! Counter with CBC-MAC ([CCM]): [Authenticated Encryption and Associated Data (AEAD)][1] -//! algorithm generic over block ciphers with block size equal to 128 bits as specified in -//! [RFC 3610]. -//! +#![no_std] +#![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" +)] +#![deny(unsafe_code)] +#![warn(missing_docs, rust_2018_idioms)] + //! # Usage //! //! Simple usage (allocating, no associated data): @@ -37,14 +42,6 @@ //! [aead]: https://docs.rs/aead //! [1]: https://en.wikipedia.org/wiki/Authenticated_encryption -#![no_std] -#![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" -)] -#![deny(unsafe_code)] -#![warn(missing_docs, rust_2018_idioms)] - pub use aead::{self, consts, AeadCore, AeadInPlace, Error, Key, KeyInit, KeySizeUser}; use aead::{ diff --git a/chacha20poly1305/src/lib.rs b/chacha20poly1305/src/lib.rs index 37eadd49..63e82165 100644 --- a/chacha20poly1305/src/lib.rs +++ b/chacha20poly1305/src/lib.rs @@ -1,7 +1,13 @@ -//! [`ChaCha20Poly1305`] ([RFC 8439][1]) is an -//! [Authenticated Encryption with Associated Data (AEAD)][2] -//! cipher amenable to fast, constant-time implementations in software, based on -//! the [ChaCha20][3] stream cipher and [Poly1305][4] universal hash function. +#![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" +)] +#![warn(missing_docs, rust_2018_idioms)] + +//! ## Supported Algorithms //! //! This crate contains pure Rust implementations of [`ChaCha20Poly1305`] //! (with optional AVX2 acceleration) as well as the following variants thereof: @@ -14,20 +20,6 @@ //! - [`XChaCha8Poly1305`] / [`XChaCha12Poly1305`] - same as above, //! but with an extended 192-bit (24-byte) nonce. //! -//! ## Security Notes -//! -//! This crate has received one [security audit by NCC Group][6], with no significant -//! findings. We would like to thank [MobileCoin][7] for funding the audit. -//! -//! All implementations contained in the crate are designed to execute in -//! constant time, either by relying on hardware intrinsics (i.e. AVX2 on -//! x86/x86_64), or using a portable implementation which is only constant time -//! on processors which implement constant-time multiplication. -//! -//! It is not suitable for use on processors with a variable-time multiplication -//! operation (e.g. short circuit on multiply-by-zero / multiply-by-one, such as -//! certain 32-bit PowerPC CPUs and some non-ARM microcontrollers). -//! //! # Usage //! #![cfg_attr(all(feature = "getrandom", feature = "std"), doc = "```")] @@ -143,22 +135,6 @@ //! # Ok(()) //! # } //! ``` -//! -//! [1]: https://tools.ietf.org/html/rfc8439 -//! [2]: https://en.wikipedia.org/wiki/Authenticated_encryption -//! [3]: https://github.com/RustCrypto/stream-ciphers/tree/master/chacha20 -//! [4]: https://github.com/RustCrypto/universal-hashes/tree/master/poly1305 -//! [5]: https://eprint.iacr.org/2019/1492.pdf -//! [6]: https://research.nccgroup.com/2020/02/26/public-report-rustcrypto-aes-gcm-and-chacha20poly1305-implementation-review/ -//! [7]: https://www.mobilecoin.com/ - -#![no_std] -#![cfg_attr(docsrs, feature(doc_cfg))] -#![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" -)] -#![warn(missing_docs, rust_2018_idioms)] mod cipher; diff --git a/deoxys/src/lib.rs b/deoxys/src/lib.rs index bc096a69..9f1a0e15 100644 --- a/deoxys/src/lib.rs +++ b/deoxys/src/lib.rs @@ -1,17 +1,11 @@ -//! The [Deoxys][1] [Authenticated Encryption and Associated Data (AEAD)][2] cipher. -//! -//! The Deoxys-II variant has been selected as the first choice for defense in-depth -//! scenario during the [CAESAR competition][3]. -//! -//! ## Security Notes -//! -//! This crate has *NOT* received any security audit. -//! -//! Although encryption and decryption passes the test vector, there is no guarantee -//! of constant-time operation. -//! -//! **USE AT YOUR OWN RISK.** -//! +#![no_std] +#![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" +)] +#![warn(missing_docs, rust_2018_idioms)] + //! # Usage //! #![cfg_attr(all(feature = "getrandom", feature = "std"), doc = "```")] @@ -104,17 +98,6 @@ //! assert_eq!(&buffer, b"plaintext message"); //! # } //! ``` -//! -//! [1]: https://sites.google.com/view/deoxyscipher -//! [2]: https://en.wikipedia.org/wiki/Authenticated_encryption -//! [3]: https://competitions.cr.yp.to/caesar-submissions.html - -#![no_std] -#![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" -)] -#![warn(missing_docs, rust_2018_idioms)] /// Deoxys-BC implementations. mod deoxys_bc; diff --git a/eax/src/lib.rs b/eax/src/lib.rs index 5b10a8fb..943afe7d 100644 --- a/eax/src/lib.rs +++ b/eax/src/lib.rs @@ -1,6 +1,13 @@ -//! EAX: [Authenticated Encryption and Associated Data (AEAD)][1] cipher -//! based on AES in counter mode. -//! +#![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" +)] +#![deny(unsafe_code)] +#![warn(missing_docs, rust_2018_idioms)] + //! # Usage //! //! Simple usage (allocating, no associated data): @@ -105,17 +112,6 @@ //! assert_eq!(&buffer, b"plaintext message"); //! # } //! ``` -//! -//! [1]: https://en.wikipedia.org/wiki/Authenticated_encryption - -#![no_std] -#![cfg_attr(docsrs, feature(doc_cfg))] -#![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" -)] -#![deny(unsafe_code)] -#![warn(missing_docs, rust_2018_idioms)] pub use aead::{self, AeadCore, AeadInPlace, Error, Key, KeyInit, KeySizeUser}; pub use cipher; @@ -158,9 +154,7 @@ type Ctr128BE = ctr::CtrCore; /// This type is generic to support substituting alternative cipher /// implementations. /// -/// If in doubt, use the built-in [`Aes128Eax`] and [`Aes256Eax`] type aliases. -/// -/// Type parameters: +/// ## Type parameters /// - `Cipher`: block cipher. /// - `M`: size of MAC tag, valid values: up to `U16`. #[derive(Clone)] diff --git a/mgm/src/lib.rs b/mgm/src/lib.rs index cf602392..eca92e1a 100644 --- a/mgm/src/lib.rs +++ b/mgm/src/lib.rs @@ -1,6 +1,12 @@ -//! Generic implementation of [Multilinear Galous Mode][1] [AEAD] construction. -//! -//! # Example +#![no_std] +#![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" +)] +#![warn(missing_docs, rust_2018_idioms)] + +//! # Usage Example #![cfg_attr(all(feature = "getrandom", feature = "std"), doc = "```")] #![cfg_attr(not(all(feature = "getrandom", feature = "std")), doc = "```ignore")] //! # fn main() -> Result<(), Box> { @@ -8,7 +14,7 @@ //! use mgm::Mgm; //! use mgm::aead::{Aead, KeyInit, OsRng, generic_array::GenericArray}; //! -//! let key = Mgm::::generate_key(&mut OsRng); +//! let key = Mgm::::generate_key(&mut OsRng); //! let cipher = Mgm::::new(&key); //! //! // 127-bit nonce value, since API has to accept 128 bits, first nonce bit @@ -22,16 +28,6 @@ //! # Ok(()) //! # } //! ``` -//! -//! [1]: https://eprint.iacr.org/2019/123.pdf -//! [AEAD]: https://en.wikipedia.org/wiki/Authenticated_encryption - -#![no_std] -#![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" -)] -#![warn(missing_docs, rust_2018_idioms)] use aead::{ consts::U0, generic_array::GenericArray, AeadCore, AeadInPlace, Error, Key, KeyInit, diff --git a/xsalsa20poly1305/src/lib.rs b/xsalsa20poly1305/src/lib.rs index 37328760..6f2a3db3 100644 --- a/xsalsa20poly1305/src/lib.rs +++ b/xsalsa20poly1305/src/lib.rs @@ -1,24 +1,13 @@ -//! **XSalsa20Poly1305** (a.k.a. NaCl [`crypto_secretbox`][1]) is an -//! [authenticated encryption][2] cipher amenable to fast, constant-time -//! implementations in software, based on the [Salsa20][3] stream cipher -//! (with [XSalsa20] 192-bit nonce extension) and the [Poly1305] universal -//! hash function, which acts as a message authentication code. -//! -//! This algorithm has largely been replaced by the newer [ChaCha20Poly1305][4] -//! (and the associated [XChaCha20Poly1305][5]) AEAD ciphers ([RFC 8439][6]), -//! but is useful for interoperability with legacy NaCl-based protocols. -//! -//! ## Security Warning -//! -//! No security audits of this crate have ever been performed, and it has not been -//! thoroughly assessed to ensure its operation is constant-time on common CPU -//! architectures. -//! -//! Where possible the implementation uses constant-time hardware intrinsics, -//! or otherwise falls back to an implementation which contains no secret-dependent -//! branches or table lookups, however it's possible LLVM may insert such -//! operations in certain scenarios. -//! +#![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" +)] +#![forbid(unsafe_code)] +#![warn(missing_docs, rust_2018_idioms)] + //! # Usage //! #![cfg_attr(all(feature = "getrandom", feature = "std"), doc = "```")] @@ -122,15 +111,6 @@ //! [5]: https://docs.rs/chacha20poly1305/latest/chacha20poly1305/struct.XChaCha20Poly1305.html //! [6]: https://tools.ietf.org/html/rfc8439 -#![no_std] -#![cfg_attr(docsrs, feature(doc_cfg))] -#![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" -)] -#![forbid(unsafe_code)] -#![warn(missing_docs, rust_2018_idioms)] - pub use aead::{self, consts, AeadCore, AeadInPlace, Error, KeyInit, KeySizeUser}; pub use salsa20::{Key, XNonce as Nonce};