Use README as crate docs (#537)

RustCrypto · Jan 10, 2024 · f5a07e6 · f5a07e6
1 parent 414eca5
commit f5a07e6
Show file tree

Hide file tree

Showing 85 changed files with 823 additions and 1,117 deletions.
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/README.md b/README.md
@@ -67,7 +67,7 @@ The SHA-1 implementation was previously published as `sha-1`, but migrated to `s
 
 MSRV bumps are considered breaking changes and will be performed only with minor version bump.
 
-## Usage
+## Examples
 
 Let us demonstrate how to use crates in this repository using SHA-2 as an example.
 
@@ -215,10 +215,10 @@ let hash2_1 = use_hasher(&mut *hasher2, b"foo");
 
 ## License
 
-All crates licensed under either of
+All crates in this repository are licensed under either of
 
- * [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)
- * [MIT license](http://opensource.org/licenses/MIT)
+* [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)
+* [MIT license](http://opensource.org/licenses/MIT)
 
 at your option.
 

diff --git a/ascon-hash/Cargo.toml b/ascon-hash/Cargo.toml
@@ -22,6 +22,7 @@ ascon = { version = "0.4", default-features = false }
 [dev-dependencies]
 spectral = { version = "0.6", default-features = false }
 hex = "0.4"
+hex-literal = "0.4"
 
 [features]
 default = ["std"]

diff --git a/ascon-hash/LICENSE-MIT b/ascon-hash/LICENSE-MIT
@@ -1,5 +1,5 @@
 Copyright (c) 2022-2023 Sebastian Ramacher <[email protected]>
-Copyright (c) 2023 The RustCrypto Project Developers
+Copyright (c) 2023-2024 The RustCrypto Project Developers
 
 Permission is hereby granted, free of charge, to any
 person obtaining a copy of this software and associated

diff --git a/ascon-hash/README.md b/ascon-hash/README.md
@@ -11,14 +11,40 @@ Pure Rust implementation of the lightweight cryptographic hash functions
 [AsconHash and AsconAHash][1] and the extendable output functions (XOF) AsconXOF
 and AsconAXOF.
 
-[Documentation][docs-link]
-
 ## Security Notes
 
 No security audits of this crate have ever been performed.
 
 USE AT YOUR OWN RISK!
 
+## Examples
+Fixed output size hashing:
+```rust
+use ascon_hash::{AsconHash, Digest};
+use hex_literal::hex;
+
+let mut hasher = AsconHash::new();
+hasher.update(b"some bytes");
+let hash = hasher.finalize();
+
+assert_eq!(hash, hex!("b742ca75e57038757059cccc6874714f9dbd7fc5924a7df4e316594fd1426ca8"));
+```
+
+XOF hashing:
+```rust
+use ascon_hash::{AsconXof, ExtendableOutput, Update, XofReader};
+use hex_literal::hex;
+
+let mut xof = AsconXof::default();
+xof.update(b"some bytes");
+let mut reader = xof.finalize_xof();
+let mut dst = [0u8; 5];
+reader.read(&mut dst);
+assert_eq!(dst, hex!("c21972fde9"));
+```
+
+Also, see the [examples section] in the RustCrypto/hashes readme.
+
 ## Minimum Supported Rust Version
 
 This crate requires **Rust 1.71** at a minimum.
@@ -28,10 +54,10 @@ version bump.
 
 ## License
 
-Licensed under either of:
+The crate is licensed under either of:
 
- * [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)
- * [MIT license](http://opensource.org/licenses/MIT)
+* [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)
+* [MIT license](http://opensource.org/licenses/MIT)
 
 at your option.
 
@@ -57,3 +83,4 @@ dual licensed as above, without any additional terms or conditions.
 [//]: # (general links)
 
 [1]: https://ascon.iaik.tugraz.at
+[examples section]: https://github.com/RustCrypto/hashes#Examples
diff --git a/ascon-hash/src/lib.rs b/ascon-hash/src/lib.rs
@@ -1,6 +1,3 @@
-// Copyright 2022-2023 Sebastian Ramacher
-// SPDX-License-Identifier: Apache-2.0 OR MIT
-
 #![no_std]
 #![cfg_attr(docsrs, feature(doc_auto_cfg))]
 #![doc = include_str!("../README.md")]
@@ -10,30 +7,6 @@
 )]
 #![warn(missing_docs)]
 
-//! ## Usage (Hashing)
-//!
-//! ```
-//! use ascon_hash::{AsconHash, Digest}; // Or `AsconAHash`
-//!
-//! let mut hasher = AsconHash::new();
-//! hasher.update(b"some bytes");
-//! let digest = hasher.finalize();
-//! assert_eq!(&digest[..], b"\xb7\x42\xca\x75\xe5\x70\x38\x75\x70\x59\xcc\xcc\x68\x74\x71\x4f\x9d\xbd\x7f\xc5\x92\x4a\x7d\xf4\xe3\x16\x59\x4f\xd1\x42\x6c\xa8");
-//! ```
-//!
-//! ## Usage (XOF)
-//!
-//! ```
-//! use ascon_hash::{AsconXof, ExtendableOutput, Update, XofReader};
-//!
-//! let mut xof = AsconXof::default();
-//! xof.update(b"some bytes");
-//! let mut reader = xof.finalize_xof();
-//! let mut dst = [0u8; 5];
-//! reader.read(&mut dst);
-//! assert_eq!(&dst, b"\xc2\x19\x72\xfd\xe9");
-//! ```
-
 use core::marker::PhantomData;
 
 use ascon::{pad, State};

diff --git a/belt-hash/LICENSE-MIT b/belt-hash/LICENSE-MIT
@@ -1,4 +1,4 @@
-Copyright (c) 2022 Artyom Pavlov
+Copyright (c) 2022-2024 The RustCrypto Project Developers
 
 Permission is hereby granted, free of charge, to any
 person obtaining a copy of this software and associated

diff --git a/belt-hash/README.md b/belt-hash/README.md
@@ -9,7 +9,19 @@
 
 Pure Rust implementation of the [BelT] hash function specified in [STB 34.101.31-2020].
 
-[Documentation][docs-link]
+## Examples
+```rust
+use belt_hash::{BeltHash, Digest};
+use hex_literal::hex;
+
+let mut hasher = BeltHash::new();
+hasher.update(b"hello world");
+let hash = hasher.finalize();
+
+assert_eq!(hash, hex!("afb175816416fbadad4629ecbd78e1887789881f2d2e5b80c22a746b7ac7ba88"));
+```
+
+Also, see the [examples section] in the RustCrypto/hashes readme.
 
 ## Minimum Supported Rust Version
 
@@ -25,10 +37,10 @@ done with a minor version bump.
 
 ## License
 
-Licensed under either of:
+The crate is licensed under either of:
 
- * [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)
- * [MIT license](http://opensource.org/licenses/MIT)
+* [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)
+* [MIT license](http://opensource.org/licenses/MIT)
 
 at your option.
 
@@ -55,3 +67,4 @@ dual licensed as above, without any additional terms or conditions.
 
 [BelT]: https://ru.wikipedia.org/wiki/BelT
 [STB 34.101.31-2020]: http://apmi.bsu.by/assets/files/std/belt-spec371.pdf
+[examples section]: https://github.com/RustCrypto/hashes#Examples
diff --git a/belt-hash/src/lib.rs b/belt-hash/src/lib.rs
@@ -1,33 +1,6 @@
-//! Pure Rust implementation of the [BelT] hash function specified in
-//! [STB 34.101.31-2020].
-//!
-//! # Usage
-//!
-//! ```rust
-//! use belt_hash::{BeltHash, Digest};
-//! use hex_literal::hex;
-//!
-//! // create a BelT hasher instance
-//! let mut hasher = BeltHash::new();
-//!
-//! // process input message
-//! hasher.update(b"hello world");
-//!
-//! // acquire hash digest in the form of Array,
-//! // which in this case is equivalent to [u8; 32]
-//! let result = hasher.finalize();
-//! let expected = hex!(
-//!     "afb175816416fbadad4629ecbd78e1887789881f2d2e5b80c22a746b7ac7ba88"
-//! );
-//! assert_eq!(result[..], expected[..]);
-//! ```
-//!
-//! Also see [examples] in the RustCrypto/hashes readme.
-//!
-//! [BelT]: https://ru.wikipedia.org/wiki/BelT
-//! [STB 34.101.31-2020]: http://apmi.bsu.by/assets/files/std/belt-spec371.pdf
-//! [examples]: https://github.com/RustCrypto/hashes#usage
 #![no_std]
+#![doc = include_str!("../README.md")]
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
 #![doc(
     html_logo_url = "https://raw.githubusercontent.com/RustCrypto/media/6ee8e381/logo.svg",
     html_favicon_url = "https://raw.githubusercontent.com/RustCrypto/media/6ee8e381/logo.svg"
@@ -52,6 +25,9 @@ use digest::{
 };
 
 const U32_MASK: u128 = (1 << 32) - 1;
+const H0: [u32; 8] = [
+    0xC8BA94B1, 0x3BF5080A, 0x8E006D36, 0xE45D4A58, 0x9DFA0485, 0xACC7B61B, 0xC2722E25, 0x0DCEFD02,
+];
 
 /// Core BelT hasher state.
 #[derive(Clone)]
@@ -128,11 +104,7 @@ impl Default for BeltHashCore {
         Self {
             r: 0,
             s: [0; 4],
-            #[rustfmt::skip]
-            h: [
-                0xC8BA94B1, 0x3BF5080A, 0x8E006D36, 0xE45D4A58,
-                0x9DFA0485, 0xACC7B61B, 0xC2722E25, 0x0DCEFD02,
-            ],
+            h: H0,
         }
     }
 }

diff --git a/belt-hash/tests/mod.rs b/belt-hash/tests/mod.rs
@@ -11,10 +11,7 @@ fn belt_rand() {
     let mut h = BeltHash::new();
     feed_rand_16mib(&mut h);
     assert_eq!(
-        h.finalize()[..],
-        hex!(
-            "a45053f80827d530008198c8185aa507"
-            "403b4a21f591579f07c34358e5991754"
-        )[..]
+        h.finalize(),
+        hex!("a45053f80827d530008198c8185aa507403b4a21f591579f07c34358e5991754")
     );
 }
diff --git a/blake2/Cargo.toml b/blake2/Cargo.toml
@@ -23,7 +23,7 @@ hex-literal = "0.4"
 default = ["std"]
 std = ["digest/std"]
 reset = [] # Enable reset functionality
-simd = []
-simd_opt = ["simd"]
-simd_asm = ["simd_opt"]
+#simd = []
+#simd_opt = ["simd"]
+#simd_asm = ["simd_opt"]
 size_opt = [] # Optimize for code size. Removes some `inline(always)`
diff --git a/blake2/LICENSE-MIT b/blake2/LICENSE-MIT
@@ -1,5 +1,6 @@
 Copyright (c) 2015-2016 The blake2-rfc Developers, Cesar Barros
 Copyright (c) 2017 Artyom Pavlov
+Copyright (c) 2017-2024 The RustCrypto Project Developers
 
 Permission is hereby granted, free of charge, to any
 person obtaining a copy of this software and associated

diff --git a/blake2/README.md b/blake2/README.md
@@ -7,9 +7,67 @@
 ![Rust Version][rustc-image]
 [![Project Chat][chat-image]][chat-link]
 
-Pure Rust implementation of the [BLAKE2 hash function][1] family.
+Pure Rust implementation of the [BLAKE2] hash function family.
 
-[Documentation][docs-link]
+## Examples
+
+### Fixed output size
+
+```rust
+use blake2::{Blake2b512, Blake2s256, Digest};
+use hex_literal::hex;
+
+// create a Blake2b512 object
+let mut hasher = Blake2b512::new();
+
+// write input message
+hasher.update(b"hello world");
+
+// read hash digest and consume hasher
+let res = hasher.finalize();
+assert_eq!(res, hex!(
+    "021ced8799296ceca557832ab941a50b4a11f83478cf141f51f933f653ab9fbc"
+    "c05a037cddbed06e309bf334942c4e58cdf1a46e237911ccd7fcf9787cbc7fd0"
+));
+
+// same example for Blake2s256:
+let mut hasher = Blake2s256::new();
+hasher.update(b"hello world");
+let res = hasher.finalize();
+assert_eq!(res, hex!("9aec6806794561107e594b1f6a8a6b0c92a0cba9acf5e5e93cca06f781813b0b"));
+```
+
+Also, see the [examples section] in the RustCrypto/hashes readme.
+
+### Variable output size
+
+This implementation supports run and compile time variable sizes.
+
+Output size set at run time:
+```rust
+use blake2::Blake2bVar;
+use blake2::digest::{Update, VariableOutput};
+use hex_literal::hex;
+
+let mut hasher = Blake2bVar::new(10).unwrap();
+hasher.update(b"my_input");
+let mut buf = [0u8; 10];
+hasher.finalize_variable(&mut buf).unwrap();
+assert_eq!(buf, hex!("2cc55c84e416924e6400"));
+```
+
+Output size set at compile time:
+```rust
+use blake2::{Blake2b, Digest, digest::consts::U10};
+use hex_literal::hex;
+
+type Blake2b80 = Blake2b<U10>;
+
+let mut hasher = Blake2b80::new();
+hasher.update(b"my_input");
+let res = hasher.finalize();
+assert_eq!(res, hex!("2cc55c84e416924e6400"));
+```
 
 ## Minimum Supported Rust Version
 
@@ -25,10 +83,10 @@ done with a minor version bump.
 
 ## License
 
-Licensed under either of:
+The crate is licensed under either of:
 
- * [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)
- * [MIT license](http://opensource.org/licenses/MIT)
+* [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)
+* [MIT license](http://opensource.org/licenses/MIT)
 
 at your option.
 
@@ -53,4 +111,5 @@ dual licensed as above, without any additional terms or conditions.
 
 [//]: # (general links)
 
-[1]: https://blake2.net/
+[BLAKE2]: https://blake2.net/
+[examples section]: https://github.com/RustCrypto/hashes#Examples