From f5a07e6bfdd69afda90769587b6b88debd1a5b84 Mon Sep 17 00:00:00 2001 From: Artyom Pavlov Date: Wed, 10 Jan 2024 16:52:58 +0300 Subject: [PATCH] Use README as crate docs (#537) --- Cargo.lock | 9 +++-- README.md | 8 ++-- ascon-hash/Cargo.toml | 1 + ascon-hash/LICENSE-MIT | 2 +- ascon-hash/README.md | 37 +++++++++++++++--- ascon-hash/src/lib.rs | 27 ------------- belt-hash/LICENSE-MIT | 2 +- belt-hash/README.md | 21 ++++++++-- belt-hash/src/lib.rs | 40 +++---------------- belt-hash/tests/mod.rs | 7 +--- blake2/Cargo.toml | 6 +-- blake2/LICENSE-MIT | 1 + blake2/README.md | 71 +++++++++++++++++++++++++++++++--- blake2/src/lib.rs | 71 +--------------------------------- blake2/tests/persona.rs | 42 ++++++++++---------- fsb/LICENSE-MIT | 2 +- fsb/README.md | 33 ++++++++++++++-- fsb/src/lib.rs | 40 +------------------ fsb/tests/mod.rs | 34 ++++++++-------- gost94/LICENSE-MIT | 1 + gost94/README.md | 33 +++++++++++++--- gost94/src/lib.rs | 36 +---------------- gost94/tests/mod.rs | 20 +++++----- groestl/LICENSE-MIT | 2 +- groestl/README.md | 26 ++++++++++--- groestl/src/lib.rs | 28 +------------- groestl/tests/mod.rs | 30 +++++++------- jh/LICENSE-MIT | 2 +- jh/README.md | 29 ++++++++++++-- jh/src/lib.rs | 34 +--------------- k12/LICENSE-MIT | 2 +- k12/README.md | 13 +++---- k12/src/lib.rs | 6 +-- k12/tests/mod.rs | 17 ++++---- md2/LICENSE-MIT | 1 + md2/README.md | 26 ++++++++++--- md2/src/lib.rs | 26 +------------ md2/tests/mod.rs | 5 +-- md4/LICENSE-MIT | 1 + md4/README.md | 31 ++++++++++++--- md4/src/lib.rs | 26 +------------ md4/tests/mod.rs | 5 +-- md5/LICENSE-MIT | 1 + md5/README.md | 40 ++++++++++++------- md5/src/lib.rs | 26 +------------ md5/tests/mod.rs | 5 +-- ripemd/LICENSE-MIT | 2 +- ripemd/README.md | 39 ++++++++++++++++--- ripemd/src/lib.rs | 41 +------------------- ripemd/tests/mod.rs | 35 +++++++---------- sha1/LICENSE-MIT | 1 + sha1/README.md | 46 +++++++++++++++++----- sha1/src/lib.rs | 55 +------------------------- sha1/tests/mod.rs | 4 +- sha2/LICENSE-MIT | 1 + sha2/README.md | 57 +++++++++++++++++++++++---- sha2/src/lib.rs | 61 +---------------------------- sha2/tests/mod.rs | 15 ++++--- sha3/LICENSE-MIT | 1 + sha3/README.md | 59 +++++++++++++++++++++++++--- sha3/src/lib.rs | 61 +---------------------------- shabal/LICENSE-MIT | 1 + shabal/README.md | 41 +++++++------------- shabal/src/lib.rs | 39 +------------------ shabal/tests/mod.rs | 34 ++++++++-------- skein/LICENSE-MIT | 2 +- skein/README.md | 30 +++++++++++--- skein/src/lib.rs | 38 +----------------- skein/tests/{lib.rs => mod.rs} | 0 sm3/LICENSE-MIT | 2 +- sm3/README.md | 27 ++++++++++--- sm3/src/lib.rs | 31 +-------------- sm3/tests/mod.rs | 4 +- streebog/LICENSE-MIT | 1 + streebog/README.md | 35 ++++++++++++++--- streebog/src/lib.rs | 36 +---------------- streebog/tests/mod.rs | 60 ++++++++++++++-------------- tiger/LICENSE-MIT | 2 +- tiger/README.md | 26 ++++++++++--- tiger/src/lib.rs | 28 +------------- tiger/tests/mod.rs | 8 ++-- whirlpool/LICENSE-MIT | 1 + whirlpool/README.md | 41 +++++++++++++++++--- whirlpool/src/lib.rs | 38 +----------------- whirlpool/tests/mod.rs | 11 +++--- 85 files changed, 823 insertions(+), 1117 deletions(-) rename skein/tests/{lib.rs => mod.rs} (100%) diff --git a/Cargo.lock b/Cargo.lock index 647da4e7d..6a908087c 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -18,6 +18,7 @@ dependencies = [ "ascon", "digest", "hex", + "hex-literal", "spectral", ] @@ -124,9 +125,9 @@ dependencies = [ [[package]] name = "getrandom" -version = "0.2.11" +version = "0.2.12" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "fe9006bed769170c11f845cf00c7c1e9092aeb3f268e007c3e760ac68008070f" +checksum = "190092ea657667030ac6a35e305e62fc4dd69fd98ac98631e5d3a2b1575a12b5" dependencies = [ "cfg-if", "libc", @@ -199,9 +200,9 @@ dependencies = [ [[package]] name = "libc" -version = "0.2.150" +version = "0.2.152" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "89d92a4743f9a61002fae18374ed11e7973f530cb3a3255fb354818118b2203c" +checksum = "13e3bf6590cbc649f4d1a3eefc9d5d6eb746f5200ffb04e5e142700b8faa56e7" [[package]] name = "md-5" diff --git a/README.md b/README.md index b2da70ad2..13298916e 100644 --- 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 index 58575d87e..c27d6e8a1 100644 --- 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 index 99440392b..3f0a8ba26 100644 --- a/ascon-hash/LICENSE-MIT +++ b/ascon-hash/LICENSE-MIT @@ -1,5 +1,5 @@ Copyright (c) 2022-2023 Sebastian Ramacher -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 index 86fc86794..f70c5817a 100644 --- 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 index b591a6de8..2696f0580 100644 --- 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 index bebabe744..6ebea87db 100644 --- 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 index 61c5d8d3e..071694ef2 100644 --- 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 index e92dfc6bb..d441158cc 100644 --- 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 index d8259a128..ce12d1d4e 100644 --- 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 index cd132e7a5..a31a71e07 100644 --- 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 index 872e206f2..a264c31a1 100644 --- 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 index e41d6fa0d..733fb77c1 100644 --- 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; + +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 diff --git a/blake2/src/lib.rs b/blake2/src/lib.rs index a18d448ea..e98a07570 100644 --- a/blake2/src/lib.rs +++ b/blake2/src/lib.rs @@ -1,74 +1,5 @@ -//! An implementation of the [BLAKE2][1] hash functions. -//! -//! # Usage -//! -//! [`Blake2b512`] and [`Blake2s256`] can be used in the following way: -//! -//! ```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 [RustCrypto/hashes](https://github.com/RustCrypto/hashes) readme. -//! -//! ## Variable output size -//! -//! This implementation supports run and compile time variable sizes. -//! -//! Run time variable output example: -//! ```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")); -//! ``` -//! -//! Compile time variable output example: -//! ```rust -//! use blake2::{Blake2b, Digest, digest::consts::U10}; -//! use hex_literal::hex; -//! -//! type Blake2b80 = Blake2b; -//! -//! let mut hasher = Blake2b80::new(); -//! hasher.update(b"my_input"); -//! let res = hasher.finalize(); -//! assert_eq!(res[..], hex!("2cc55c84e416924e6400")[..]); -//! ``` -//! -//! # Acknowledgment -//! Based on the [blake2-rfc][2] crate. -//! -//! [1]: https://en.wikipedia.org/wiki/BLAKE_(hash_function)#BLAKE2 -//! [2]: https://github.com/cesarb/blake2-rfc - #![no_std] +#![doc = include_str!("../README.md")] #![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" diff --git a/blake2/tests/persona.rs b/blake2/tests/persona.rs index 49e6574e9..53ba8ef08 100644 --- a/blake2/tests/persona.rs +++ b/blake2/tests/persona.rs @@ -2,39 +2,37 @@ use blake2::{digest::FixedOutput, Blake2bMac512, Blake2sMac256}; use hex_literal::hex; #[test] -#[rustfmt::skip] fn blake2s_persona() { - let key= hex!(" - 000102030405060708090a0b0c0d0e0f - 101112131415161718191a1b1c1d1e1f - "); + let key = hex!( + "000102030405060708090a0b0c0d0e0f" + "101112131415161718191a1b1c1d1e1f" + ); let persona = b"personal"; let ctx = Blake2sMac256::new_with_salt_and_personal(&key, &[], persona).unwrap(); assert_eq!( - ctx.finalize_fixed()[..], - hex!(" - 25a4ee63b594aed3f88a971e1877ef70 - 99534f9097291f88fb86c79b5e70d022 - ")[..], + ctx.finalize_fixed(), + hex!( + "25a4ee63b594aed3f88a971e1877ef70" + "99534f9097291f88fb86c79b5e70d022" + ), ); } #[test] -#[rustfmt::skip] fn blake2b_persona() { - let key = hex!(" - 000102030405060708090a0b0c0d0e0f - 101112131415161718191a1b1c1d1e1f - "); + let key = hex!( + "000102030405060708090a0b0c0d0e0f" + "101112131415161718191a1b1c1d1e1f" + ); let persona = b"personal"; let ctx = Blake2bMac512::new_with_salt_and_personal(&key, &[], persona).unwrap(); assert_eq!( - ctx.finalize_fixed()[..], - hex!(" - 03de3b295dcfc3b25b05abb09bc95fe3 - e9ff3073638badc68101d1e42019d077 - 1dd07525a3aae8318e92c5e5d967ba92 - e4810d0021d7bf3b49da0b4b4a8a4e1f - ")[..], + ctx.finalize_fixed(), + hex!( + "03de3b295dcfc3b25b05abb09bc95fe3" + "e9ff3073638badc68101d1e42019d077" + "1dd07525a3aae8318e92c5e5d967ba92" + "e4810d0021d7bf3b49da0b4b4a8a4e1f" + ), ); } diff --git a/fsb/LICENSE-MIT b/fsb/LICENSE-MIT index c869ada57..6f139a79c 100644 --- a/fsb/LICENSE-MIT +++ b/fsb/LICENSE-MIT @@ -1,4 +1,4 @@ -Copyright (c) 2021 The RustCrypto Project Developers +Copyright (c) 2021-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/fsb/README.md b/fsb/README.md index 1319026f5..af5de0a50 100644 --- a/fsb/README.md +++ b/fsb/README.md @@ -7,9 +7,33 @@ ![Rust Version][rustc-image] [![Project Chat][chat-image]][chat-link] -Pure Rust implementation of the [FSB hash function][1] family. +Pure Rust implementation of the [FSB] cryptographic hash algorithms. -[Documentation][docs-link] +There are 5 standard versions of the FSB hash function: + +* `FSB-160` +* `FSB-224` +* `FSB-256` +* `FSB-384` +* `FSB-512` + +## Examples + +Output size of FSB-256 is fixed, so its functionality is usually +accessed via the `Digest` trait: + +```rust +use fsb::{Digest, Fsb256}; +use hex_literal::hex; + +let mut hasher = Fsb256::new(); +hasher.update(b"hello"); +let hash = hasher.finalize(); + +assert_eq!(hash, hex!("0f036dc3761aed2cba9de586a85976eedde6fa8f115c0190763decc02f28edbc")); +``` + +Also, see the [examples section] in the RustCrypto/hashes readme. ## Minimum Supported Rust Version @@ -25,7 +49,7 @@ 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) @@ -53,4 +77,5 @@ dual licensed as above, without any additional terms or conditions. [//]: # (general links) -[1]: https://www.paris.inria.fr/secret/CBCrypto/index.php?pg=fsb +[FSB]: https://www.paris.inria.fr/secret/CBCrypto/index.php?pg=fsb +[examples section]: https://github.com/RustCrypto/hashes#Examples diff --git a/fsb/src/lib.rs b/fsb/src/lib.rs index 350fc1126..06760cb1a 100644 --- a/fsb/src/lib.rs +++ b/fsb/src/lib.rs @@ -1,43 +1,5 @@ -//! An implementation of the [FSB][1] cryptographic hash algorithms. -//! The FSB hash function was one of the submissions to SHA-3, -//! the cryptographic hash algorithm competition organized by the NIST. -//! -//! There are 5 standard versions of the FSB hash function: -//! -//! * `FSB-160` -//! * `FSB-224` -//! * `FSB-256` -//! * `FSB-384` -//! * `FSB-512` -//! -//! # Examples -//! -//! Output size of FSB-256 is fixed, so its functionality is usually -//! accessed via the `Digest` trait: -//! -//! ``` -//! use hex_literal::hex; -//! use fsb::{Digest, Fsb256}; -//! -//! // create a FSB-256 object -//! let mut hasher = Fsb256::new(); -//! -//! // write input message -//! hasher.update(b"hello"); -//! -//! // read hash digest -//! let result = hasher.finalize(); -//! -//! assert_eq!(result[..], hex!(" -//! 0f036dc3761aed2cba9de586a85976eedde6fa8f115c0190763decc02f28edbc -//! ")[..]); -//! ``` -//! Also see [RustCrypto/hashes][2] readme. -//! -//! [1]: https://www.paris.inria.fr/secret/CBCrypto/index.php?pg=fsb -//! [2]: https://github.com/RustCrypto/hashes - #![no_std] +#![doc = include_str!("../README.md")] #![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" diff --git a/fsb/tests/mod.rs b/fsb/tests/mod.rs index 928f1b979..6a9bddeab 100644 --- a/fsb/tests/mod.rs +++ b/fsb/tests/mod.rs @@ -14,8 +14,8 @@ fn fsb160_rand() { let mut h = Fsb160::new(); feed_rand_16mib(&mut h); assert_eq!( - h.finalize()[..], - hex!("40b7538be5e51978690d1a92fe12a7f25f0a7f08")[..] + h.finalize(), + hex!("40b7538be5e51978690d1a92fe12a7f25f0a7f08") ); } @@ -24,8 +24,8 @@ fn fsb224_rand() { let mut h = Fsb224::new(); feed_rand_16mib(&mut h); assert_eq!( - h.finalize()[..], - hex!("0ec203ccec7cbf0cadd32e5dc069d0b4215a104c4dad5444944a0d09")[..] + h.finalize(), + hex!("0ec203ccec7cbf0cadd32e5dc069d0b4215a104c4dad5444944a0d09") ); } @@ -34,35 +34,33 @@ fn fsb256_rand() { let mut h = Fsb256::new(); feed_rand_16mib(&mut h); assert_eq!( - h.finalize()[..], - hex!("eecb42832a2b03bc91beb1a56ddf2973c962b1aeb22f278e9d78a7a8879ebba7")[..] + h.finalize(), + hex!("eecb42832a2b03bc91beb1a56ddf2973c962b1aeb22f278e9d78a7a8879ebba7") ); } #[test] -#[rustfmt::skip] fn fsb384_rand() { let mut h = Fsb384::new(); feed_rand_16mib(&mut h); assert_eq!( - h.finalize()[..], - hex!(" - f17533ed4d4484434715e63bc8e801c9cfe988c38d47d3b4be0409571360aa2f - b360b2804c14f606906b323e7901c09e - ")[..] + h.finalize(), + hex!( + "f17533ed4d4484434715e63bc8e801c9cfe988c38d47d3b4be0409571360aa2f" + "b360b2804c14f606906b323e7901c09e" + ) ); } #[test] -#[rustfmt::skip] fn fsb512_rand() { let mut h = Fsb512::new(); feed_rand_16mib(&mut h); assert_eq!( - h.finalize()[..], - hex!(" - 957a7733643e075ab7a3b04607800a6208a26b008bdaee759a3a635bb9b5b708 - 3531725783505468bf438f2a0a96163bbe0775468a11c93db9994c466b2e7d8c - ")[..] + h.finalize(), + hex!( + "957a7733643e075ab7a3b04607800a6208a26b008bdaee759a3a635bb9b5b708" + "3531725783505468bf438f2a0a96163bbe0775468a11c93db9994c466b2e7d8c" + ) ); } diff --git a/gost94/LICENSE-MIT b/gost94/LICENSE-MIT index 78d6d79a4..4abba7d11 100644 --- a/gost94/LICENSE-MIT +++ b/gost94/LICENSE-MIT @@ -1,4 +1,5 @@ Copyright (c) 2016 Artyom Pavlov +Copyright (c) 2016-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/gost94/README.md b/gost94/README.md index aff3cc763..4c4ec68e0 100644 --- a/gost94/README.md +++ b/gost94/README.md @@ -7,9 +7,27 @@ [![Project Chat][chat-image]][chat-link] [![Build Status][build-image]][build-link] -Pure Rust implementation of the [GOST R 34.11-94 hash function][1]. +Pure Rust implementation of the [GOST R 34.11-94] cryptographic hash algorithm. -[Documentation][docs-link] +## Examples + +```rust +use gost94::{Gost94CryptoPro, Digest}; +use hex_literal::hex; + +let mut hasher = Gost94CryptoPro::new(); +hasher.update("The quick brown fox jumps over the lazy dog"); +let hash = hasher.finalize(); + +assert_eq!(hash, hex!("9004294a361a508c586fe53d1f1b02746765e71b765472786e4770d565830a76")); +``` + +Also, see the [examples section] in the RustCrypto/hashes readme. + +## Associated OIDs. +There can be a confusion regarding OIDs associated with declared types. +According to the [RFC 4357], the OIDs 1.2.643.2.2.30.1 and 1.2.643.2.2.30.0 are used to identify the hash function parameter sets (CryptoPro vs Test ones). +According to [RFC 4490] the OID 1.2.643.2.2.9 identifies the GOST 34.311-95 (former GOST R 34.11-94) function, but then it continues that this function MUST be used only with the CryptoPro parameter set. ## Minimum Supported Rust Version @@ -25,10 +43,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 +71,7 @@ dual licensed as above, without any additional terms or conditions. [//]: # (general links) -[1]: https://en.wikipedia.org/wiki/GOST_(hash_function) +[GOST R 34.11-94]: https://en.wikipedia.org/wiki/GOST_(hash_function) +[RFC 4357]: https://www.rfc-editor.org/rfc/rfc4357 +[RFC 4490]: https://www.rfc-editor.org/rfc/rfc4490 +[examples section]: https://github.com/RustCrypto/hashes#Examples diff --git a/gost94/src/lib.rs b/gost94/src/lib.rs index f530a1bcc..bb4c04984 100644 --- a/gost94/src/lib.rs +++ b/gost94/src/lib.rs @@ -1,39 +1,5 @@ -//! An implementation of the [GOST R 34.11-94][1] cryptographic hash algorithm. -//! -//! # Usage -//! ```rust -//! use gost94::{Gost94CryptoPro, Digest}; -//! use hex_literal::hex; -//! -//! // create Gost94 hasher instance with CryptoPro params -//! let mut hasher = Gost94CryptoPro::new(); -//! -//! // process input message -//! hasher.update("The quick brown fox jumps over the lazy dog"); -//! -//! // acquire hash digest in the form of Array, -//! // which in this case is equivalent to [u8; 32] -//! let result = hasher.finalize(); -//! assert_eq!(result[..], hex!(" -//! 9004294a361a508c586fe53d1f1b02746765e71b765472786e4770d565830a76 -//! ")); -//! ``` -//! -//! Also see [RustCrypto/hashes][2] readme. -//! -//! # Associated OIDs. -//! There can be a confusion regarding OIDs associated with declared types. According to the -//! [RFC 4357][3], the OIDs 1.2.643.2.2.30.1 and 1.2.643.2.2.30.0 are used to identify the hash -//! function parameter sets (CryptoPro vs Test ones). According to [RFC 4490][4] the OID -//! 1.2.643.2.2.9 identifies the GOST 34.311-95 (former GOST R 34.11-94) function, but then it -//! continues that this function MUST be used only with the CryptoPro parameter set. -//! -//! [1]: https://en.wikipedia.org/wiki/GOST_(hash_function) -//! [2]: https://github.com/RustCrypto/hashes -//! [3]: https://www.rfc-editor.org/rfc/rfc4357 -//! [4]: https://www.rfc-editor.org/rfc/rfc4490 - #![no_std] +#![doc = include_str!("../README.md")] #![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" diff --git a/gost94/tests/mod.rs b/gost94/tests/mod.rs index 7d0cad741..a31e4beb5 100644 --- a/gost94/tests/mod.rs +++ b/gost94/tests/mod.rs @@ -18,8 +18,8 @@ fn gost94_test_rand() { let mut h = Gost94Test::new(); feed_rand_16mib(&mut h); assert_eq!( - h.finalize()[..], - hex!("fdd1b9f220898c117f82d664716795e12f5e9f458ee8cd71d014329438db5089")[..] + h.finalize(), + hex!("fdd1b9f220898c117f82d664716795e12f5e9f458ee8cd71d014329438db5089") ); } @@ -28,8 +28,8 @@ fn gost94_cryptopro_rand() { let mut h = Gost94CryptoPro::new(); feed_rand_16mib(&mut h); assert_eq!( - h.finalize()[..], - hex!("1d539ea8a318df8c13d304fcfd9beeec188bb48683d9d7f4c4a3750cff6ef22a")[..] + h.finalize(), + hex!("1d539ea8a318df8c13d304fcfd9beeec188bb48683d9d7f4c4a3750cff6ef22a") ); } @@ -42,7 +42,7 @@ fn gost_engine_tests() { h.update(b"12345670"); } assert_eq!( - h.finalize_reset().as_slice(), + h.finalize_reset(), hex!("f7fc6d16a6a5c12ac4f7d320e0fd0d8354908699125e09727a4ef929122b1cae"), ); @@ -50,7 +50,7 @@ fn gost_engine_tests() { h.update(b"\x00\x01\x02\x15\x84\x67\x45\x31"); } assert_eq!( - h.finalize_reset().as_slice(), + h.finalize_reset(), hex!("69f529aa82d9344ab0fa550cdf4a70ecfd92a38b5520b1906329763e09105196"), ); @@ -60,7 +60,7 @@ fn gost_engine_tests() { } h.update(&buf[0..539]); assert_eq!( - h.finalize_reset().as_slice(), + h.finalize_reset(), hex!("bd5f1e4b539c7b00f0866afdbc8ed452503a18436061747a343f43efe888aac9"), ); @@ -72,7 +72,7 @@ fn gost_engine_tests() { } h.update("12345\n"); assert_eq!( - h.finalize().as_slice(), + h.finalize(), hex!("e5d3ac4ea3f67896c51ff919cedb9405ad771e39f0f2eab103624f9a758e506f"), ); } @@ -81,7 +81,7 @@ fn gost_engine_tests() { fn arithmetic_overflow_regression() { let mut h = Gost94Test::default(); h.update(&include_bytes!("data/arithmetic_overflow.bin")[..]); - h.finalize().as_slice(); + h.finalize(); } #[test] @@ -89,7 +89,7 @@ fn gost_ua_engine_tests() { let mut h = Gost94UA::new(); h.update(b"test"); assert_eq!( - h.finalize_reset().as_slice(), + h.finalize_reset(), hex!("7c536414f8b5b9cc649fdf3cccb2685c1a12622956308e34f31c50ed7b3af56c"), ); } diff --git a/groestl/LICENSE-MIT b/groestl/LICENSE-MIT index f39f9ff82..05ad2e61a 100644 --- a/groestl/LICENSE-MIT +++ b/groestl/LICENSE-MIT @@ -1,4 +1,4 @@ -Copyright (c) 2020 RustCrypto Developers +Copyright (c) 2020-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/groestl/README.md b/groestl/README.md index e80f02902..769239098 100644 --- a/groestl/README.md +++ b/groestl/README.md @@ -7,9 +7,22 @@ [![Project Chat][chat-image]][chat-link] [![Build Status][build-image]][build-link] -Pure Rust implementation of the [Grøstl hash function][1]. +Pure Rust implementation of the [Grøstl] cryptographic hash function. -[Documentation][docs-link] +## Examples + +```rust +use groestl::{Digest, Groestl256}; +use hex_literal::hex; + +let mut hasher = Groestl256::default(); +hasher.update(b"my message"); +let result = hasher.finalize(); + +assert_eq!(result, hex!("dc0283ca481efa76b7c19dd5a0b763dff0e867451bd9488a9c59f6c8b8047a86")); +``` + +Also, see the [examples section] in the RustCrypto/hashes readme. ## Minimum Supported Rust Version @@ -25,10 +38,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 +66,5 @@ dual licensed as above, without any additional terms or conditions. [//]: # (general links) -[1]: https://en.wikipedia.org/wiki/Gr%C3%B8stl +[Grøstl]: https://en.wikipedia.org/wiki/Grøstl +[examples section]: https://github.com/RustCrypto/hashes#Examples diff --git a/groestl/src/lib.rs b/groestl/src/lib.rs index 730477f3d..a467c0ed7 100644 --- a/groestl/src/lib.rs +++ b/groestl/src/lib.rs @@ -1,31 +1,5 @@ -//! An implementation of the [Grøstl][1] cryptographic hash function. -//! -//! # Usage -//! -//! ``` -//! use groestl::{Digest, Groestl256}; -//! use hex_literal::hex; -//! -//! // create a Groestl-256 hasher instance -//! let mut hasher = Groestl256::default(); -//! -//! // process input message -//! hasher.update(b"my message"); -//! -//! // acquire hash digest in the form of Array, -//! // which in this case is equivalent to [u8; 32] -//! let result = hasher.finalize(); -//! assert_eq!(result[..], hex!(" -//! dc0283ca481efa76b7c19dd5a0b763dff0e867451bd9488a9c59f6c8b8047a86 -//! ")); -//! ``` -//! -//! Also see [RustCrypto/hashes][2] readme. -//! -//! [1]: https://en.wikipedia.org/wiki/Grøstl -//! [2]: https://github.com/RustCrypto/hashes - #![no_std] +#![doc = include_str!("../README.md")] #![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" diff --git a/groestl/tests/mod.rs b/groestl/tests/mod.rs index 41a5cf261..6b23220e5 100755 --- a/groestl/tests/mod.rs +++ b/groestl/tests/mod.rs @@ -13,8 +13,8 @@ fn groestl224_rand() { let mut h = Groestl224::new(); feed_rand_16mib(&mut h); assert_eq!( - h.finalize()[..], - hex!("2000744c2f85a7fb4733e97da8db00069dd6defa9186dac3461dfeb8")[..] + h.finalize(), + hex!("2000744c2f85a7fb4733e97da8db00069dd6defa9186dac3461dfeb8"), ); } @@ -23,35 +23,33 @@ fn groestl256_rand() { let mut h = Groestl256::new(); feed_rand_16mib(&mut h); assert_eq!( - h.finalize()[..], - hex!("aac71c789678f627a6474605322ae98d1647e47f405d00b1461b90ee5f0cfbc4")[..] + h.finalize(), + hex!("aac71c789678f627a6474605322ae98d1647e47f405d00b1461b90ee5f0cfbc4"), ); } #[test] -#[rustfmt::skip] fn groestl384_rand() { let mut h = Groestl384::new(); feed_rand_16mib(&mut h); assert_eq!( - h.finalize()[..], - hex!(" - dab78eea895a6dde0c53dc02fc79c7986f5d6811618ca6e5922f01e8aca9bfeb - 20ed5eda4130bf0ab474ac0b6f0290f8 - ")[..] + h.finalize(), + hex!( + "dab78eea895a6dde0c53dc02fc79c7986f5d6811618ca6e5922f01e8aca9bfeb" + "20ed5eda4130bf0ab474ac0b6f0290f8" + ), ); } #[test] -#[rustfmt::skip] fn groestl512_rand() { let mut h = Groestl512::new(); feed_rand_16mib(&mut h); assert_eq!( - h.finalize()[..], - hex!(" - 7e4d8257c217c7ae59331126e0f984f145e9789862de7c099675ac29e46424ef - e93543974fa7113190d492f607f629a03db35ec5551abcb2785ae145fd3c543f - ")[..], + h.finalize(), + hex!( + "7e4d8257c217c7ae59331126e0f984f145e9789862de7c099675ac29e46424ef" + "e93543974fa7113190d492f607f629a03db35ec5551abcb2785ae145fd3c543f" + ), ); } diff --git a/jh/LICENSE-MIT b/jh/LICENSE-MIT index 50c61807c..3b73c41cf 100644 --- a/jh/LICENSE-MIT +++ b/jh/LICENSE-MIT @@ -1,4 +1,4 @@ -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/jh/README.md b/jh/README.md index 938669dae..bc573194f 100644 --- a/jh/README.md +++ b/jh/README.md @@ -9,7 +9,27 @@ Pure Rust implementation of the [JH] cryptographic hash function. -[Documentation][docs-link] +There are 4 standard versions of the JH hash function: + +* JH-224 +* JH-256 +* JH-384 +* JH-512 + +## Examples + +```rust +use jh::{Digest, Jh256}; +use hex_literal::hex; + +let mut hasher = Jh256::new(); +hasher.update(b"hello"); +let result = hasher.finalize(); + +assert_eq!(result, hex!("94fd3f4c564957c6754265676bf8b244c707d3ffb294e18af1f2e4f9b8306089")); +``` + +Also, see the [examples section] in the RustCrypto/hashes readme. ## Minimum Supported Rust Version @@ -25,10 +45,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. @@ -54,3 +74,4 @@ dual licensed as above, without any additional terms or conditions. [//]: # (general links) [JH]: https://en.wikipedia.org/wiki/JH_(hash_function) +[examples section]: https://github.com/RustCrypto/hashes#Examples diff --git a/jh/src/lib.rs b/jh/src/lib.rs index 93e6e891b..cfae16f1a 100644 --- a/jh/src/lib.rs +++ b/jh/src/lib.rs @@ -1,37 +1,5 @@ -//! Implementation of the [JH] cryptographic hash function. -//! -//! There are 4 standard versions of the JH hash function: -//! -//! * [JH-224][Jh224] -//! * [JH-256][Jh256] -//! * [JH-384][Jh384] -//! * [JH-512][Jh512] -//! -//! # Examples -//! -//! Hash functionality is usually accessed via the [`Digest`] trait: -//! -//! ``` -//! use hex_literal::hex; -//! use jh::{Digest, Jh256}; -//! -//! // create a JH-256 object -//! let mut hasher = Jh256::new(); -//! -//! // write input message -//! hasher.update(b"hello"); -//! -//! // read hash digest -//! let result = hasher.finalize(); -//! -//! let expected = hex!("94fd3f4c564957c6754265676bf8b244c707d3ffb294e18af1f2e4f9b8306089"); -//! assert_eq!(result[..], expected[..]); -//! ``` -//! Also see [RustCrypto/hashes] readme. -//! -//! [JH]: https://en.wikipedia.org/wiki/JH_(hash_function) -//! [RustCrypto/hashes]: https://github.com/RustCrypto/hashes #![no_std] +#![doc = include_str!("../README.md")] #![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" diff --git a/k12/LICENSE-MIT b/k12/LICENSE-MIT index f39f9ff82..05ad2e61a 100644 --- a/k12/LICENSE-MIT +++ b/k12/LICENSE-MIT @@ -1,4 +1,4 @@ -Copyright (c) 2020 RustCrypto Developers +Copyright (c) 2020-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/k12/README.md b/k12/README.md index 1a2ba6d42..e101a9821 100644 --- a/k12/README.md +++ b/k12/README.md @@ -6,10 +6,7 @@ ![Rust Version][rustc-image] [![Build Status][build-image]][build-link] -Pure Rust implementation of the [KangarooTwelve][1] eXtendable-Output Function -(XOF). - -[Documentation][docs-link] +Pure Rust implementation of the [KangarooTwelve] eXtendable-Output Function (XOF). ## Minimum Supported Rust Version @@ -25,10 +22,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 +50,4 @@ dual licensed as above, without any additional terms or conditions. [//]: # (general links) -[1]: https://keccak.team/kangarootwelve.html +[KangarooTwelve]: https://keccak.team/kangarootwelve.html diff --git a/k12/src/lib.rs b/k12/src/lib.rs index 7f1602ec8..129da40b3 100644 --- a/k12/src/lib.rs +++ b/k12/src/lib.rs @@ -1,9 +1,5 @@ -//! Pure Rust implementation of the KangarooTwelve cryptographic hash -//! algorithm, based on the reference implementation: -//! -//! - #![no_std] +#![doc = include_str!("../README.md")] #![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" diff --git a/k12/tests/mod.rs b/k12/tests/mod.rs index 36b5b29b8..7f54c2676 100644 --- a/k12/tests/mod.rs +++ b/k12/tests/mod.rs @@ -12,7 +12,6 @@ fn digest_and_box(data: &[u8], n: usize) -> Box<[u8]> { } #[test] -#[rustfmt::skip] fn empty() { // Source: reference paper assert_eq!( @@ -22,10 +21,10 @@ fn empty() { assert_eq!( digest_and_box(b"", 64)[..], - hex!(" - 1ac2d450fc3b4205d19da7bfca1b37513c0803577ac7167f06fe2ce1f0ef39e5 - 4269c056b8c82e48276038b6d292966cc07a3d4645272e31ff38508139eb0a71 - ")[..] + hex!( + "1ac2d450fc3b4205d19da7bfca1b37513c0803577ac7167f06fe2ce1f0ef39e5" + "4269c056b8c82e48276038b6d292966cc07a3d4645272e31ff38508139eb0a71" + )[..], ); assert_eq!( @@ -83,11 +82,11 @@ fn input_multiple_of_chunk_size_minus_one() { hex!("daacf62e434bdd126fbe9e61fae38d1429e9dddfaf8f999095585c3cbf366a4a"), hex!("eac3722b4b7db10af973ed7ca60e113a19fab895b46476a9aac51ead099e6ba4"), ]; - for i in 0..expected.len() { + for (i, exp_res) in expected.iter().enumerate() { let len = 8192 * (i + 1) - 1; let m: Vec = (0..len).map(|j| (j % 251) as u8).collect(); let result = digest_and_box(&m, 32); - assert_eq!(result[..], expected[i as usize][..]); + assert_eq!(result[..], exp_res[..]); } } @@ -100,10 +99,10 @@ fn input_multiple_of_chunk_size() { hex!("f4082a8fe7d1635aa042cd1da63bf235f91c231886c29896f9fe3818c60cd360"), hex!("d14f8dc243c206004ca8a996997e5ae16a8bdda288f6c90d20d7c43c1a408618"), ]; - for i in 0..expected.len() { + for (i, exp_res) in expected.iter().enumerate() { let len = 8192 * (i + 1); let m: Vec = (0..len).map(|j| (j % 251) as u8).collect(); let result = digest_and_box(&m, 32); - assert_eq!(result[..], expected[i as usize][..]); + assert_eq!(result[..], exp_res[..]); } } diff --git a/md2/LICENSE-MIT b/md2/LICENSE-MIT index ed3fa4d31..af2f14b8b 100644 --- a/md2/LICENSE-MIT +++ b/md2/LICENSE-MIT @@ -1,4 +1,5 @@ Copyright (c) 2016 felipeamp +Copyright (c) 2016-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/md2/README.md b/md2/README.md index 8267d5c50..d24bb58fb 100644 --- a/md2/README.md +++ b/md2/README.md @@ -7,9 +7,22 @@ [![Project Chat][chat-image]][chat-link] [![Build Status][build-image]][build-link] -Pure Rust implementation of the [MD2 hash function][1]. +Pure Rust implementation of the [MD2] cryptographic hash algorithm. -[Documentation][docs-link] +## Examples + +```rust +use md2::{Md2, Digest}; +use hex_literal::hex; + +let mut hasher = Md2::new(); +hasher.update(b"hello world"); +let hash = hasher.finalize(); + +assert_eq!(hash, hex!("d9cce882ee690a5c1ce70beff3a78c77")); +``` + +Also, see the [examples section] in the RustCrypto/hashes readme. ## Minimum Supported Rust Version @@ -25,10 +38,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 +66,5 @@ dual licensed as above, without any additional terms or conditions. [//]: # (general links) -[1]: https://en.wikipedia.org/wiki/MD2_(hash_function) +[MD2]: https://en.wikipedia.org/wiki/MD2_(hash_function) +[examples section]: https://github.com/RustCrypto/hashes#Examples diff --git a/md2/src/lib.rs b/md2/src/lib.rs index 7beb7effe..76c5a5564 100644 --- a/md2/src/lib.rs +++ b/md2/src/lib.rs @@ -1,29 +1,5 @@ -//! An implementation of the [MD2][1] cryptographic hash algorithm. -//! -//! # Usage -//! -//! ```rust -//! use md2::{Md2, Digest}; -//! use hex_literal::hex; -//! -//! // create a Md2 hasher instance -//! let mut hasher = Md2::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; 16] -//! let result = hasher.finalize(); -//! assert_eq!(result[..], hex!("d9cce882ee690a5c1ce70beff3a78c77")); -//! ``` -//! -//! Also see [RustCrypto/hashes][2] readme. -//! -//! [1]: https://en.wikipedia.org/wiki/MD4 -//! [2]: https://github.com/RustCrypto/hashes - #![no_std] +#![doc = include_str!("../README.md")] #![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" diff --git a/md2/tests/mod.rs b/md2/tests/mod.rs index d43f0f4cb..21e4cc14a 100644 --- a/md2/tests/mod.rs +++ b/md2/tests/mod.rs @@ -8,8 +8,5 @@ digest::new_test!(md2_main, "md2", Md2, fixed_reset_test); fn md2_rand() { let mut h = Md2::new(); feed_rand_16mib(&mut h); - assert_eq!( - h.finalize()[..], - hex!("f9638c7be725f4d0b5ac342560af1a5b")[..] - ); + assert_eq!(h.finalize(), hex!("f9638c7be725f4d0b5ac342560af1a5b")); } diff --git a/md4/LICENSE-MIT b/md4/LICENSE-MIT index fbed5b4cb..775532acf 100644 --- a/md4/LICENSE-MIT +++ b/md4/LICENSE-MIT @@ -1,4 +1,5 @@ Copyright (c) 2016 bacher09, Artyom Pavlov +Copyright (c) 2016-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/md4/README.md b/md4/README.md index 7135678c6..bd80a2fe1 100644 --- a/md4/README.md +++ b/md4/README.md @@ -7,9 +7,27 @@ [![Project Chat][chat-image]][chat-link] [![Build Status][build-image]][build-link] -Pure Rust implementation of the [MD4 hash function][1]. +Pure Rust implementation of the [MD4] cryptographic hash algorithm. -[Documentation][docs-link] +## Examples + +```rust +use md4::{Md4, Digest}; +use hex_literal::hex; + +// create a Md4 hasher instance +let mut hasher = Md4::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; 16] +let result = hasher.finalize(); +assert_eq!(result[..], hex!("aa010fbc1d14c795d86ef98c95479d17")); +``` + +Also, see the [examples section] in the RustCrypto/hashes readme. ## Minimum Supported Rust Version @@ -25,10 +43,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 +71,5 @@ dual licensed as above, without any additional terms or conditions. [//]: # (general links) -[1]: https://en.wikipedia.org/wiki/MD4 +[MD4]: https://en.wikipedia.org/wiki/MD4 +[examples section]: https://github.com/RustCrypto/hashes#Examples diff --git a/md4/src/lib.rs b/md4/src/lib.rs index acceb0e32..c25022eba 100644 --- a/md4/src/lib.rs +++ b/md4/src/lib.rs @@ -1,29 +1,5 @@ -//! An implementation of the [MD4][1] cryptographic hash algorithm. -//! -//! # Usage -//! -//! ```rust -//! use md4::{Md4, Digest}; -//! use hex_literal::hex; -//! -//! // create a Md4 hasher instance -//! let mut hasher = Md4::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; 16] -//! let result = hasher.finalize(); -//! assert_eq!(result[..], hex!("aa010fbc1d14c795d86ef98c95479d17")); -//! ``` -//! -//! Also see [RustCrypto/hashes][2] readme. -//! -//! [1]: https://en.wikipedia.org/wiki/MD4 -//! [2]: https://github.com/RustCrypto/hashes - #![no_std] +#![doc = include_str!("../README.md")] #![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" diff --git a/md4/tests/mod.rs b/md4/tests/mod.rs index e7aa88db5..d7681e2ff 100644 --- a/md4/tests/mod.rs +++ b/md4/tests/mod.rs @@ -8,8 +8,5 @@ digest::new_test!(md4_main, "md4", Md4, fixed_reset_test); fn md4_rand() { let mut h = Md4::new(); feed_rand_16mib(&mut h); - assert_eq!( - h.finalize()[..], - hex!("07345abfb6192d85bf6a211381926120")[..] - ); + assert_eq!(h.finalize(), hex!("07345abfb6192d85bf6a211381926120")); } diff --git a/md5/LICENSE-MIT b/md5/LICENSE-MIT index 66cf75563..6c74a37c8 100644 --- a/md5/LICENSE-MIT +++ b/md5/LICENSE-MIT @@ -1,6 +1,7 @@ Copyright (c) 2006-2009 Graydon Hoare Copyright (c) 2009-2013 Mozilla Foundation Copyright (c) 2016 Artyom Pavlov +Copyright (c) 2016-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/md5/README.md b/md5/README.md index 8729f3276..6186ac728 100644 --- a/md5/README.md +++ b/md5/README.md @@ -7,23 +7,36 @@ [![Project Chat][chat-image]][chat-link] [![Build Status][build-image]][build-link] -Pure Rust implementation of the [MD5 hash function][1]. - -[Documentation][docs-link] +Pure Rust implementation of the [MD5] cryptographic hash algorithm. ## ⚠️ Security Warning This crate is provided for the purposes of legacy interoperability with protocols and systems which mandate the use of MD5. -However, MD5 is [cryptographically broken and unsuitable for further use][2]. +However, MD5 is [cryptographically broken and unsuitable for further use][1]. Collision attacks against MD5 are both practical and trivial, and -[theoretical attacks against MD5's preimage resistance have been found][3]. +[theoretical attacks against MD5's preimage resistance have been found][2]. -[RFC6151][4] advises no new IETF protocols can be designed MD5-based constructions, +[RFC 6151] advises no new IETF protocols can be designed MD5-based constructions, including HMAC-MD5. +## Examples + +```rust +use md5::{Md5, Digest}; +use hex_literal::hex; + +let mut hasher = Md5::new(); +hasher.update(b"hello world"); +let hash = hasher.finalize(); + +assert_eq!(hash, hex!("5eb63bbbe01eeed093cb22bb8f5acdc3")); +``` + +Also, see the [examples section] in the RustCrypto/hashes readme. + ## Minimum Supported Rust Version Rust **1.71** or higher. @@ -38,10 +51,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. @@ -66,7 +79,8 @@ dual licensed as above, without any additional terms or conditions. [//]: # (general links) -[1]: https://en.wikipedia.org/wiki/MD5 -[2]: https://www.kb.cert.org/vuls/id/836068 -[3]: https://dl.acm.org/citation.cfm?id=1724151 -[4]: https://tools.ietf.org/html/rfc6151 +[MD5]: https://en.wikipedia.org/wiki/MD5 +[examples section]: https://github.com/RustCrypto/hashes#Examples +[1]: https://www.kb.cert.org/vuls/id/836068 +[2]: https://dl.acm.org/citation.cfm?id=1724151 +[RFC 6151]: https://tools.ietf.org/html/rfc6151 diff --git a/md5/src/lib.rs b/md5/src/lib.rs index 59f5b84d4..53b5dc07c 100644 --- a/md5/src/lib.rs +++ b/md5/src/lib.rs @@ -1,29 +1,5 @@ -//! An implementation of the [MD5][1] cryptographic hash algorithm. -//! -//! # Usage -//! -//! ```rust -//! use md5::{Md5, Digest}; -//! use hex_literal::hex; -//! -//! // create a Md5 hasher instance -//! let mut hasher = Md5::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; 16] -//! let result = hasher.finalize(); -//! assert_eq!(result[..], hex!("5eb63bbbe01eeed093cb22bb8f5acdc3")); -//! ``` -//! -//! Also see [RustCrypto/hashes][2] readme. -//! -//! [1]: https://en.wikipedia.org/wiki/MD5 -//! [2]: https://github.com/RustCrypto/hashes - #![no_std] +#![doc = include_str!("../README.md")] #![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" diff --git a/md5/tests/mod.rs b/md5/tests/mod.rs index 316cb8fbe..175d5060e 100644 --- a/md5/tests/mod.rs +++ b/md5/tests/mod.rs @@ -8,8 +8,5 @@ digest::new_test!(md5_main, "md5", md5::Md5, fixed_reset_test); fn md5_rand() { let mut h = Md5::new(); feed_rand_16mib(&mut h); - assert_eq!( - h.finalize()[..], - hex!("61aec26f1b909578ef638ae02dac0977")[..] - ); + assert_eq!(h.finalize(), hex!("61aec26f1b909578ef638ae02dac0977")); } diff --git a/ripemd/LICENSE-MIT b/ripemd/LICENSE-MIT index efb0b5f8b..6f139a79c 100644 --- a/ripemd/LICENSE-MIT +++ b/ripemd/LICENSE-MIT @@ -1,4 +1,4 @@ -Copyright (c) 2021 RustCrypto Developers +Copyright (c) 2021-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/ripemd/README.md b/ripemd/README.md index 5f7370800..52eb89097 100644 --- a/ripemd/README.md +++ b/ripemd/README.md @@ -7,9 +7,37 @@ [![Project Chat][chat-image]][chat-link] [![Build Status][build-image]][build-link] -Pure Rust implementation of the [RIPEMD] hash functions. +Pure Rust implementation of the [RIPEMD] cryptographic hash. -[Documentation][docs-link] +This crate implements only the modified 1996 versions, not the original +one from 1992. + +Note that RIPEMD-256 provides only the same security as RIPEMD-128, +and RIPEMD-320 provides only the same security as RIPEMD-160. + +## Examples + +```rust +use ripemd::{Ripemd160, Ripemd320, Digest}; +use hex_literal::hex; + +let mut hasher = Ripemd160::new(); +hasher.update(b"Hello world!"); +let hash160 = hasher.finalize(); + +assert_eq!(hash160, hex!("7f772647d88750add82d8e1a7a3e5c0902a346a3")); + +let mut hasher = Ripemd320::new(); +hasher.update(b"Hello world!"); +let hash320 = hasher.finalize(); + +assert_eq!(hash320, hex!( + "f1c1c231d301abcf2d7daae0269ff3e7bc68e623" + "ad723aa068d316b056d26b7d1bb6f0cc0f28336d" +)); +``` + +Also, see the [examples section] in the RustCrypto/hashes readme. ## Minimum Supported Rust Version @@ -25,10 +53,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. @@ -54,3 +82,4 @@ dual licensed as above, without any additional terms or conditions. [//]: # (general links) [RIPEMD]: https://en.wikipedia.org/wiki/RIPEMD +[examples section]: https://github.com/RustCrypto/hashes#Examples diff --git a/ripemd/src/lib.rs b/ripemd/src/lib.rs index 5bb19b977..eb0d04167 100644 --- a/ripemd/src/lib.rs +++ b/ripemd/src/lib.rs @@ -1,44 +1,5 @@ -//! An implementation of the [RIPEMD] cryptographic hash. -//! -//! This crate implements only the modified 1996 versions, not the original -//! one from 1992. -//! -//! Note that RIPEMD-256 provides only the same security as RIPEMD-128, -//! and RIPEMD-320 provides only the same security as RIPEMD-160. -//! -//! # Usage -//! -//! ```rust -//! use hex_literal::hex; -//! use ripemd::{Ripemd160, Ripemd320, Digest}; -//! -//! // create a RIPEMD-160 hasher instance -//! let mut hasher = Ripemd160::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; 20] -//! let result = hasher.finalize(); -//! assert_eq!(result[..], hex!("7f772647d88750add82d8e1a7a3e5c0902a346a3")); -//! -//! // same for RIPEMD-320 -//! let mut hasher = Ripemd320::new(); -//! hasher.update(b"Hello world!"); -//! let result = hasher.finalize(); -//! assert_eq!(&result[..], &hex!(" -//! f1c1c231d301abcf2d7daae0269ff3e7bc68e623 -//! ad723aa068d316b056d26b7d1bb6f0cc0f28336d -//! ")[..]); -//! ``` -//! -//! Also see [RustCrypto/hashes] readme. -//! -//! [RIPEMD]: https://en.wikipedia.org/wiki/RIPEMD -//! [RustCrypto/hashes]: https://github.com/RustCrypto/hashes - #![no_std] +#![doc = include_str!("../README.md")] #![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" diff --git a/ripemd/tests/mod.rs b/ripemd/tests/mod.rs index 96d3c0086..fe2a78e27 100644 --- a/ripemd/tests/mod.rs +++ b/ripemd/tests/mod.rs @@ -25,10 +25,7 @@ fn ripemd128_1mil_a() { fn ripemd128_rand() { let mut h = Ripemd128::new(); feed_rand_16mib(&mut h); - assert_eq!( - h.finalize()[..], - hex!("01eb52529bcec15bd0cb4040ec998632")[..] - ); + assert_eq!(h.finalize(), hex!("01eb52529bcec15bd0cb4040ec998632")); } #[test] @@ -49,8 +46,8 @@ fn ripemd160_rand() { let mut h = Ripemd160::new(); feed_rand_16mib(&mut h); assert_eq!( - h.finalize()[..], - hex!("bcd8c672932125776af3c60eeeb58bbaf206f386")[..] + h.finalize(), + hex!("bcd8c672932125776af3c60eeeb58bbaf206f386") ); } @@ -63,7 +60,7 @@ fn ripemd256_1mil_a() { } assert_eq!( h.finalize(), - hex!("ac953744e10e31514c150d4d8d7b677342e33399788296e43ae4850ce4f97978") + hex!("ac953744e10e31514c150d4d8d7b677342e33399788296e43ae4850ce4f97978"), ); } @@ -72,13 +69,12 @@ fn ripemd256_rand() { let mut h = Ripemd256::new(); feed_rand_16mib(&mut h); assert_eq!( - h.finalize()[..], - hex!("6492ffe075896441b737900bdf58fc960e77477e42a2a61bc02c66fd689b69d0")[..] + h.finalize(), + hex!("6492ffe075896441b737900bdf58fc960e77477e42a2a61bc02c66fd689b69d0"), ); } #[test] -#[rustfmt::skip] fn ripemd320_1mil_a() { let mut h = Ripemd320::new(); let buf = [b'a'; 1000]; @@ -87,23 +83,22 @@ fn ripemd320_1mil_a() { } assert_eq!( h.finalize(), - hex!(" - bdee37f4371e20646b8b0d862dda16292ae36f40 - 965e8c8509e63d1dbddecc503e2b63eb9245bb66 - ") + hex!( + "bdee37f4371e20646b8b0d862dda16292ae36f40" + "965e8c8509e63d1dbddecc503e2b63eb9245bb66" + ), ); } #[test] -#[rustfmt::skip] fn ripemd320_rand() { let mut h = Ripemd320::new(); feed_rand_16mib(&mut h); assert_eq!( - h.finalize()[..], - hex!(" - 3a905312162c5c173639f6cc1cdf51d14e8bda02 - 865767592e26d9343fbec348ce55ce39b4b4b56f - ")[..] + h.finalize(), + hex!( + "3a905312162c5c173639f6cc1cdf51d14e8bda02" + "865767592e26d9343fbec348ce55ce39b4b4b56f" + ), ); } diff --git a/sha1/LICENSE-MIT b/sha1/LICENSE-MIT index 66cf75563..6c74a37c8 100644 --- a/sha1/LICENSE-MIT +++ b/sha1/LICENSE-MIT @@ -1,6 +1,7 @@ Copyright (c) 2006-2009 Graydon Hoare Copyright (c) 2009-2013 Mozilla Foundation Copyright (c) 2016 Artyom Pavlov +Copyright (c) 2016-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/sha1/README.md b/sha1/README.md index 3546d5004..019d23351 100644 --- a/sha1/README.md +++ b/sha1/README.md @@ -7,18 +7,43 @@ [![Project Chat][chat-image]][chat-link] [![Build Status][build-image]][build-link] -Pure Rust implementation of the [SHA-1 hash function][1]. +Pure Rust implementation of the [SHA-1] cryptographic hash algorithm. -[Documentation][docs-link] - -## 🚨 Warning: Cryptographically Broken 🚨 +## 🚨 Warning: Cryptographically Broken! 🚨 The SHA-1 hash function should be considered cryptographically broken and unsuitable for further use in any security critical capacity, as it is -[practically vulnerable to chosen-prefix collisions][2]. +[practically vulnerable to chosen-prefix collisions][1]. We provide this crate for legacy interoperability purposes only. +## Examples + +### One-shot API + +```rust +use hex_literal::hex; +use sha1::{Sha1, Digest}; + +let result = Sha1::digest(b"hello world"); +assert_eq!(result, hex!("2aae6c35c94fcfb415dbe95f408b9ce91ee846ed")); +``` + +### Incremental API + +```rust +use hex_literal::hex; +use sha1::{Sha1, Digest}; + +let mut hasher = Sha1::new(); +hasher.update(b"hello world"); +let hash = hasher.finalize(); + +assert_eq!(hash, hex!("2aae6c35c94fcfb415dbe95f408b9ce91ee846ed")); +``` + +Also, see the [examples section] in the RustCrypto/hashes readme. + ## Minimum Supported Rust Version Rust **1.71** or higher. @@ -33,10 +58,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. @@ -61,5 +86,6 @@ dual licensed as above, without any additional terms or conditions. [//]: # (general links) -[1]: https://en.wikipedia.org/wiki/SHA-1 -[2]: https://sha-mbles.github.io/ +[SHA-1]: https://en.wikipedia.org/wiki/SHA-1 +[1]: https://sha-mbles.github.io/ +[examples section]: https://github.com/RustCrypto/hashes#Examples diff --git a/sha1/src/lib.rs b/sha1/src/lib.rs index 5ea8de75e..647f0ace0 100644 --- a/sha1/src/lib.rs +++ b/sha1/src/lib.rs @@ -1,58 +1,5 @@ -//! Pure Rust implementation of the [SHA-1][1] cryptographic hash algorithm -//! with optional hardware-specific optimizations. -//! -//! # 🚨 Warning: Cryptographically Broken! 🚨 -//! -//! The SHA-1 hash function should be considered cryptographically broken and -//! unsuitable for further use in any security critical capacity, as it is -//! [practically vulnerable to chosen-prefix collisions][2]. -//! -//! We provide this crate for legacy interoperability purposes only. -//! -//! # Usage -//! -//! ## One-shot API -//! -//! ```rust -//! use hex_literal::hex; -//! use sha1::{Sha1, Digest}; -//! -//! let result = Sha1::digest(b"hello world"); -//! assert_eq!(result[..], hex!("2aae6c35c94fcfb415dbe95f408b9ce91ee846ed")); -//! ``` -//! -//! ## Incremental API -//! -//! ```rust -//! use hex_literal::hex; -//! use sha1::{Sha1, Digest}; -//! -//! // create a Sha1 object -//! let mut hasher = Sha1::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; 20] -//! let result = hasher.finalize(); -//! assert_eq!(result[..], hex!("2aae6c35c94fcfb415dbe95f408b9ce91ee846ed")); -//! ``` -//! -//! Also see [RustCrypto/hashes][3] readme. -//! -//! # Note for users of `sha1 v0.6` -//! -//! This crate has been transferred to the RustCrypto organization and uses -//! implementation previously published as the `sha-1` crate. The previous -//! zero dependencies version is now published as the [`sha1_smol`] crate. -//! -//! [1]: https://en.wikipedia.org/wiki/SHA-1 -//! [2]: https://sha-mbles.github.io/ -//! [3]: https://github.com/RustCrypto/hashes -//! [`sha1_smol`]: https://github.com/mitsuhiko/sha1-smol/ - #![no_std] +#![doc = include_str!("../README.md")] #![cfg_attr(docsrs, feature(doc_cfg))] #![doc( html_logo_url = "https://raw.githubusercontent.com/RustCrypto/media/6ee8e381/logo.svg", diff --git a/sha1/tests/mod.rs b/sha1/tests/mod.rs index 04aa69f1c..6f26dabc3 100644 --- a/sha1/tests/mod.rs +++ b/sha1/tests/mod.rs @@ -9,7 +9,7 @@ fn sha1_rand() { let mut h = Sha1::new(); feed_rand_16mib(&mut h); assert_eq!( - h.finalize()[..], - hex!("7e565a25a8b123e9881addbcedcd927b23377a78")[..] + h.finalize(), + hex!("7e565a25a8b123e9881addbcedcd927b23377a78"), ); } diff --git a/sha2/LICENSE-MIT b/sha2/LICENSE-MIT index 66cf75563..6c74a37c8 100644 --- a/sha2/LICENSE-MIT +++ b/sha2/LICENSE-MIT @@ -1,6 +1,7 @@ Copyright (c) 2006-2009 Graydon Hoare Copyright (c) 2009-2013 Mozilla Foundation Copyright (c) 2016 Artyom Pavlov +Copyright (c) 2016-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/sha2/README.md b/sha2/README.md index 8d24f5e7c..518cf1df7 100644 --- a/sha2/README.md +++ b/sha2/README.md @@ -7,12 +7,52 @@ [![Project Chat][chat-image]][chat-link] [![Build Status][build-image]][build-link] -Pure Rust implementation of the [SHA-2 hash function family][1] -including SHA-224, SHA-256, SHA-384, and SHA-512. +Pure Rust implementation of the [SHA-2] cryptographic hash algorithms. -[Documentation][docs-link] +There are 6 standard algorithms specified in the SHA-2 standard: +`Sha224`, `Sha256`, `Sha512_224`, `Sha512_256`, `Sha384`, and `Sha512`. - +Algorithmically, there are only 2 core algorithms: SHA-256 and SHA-512. +All other algorithms are just applications of these with different initial +hash values, and truncated to different digest bit lengths. The first two +algorithms in the list are based on SHA-256, while the last four are based +on SHA-512. + +## Examples + +### One-shot API + +```rust +use sha2::{Sha256, Digest}; +use hex_literal::hex; + +let hash = Sha256::digest(b"hello world"); +assert_eq!(hash, hex!("b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9")); +``` + +### Incremental API + +```rust +use sha2::{Sha256, Sha512, Digest}; +use hex_literal::hex; + +let mut hasher = Sha256::new(); +hasher.update(b"hello world"); +let hash256 = hasher.finalize(); + +assert_eq!(hash256, hex!("b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9")); + +let mut hasher = Sha512::new(); +hasher.update(b"hello world"); +let hash512 = hasher.finalize(); + +assert_eq!(hash512, hex!( + "309ecc489c12d6eb4cc40f50c902f2b4d0ed77ee511a7c7a9bcd3ca86d4cd86f" + "989dd35bc5ff499670da34255b45b0cfd830e81f605dcf7dc5542e93ae9cd76f" +)); +``` + +Also, see the [examples section] in the RustCrypto/hashes readme. ## Minimum Supported Rust Version @@ -28,10 +68,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. @@ -56,4 +96,5 @@ dual licensed as above, without any additional terms or conditions. [//]: # (general links) -[1]: https://en.wikipedia.org/wiki/SHA-2 +[SHA-2]: https://en.wikipedia.org/wiki/SHA-2 +[examples section]: https://github.com/RustCrypto/hashes#Examples diff --git a/sha2/src/lib.rs b/sha2/src/lib.rs index c178d4eb4..c2d4936d1 100644 --- a/sha2/src/lib.rs +++ b/sha2/src/lib.rs @@ -1,64 +1,5 @@ -//! An implementation of the [SHA-2][1] cryptographic hash algorithms. -//! -//! There are 6 standard algorithms specified in the SHA-2 standard: [`Sha224`], -//! [`Sha256`], [`Sha512_224`], [`Sha512_256`], [`Sha384`], and [`Sha512`]. -//! -//! Algorithmically, there are only 2 core algorithms: SHA-256 and SHA-512. -//! All other algorithms are just applications of these with different initial -//! hash values, and truncated to different digest bit lengths. The first two -//! algorithms in the list are based on SHA-256, while the last four are based -//! on SHA-512. -//! -//! # Usage -//! -//! ## One-shot API -//! -//! ```rust -//! use hex_literal::hex; -//! use sha2::{Sha256, Digest}; -//! -//! let result = Sha256::digest(b"hello world"); -//! assert_eq!(result[..], hex!(" -//! b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 -//! ")[..]); -//! ``` -//! -//! ## Incremental API -//! -//! ```rust -//! use hex_literal::hex; -//! use sha2::{Sha256, Sha512, Digest}; -//! -//! // create a Sha256 object -//! let mut hasher = Sha256::new(); -//! -//! // write input message -//! hasher.update(b"hello world"); -//! -//! // read hash digest and consume hasher -//! let result = hasher.finalize(); -//! -//! assert_eq!(result[..], hex!(" -//! b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 -//! ")[..]); -//! -//! // same for Sha512 -//! let mut hasher = Sha512::new(); -//! hasher.update(b"hello world"); -//! let result = hasher.finalize(); -//! -//! assert_eq!(result[..], hex!(" -//! 309ecc489c12d6eb4cc40f50c902f2b4d0ed77ee511a7c7a9bcd3ca86d4cd86f -//! 989dd35bc5ff499670da34255b45b0cfd830e81f605dcf7dc5542e93ae9cd76f -//! ")[..]); -//! ``` -//! -//! Also see [RustCrypto/hashes][2] readme. -//! -//! [1]: https://en.wikipedia.org/wiki/SHA-2 -//! [2]: https://github.com/RustCrypto/hashes - #![no_std] +#![doc = include_str!("../README.md")] #![cfg_attr(docsrs, feature(doc_cfg))] #![doc( html_logo_url = "https://raw.githubusercontent.com/RustCrypto/media/6ee8e381/logo.svg", diff --git a/sha2/tests/mod.rs b/sha2/tests/mod.rs index 91df4683b..91104229b 100644 --- a/sha2/tests/mod.rs +++ b/sha2/tests/mod.rs @@ -15,21 +15,20 @@ fn sha256_rand() { let mut h = Sha256::new(); feed_rand_16mib(&mut h); assert_eq!( - h.finalize()[..], - hex!("45f51fead87328fe837a86f4f1ac0eb15116ab1473adc0423ef86c62eb2320c7")[..] + h.finalize(), + hex!("45f51fead87328fe837a86f4f1ac0eb15116ab1473adc0423ef86c62eb2320c7"), ); } #[test] -#[rustfmt::skip] fn sha512_rand() { let mut h = Sha512::new(); feed_rand_16mib(&mut h); assert_eq!( - h.finalize()[..], - hex!(" - 9084d75a7c0721541d737b6171eb465dc9ba08a119a182a8508484aa27a176cd - e7c2103b108393eb024493ced4aac56be6f57222cac41b801f11494886264997 - ")[..] + h.finalize(), + hex!( + "9084d75a7c0721541d737b6171eb465dc9ba08a119a182a8508484aa27a176cd" + "e7c2103b108393eb024493ced4aac56be6f57222cac41b801f11494886264997" + ), ); } diff --git a/sha3/LICENSE-MIT b/sha3/LICENSE-MIT index c7ee28b0f..49ee1c853 100644 --- a/sha3/LICENSE-MIT +++ b/sha3/LICENSE-MIT @@ -2,6 +2,7 @@ Copyright (c) 2006-2009 Graydon Hoare Copyright (c) 2009-2013 Mozilla Foundation Copyright (c) 2014 Sébastien Martini Copyright (c) 2016-2023 Artyom Pavlov, Marek Kotewicz +Copyright (c) 2020-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/sha3/README.md b/sha3/README.md index 13bcb74bf..e16d3ef81 100644 --- a/sha3/README.md +++ b/sha3/README.md @@ -7,9 +7,55 @@ [![Project Chat][chat-image]][chat-link] [![Build Status][build-image]][build-link] -Pure Rust implementation of the [SHA-3 (Keccak) hash function][1]. +Pure Rust implementation of the [SHA-3] cryptographic hash algorithms. -[Documentation][docs-link] +There are 6 standard algorithms specified in the SHA-3 standard: + +* `SHA3-224` +* `SHA3-256` +* `SHA3-384` +* `SHA3-512` +* `SHAKE128`, an extendable output function (XOF) +* `SHAKE256`, an extendable output function (XOF) +* `Keccak224`, `Keccak256`, `Keccak384`, `Keccak512` (NIST submission + without padding changes) + +This crates additionally supports the `TurboSHAKE` XOF variant. + +## Examples + +Output size of SHA3-256 is fixed, so its functionality is usually +accessed via the `Digest` trait: + +```rust +use hex_literal::hex; +use sha3::{Digest, Sha3_256}; + +let mut hasher = Sha3_256::new(); +hasher.update(b"abc"); +let hash = hasher.finalize(); + +assert_eq!(hash, hex!("3a985da74fe225b2045c172d6bd390bd855f086e3e9d525b46bfe24511431532")); +``` + +SHAKE functions have an extendable output, so finalization method returns +XOF reader from which results of arbitrary length can be read. Note that +these functions do not implement `Digest`, so lower-level traits have to +be imported: + +```rust +use sha3::{Shake128, digest::{Update, ExtendableOutput, XofReader}}; +use hex_literal::hex; + +let mut hasher = Shake128::default(); +hasher.update(b"abc"); +let mut reader = hasher.finalize_xof(); +let mut buf = [0u8; 10]; +reader.read(&mut buf); +assert_eq!(buf, hex!("5881092dd818bf5cf8a3")); +``` + +Also, see the [examples section] in the RustCrypto/hashes readme. ## Minimum Supported Rust Version @@ -25,10 +71,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 +99,5 @@ dual licensed as above, without any additional terms or conditions. [//]: # (general links) -[1]: https://en.wikipedia.org/wiki/SHA-3 +[SHA-3]: https://en.wikipedia.org/wiki/SHA-3 +[examples section]: https://github.com/RustCrypto/hashes#Examples diff --git a/sha3/src/lib.rs b/sha3/src/lib.rs index a7bc26b63..d7fccecbf 100644 --- a/sha3/src/lib.rs +++ b/sha3/src/lib.rs @@ -1,64 +1,5 @@ -//! An implementation of the [SHA-3][1] cryptographic hash algorithms. -//! -//! There are 6 standard algorithms specified in the SHA-3 standard: -//! -//! * `SHA3-224` -//! * `SHA3-256` -//! * `SHA3-384` -//! * `SHA3-512` -//! * `SHAKE128`, an extendable output function (XOF) -//! * `SHAKE256`, an extendable output function (XOF) -//! * `Keccak224`, `Keccak256`, `Keccak384`, `Keccak512` (NIST submission -//! without padding changes) -//! -//! Additionally supports `TurboSHAKE`. -//! -//! # Examples -//! -//! Output size of SHA3-256 is fixed, so its functionality is usually -//! accessed via the `Digest` trait: -//! -//! ``` -//! use hex_literal::hex; -//! use sha3::{Digest, Sha3_256}; -//! -//! // create a SHA3-256 object -//! let mut hasher = Sha3_256::new(); -//! -//! // write input message -//! hasher.update(b"abc"); -//! -//! // read hash digest -//! let result = hasher.finalize(); -//! -//! assert_eq!(result[..], hex!(" -//! 3a985da74fe225b2045c172d6bd390bd855f086e3e9d525b46bfe24511431532 -//! ")[..]); -//! ``` -//! -//! SHAKE functions have an extendable output, so finalization method returns -//! XOF reader from which results of arbitrary length can be read. Note that -//! these functions do not implement `Digest`, so lower-level traits have to -//! be imported: -//! -//! ``` -//! use sha3::{Shake128, digest::{Update, ExtendableOutput, XofReader}}; -//! use hex_literal::hex; -//! -//! let mut hasher = Shake128::default(); -//! hasher.update(b"abc"); -//! let mut reader = hasher.finalize_xof(); -//! let mut res1 = [0u8; 10]; -//! reader.read(&mut res1); -//! assert_eq!(res1, hex!("5881092dd818bf5cf8a3")); -//! ``` -//! -//! Also see [RustCrypto/hashes][2] readme. -//! -//! [1]: https://en.wikipedia.org/wiki/SHA-3 -//! [2]: https://github.com/RustCrypto/hashes - #![no_std] +#![doc = include_str!("../README.md")] #![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" diff --git a/shabal/LICENSE-MIT b/shabal/LICENSE-MIT index 66cf75563..6c74a37c8 100644 --- a/shabal/LICENSE-MIT +++ b/shabal/LICENSE-MIT @@ -1,6 +1,7 @@ Copyright (c) 2006-2009 Graydon Hoare Copyright (c) 2009-2013 Mozilla Foundation Copyright (c) 2016 Artyom Pavlov +Copyright (c) 2016-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/shabal/README.md b/shabal/README.md index fb2654e76..94fa4db5e 100644 --- a/shabal/README.md +++ b/shabal/README.md @@ -7,39 +7,25 @@ [![Project Chat][chat-image]][chat-link] [![Build Status][build-image]][build-link] -Pure Rust implementation of the [Shabal][1] cryptographic hash algorithm. +Pure Rust implementation of the [Shabal] cryptographic hash algorithm. -[Documentation][docs-link] +There are 5 standard algorithms specified in the Shabal standard: [`Shabal192`], [`Shabal224`], [`Shabal256`], [`Shabal384`], [`Shabal512`]. -## About -There are 5 standard algorithms specified in the Shabal standard: - -* `Shabal192`, which is the `Shabal` algorithm with the result truncated to 192 bits -* `Shabal224`, which is the `Shabal` algorithm with the result truncated to 224 bits -* `Shabal256`, which is the `Shabal` algorithm with the result truncated to 256 bits. -* `Shabal384`, which is the `Shabal` algorithm with the result truncated to 384 bits. -* `Shabal512`, which is the `Shabal` algorithm with the result not truncated. - -There is a single Shabal algorithm. All variants have different initialisation and apart -from Shabal512 all truncate the result. - -## Usage +## Examples ```rust use shabal::{Shabal256, Digest}; +use hex_literal::hex; -// create a Shabal256 hasher instance let mut hasher = Shabal256::new(); +hasher.update(b"helloworld"); +let hash = hasher.finalize(); -// process input message -hasher.input(b"helloworld"); - -// acquire hash digest in the form of GenericArray, -// which in this case is equivalent to [u8; 32] -let result = hasher.result(); -assert_eq!(result[..], hex!("d945dee21ffca23ac232763aa9cac6c15805f144db9d6c97395437e01c8595a8")); +assert_eq!(hash, hex!("d945dee21ffca23ac232763aa9cac6c15805f144db9d6c97395437e01c8595a8")); ``` +Also, see the [examples section] in the RustCrypto/hashes readme. + ## Minimum Supported Rust Version Rust **1.71** or higher. @@ -54,10 +40,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. @@ -82,4 +68,5 @@ dual licensed as above, without any additional terms or conditions. [//]: # (general links) -[1]: https://www.cs.rit.edu/~ark/20090927/Round2Candidates/Shabal.pdf +[Shabal]: https://www.cs.rit.edu/~ark/20090927/Round2Candidates/Shabal.pdf +[examples section]: https://github.com/RustCrypto/hashes#Examples diff --git a/shabal/src/lib.rs b/shabal/src/lib.rs index bb529aa4b..fbfe2da16 100644 --- a/shabal/src/lib.rs +++ b/shabal/src/lib.rs @@ -1,42 +1,5 @@ -//! An implementation of the [Shabal][1] cryptographic hash algorithm. -//! -//! There are 5 standard algorithms specified in the Shabal standard: -//! -//! * `Shabal192`, which is the `Shabal` algorithm with the result truncated to 192 bits -//! * `Shabal224`, which is the `Shabal` algorithm with the result truncated to 224 bits -//! * `Shabal256`, which is the `Shabal` algorithm with the result truncated to 256 bits. -//! * `Shabal384`, which is the `Shabal` algorithm with the result truncated to 384 bits. -//! * `Shabal512`, which is the `Shabal` algorithm with the result not truncated. -//! -//! There is a single Shabal algorithm. All variants have different initialisation and apart -//! from Shabal512 all truncate the result. -//! -//! # Usage -//! -//! ```rust -//! use hex_literal::hex; -//! use shabal::{Shabal256, Digest}; -//! -//! // create a Shabal256 hasher instance -//! let mut hasher = Shabal256::new(); -//! -//! // process input message -//! hasher.update(b"helloworld"); -//! -//! // acquire hash digest in the form of Array, -//! // which in this case is equivalent to [u8; 32] -//! let result = hasher.finalize(); -//! assert_eq!(result[..], hex!(" -//! d945dee21ffca23ac232763aa9cac6c15805f144db9d6c97395437e01c8595a8 -//! ")[..]); -//! ``` -//! -//! Also see [RustCrypto/hashes][2] readme. -//! -//! [1]: https://www.cs.rit.edu/~ark/20090927/Round2Candidates/Shabal.pdf -//! [2]: https://github.com/RustCrypto/hashes - #![no_std] +#![doc = include_str!("../README.md")] #![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" diff --git a/shabal/tests/mod.rs b/shabal/tests/mod.rs index 0e43643d4..08ff31099 100644 --- a/shabal/tests/mod.rs +++ b/shabal/tests/mod.rs @@ -16,8 +16,8 @@ fn shabal192_rand() { let mut h = Shabal192::new(); feed_rand_16mib(&mut h); assert_eq!( - h.finalize()[..], - hex!("a3e480026be158db97976a895b7a015e9e5205986ebc8a89")[..] + h.finalize(), + hex!("a3e480026be158db97976a895b7a015e9e5205986ebc8a89"), ); } @@ -26,8 +26,8 @@ fn shabal224_rand() { let mut h = Shabal224::new(); feed_rand_16mib(&mut h); assert_eq!( - h.finalize()[..], - hex!("a09bedfed92fdffc896e6043ec175aa1f07383c65bde990a3661e3d0")[..] + h.finalize(), + hex!("a09bedfed92fdffc896e6043ec175aa1f07383c65bde990a3661e3d0"), ); } @@ -36,35 +36,33 @@ fn shabal256_rand() { let mut h = Shabal256::new(); feed_rand_16mib(&mut h); assert_eq!( - h.finalize()[..], - hex!("53252a6467450aa1afc1ac25efb493aa65b70e5b2280a4bed7f672c0cfe6f40e")[..] + h.finalize(), + hex!("53252a6467450aa1afc1ac25efb493aa65b70e5b2280a4bed7f672c0cfe6f40e"), ); } #[test] -#[rustfmt::skip] fn shabal384_rand() { let mut h = Shabal384::new(); feed_rand_16mib(&mut h); assert_eq!( - h.finalize()[..], - hex!(" - 15b8ece81e490848c997dba603523be8842c654262e5adc29138d22a01ff0c9f - 2b0a0dc9f3e7702ac3598fb1b9ff2db2 - ")[..] + h.finalize(), + hex!( + "15b8ece81e490848c997dba603523be8842c654262e5adc29138d22a01ff0c9f" + "2b0a0dc9f3e7702ac3598fb1b9ff2db2" + ), ); } #[test] -#[rustfmt::skip] fn shabal512_rand() { let mut h = Shabal512::new(); feed_rand_16mib(&mut h); assert_eq!( - h.finalize()[..], - hex!(" - 66f091bc2ba6c571a776441c08ee0711752344ba8b4c88ea17a078baa70d8c0a - 717b7da24e765867cfcf273a43a58f90e07c0130d1e97adc49f66a0502536e82 - ")[..] + h.finalize(), + hex!( + "66f091bc2ba6c571a776441c08ee0711752344ba8b4c88ea17a078baa70d8c0a" + "717b7da24e765867cfcf273a43a58f90e07c0130d1e97adc49f66a0502536e82" + ), ); } diff --git a/skein/LICENSE-MIT b/skein/LICENSE-MIT index 50c61807c..3b73c41cf 100644 --- a/skein/LICENSE-MIT +++ b/skein/LICENSE-MIT @@ -1,4 +1,4 @@ -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/skein/README.md b/skein/README.md index 092aac08b..d847c6db2 100644 --- a/skein/README.md +++ b/skein/README.md @@ -7,9 +7,28 @@ [![Project Chat][chat-image]][chat-link] [![Build Status][build-image]][build-link] -Pure Rust implementation of the [Skein] family of cryptographic hash algorithms. +Implementation of the [Skein] family of cryptographic hash algorithms. -[Documentation][docs-link] +There are 3 standard versions of the Skein hash function: `Skein256`, `Skein512`, `Skein1024`. + +Output size of the Skein hash functions is arbitrary, so it has to be +fixed using additional type parameter. + +## Examples + +```rust +use hex_literal::hex; +use skein::{Digest, Skein512, consts::U32}; + +let mut hasher = Skein512::::new(); +hasher.update(b"The quick brown fox "); +hasher.update(b"jumps over the lazy dog"); +let hash = hasher.finalize(); + +assert_eq!(hash, hex!("b3250457e05d3060b1a4bbc1428bc75a3f525ca389aeab96cfa34638d96e492a")); +``` + +Also, see the [examples section] in the RustCrypto/hashes readme. ## Minimum Supported Rust Version @@ -25,10 +44,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. @@ -54,3 +73,4 @@ dual licensed as above, without any additional terms or conditions. [//]: # (general links) [Skein]: https://schneier.com/academic/skein +[examples section]: https://github.com/RustCrypto/hashes#Examples diff --git a/skein/src/lib.rs b/skein/src/lib.rs index 57a489034..649ea8a95 100644 --- a/skein/src/lib.rs +++ b/skein/src/lib.rs @@ -1,40 +1,5 @@ -//! Implementation of the [Skein] family of cryptographic hash algorithms. -//! -//! There are 3 standard versions of the Skein hash function: -//! -//! * [`Skein256`] -//! * [`Skein512`] -//! * [`Skein1024`] -//! -//! Output size of the Skein hash functions is arbitrary, so it has to be -//! fixed using additional type parameter -//! -//! # Examples -//! Hash functionality is usually accessed via the [`Digest`] trait: -//! -//! ``` -//! use hex_literal::hex; -//! use skein::{Digest, Skein512, consts::U32}; -//! -//! // Create a Skein-512-256 hasher object -//! let mut hasher = Skein512::::new(); -//! -//! // Write input message -//! hasher.update(b"The quick brown fox "); -//! hasher.update(b"jumps over the lazy dog"); -//! -//! // Read hash digest -//! let result = hasher.finalize(); -//! -//! let expected = hex!("b3250457e05d3060b1a4bbc1428bc75a3f525ca389aeab96cfa34638d96e492a"); -//! assert_eq!(result[..], expected[..]); -//! ``` -//! Also see [RustCrypto/hashes] readme. -//! -//! [Skein]: https://schneier.com/academic/skein -//! [RustCrypto/hashes]: https://github.com/RustCrypto/hashes - #![no_std] +#![doc = include_str!("../README.md")] #![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" @@ -208,5 +173,4 @@ macro_rules! define_hasher { define_hasher!(Skein256Core, Skein256, Threefish256, U32, "Skein-256"); define_hasher!(Skein512Core, Skein512, Threefish512, U64, "Skein-512"); -#[rustfmt::skip] define_hasher!(Skein1024Core, Skein1024, Threefish1024, U128, "Skein-1024"); diff --git a/skein/tests/lib.rs b/skein/tests/mod.rs similarity index 100% rename from skein/tests/lib.rs rename to skein/tests/mod.rs diff --git a/sm3/LICENSE-MIT b/sm3/LICENSE-MIT index c869ada57..6f139a79c 100644 --- a/sm3/LICENSE-MIT +++ b/sm3/LICENSE-MIT @@ -1,4 +1,4 @@ -Copyright (c) 2021 The RustCrypto Project Developers +Copyright (c) 2021-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/sm3/README.md b/sm3/README.md index 32266f11b..9802ce00a 100644 --- a/sm3/README.md +++ b/sm3/README.md @@ -7,9 +7,23 @@ [![Project Chat][chat-image]][chat-link] [![Build Status][build-image]][build-link] -Pure Rust implementation of the [SM3 (OSCCA GM/T 0004-2012)][1] hash function. +Pure Rust implementation of the [SM3] cryptographic hash function defined +in OSCCA GM/T 0004-2012. -[Documentation][docs-link] +## Examples + +```rust +use sm3::{Digest, Sm3}; +use hex_literal::hex; + +let mut hasher = Sm3::new(); +hasher.update(b"hello world"); +let hash = hasher.finalize(); + +assert_eq!(hash, hex!("44f0061e69fa6fdfc290c494654a05dc0c053da7e5c52b84ef93a9d67d3fff88")); +``` + +Also, see the [examples section] in the RustCrypto/hashes readme. ## Minimum Supported Rust Version @@ -25,10 +39,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 +67,5 @@ dual licensed as above, without any additional terms or conditions. [//]: # (general links) -[1]: https://en.wikipedia.org/wiki/sm3 +[SM3]: https://en.wikipedia.org/wiki/SM3_(hash_function) +[examples section]: https://github.com/RustCrypto/hashes#Examples diff --git a/sm3/src/lib.rs b/sm3/src/lib.rs index 891adec56..0452dc1bc 100644 --- a/sm3/src/lib.rs +++ b/sm3/src/lib.rs @@ -1,34 +1,5 @@ -//! An implementation of the [SM3] cryptographic hash function defined -//! in OSCCA GM/T 0004-2012. -//! -//! # Usage -//! Hasher functionality is expressed via traits defined in the [`digest`] -//! crate. -//! -//! ```rust -//! use hex_literal::hex; -//! use sm3::{Digest, Sm3}; -//! -//! // create a hasher object, to use it do not forget to import `Digest` trait -//! let mut hasher = Sm3::new(); -//! -//! // write input message -//! hasher.update(b"hello world"); -//! -//! // read hash digest and consume hasher -//! let result = hasher.finalize(); -//! -//! assert_eq!(result[..], hex!(" -//! 44f0061e69fa6fdfc290c494654a05dc0c053da7e5c52b84ef93a9d67d3fff88 -//! ")[..]); -//! ``` -//! -//! Also see [RustCrypto/hashes] readme. -//! -//! [SM3]: https://en.wikipedia.org/wiki/SM3_(hash_function) -//! [RustCrypto/hashes]: https://github.com/RustCrypto/hashes - #![no_std] +#![doc = include_str!("../README.md")] #![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" diff --git a/sm3/tests/mod.rs b/sm3/tests/mod.rs index fa746c443..54c91ab07 100644 --- a/sm3/tests/mod.rs +++ b/sm3/tests/mod.rs @@ -10,7 +10,7 @@ fn sm3_rand() { let mut h = Sm3::new(); feed_rand_16mib(&mut h); assert_eq!( - h.finalize()[..], - hex!("ad154967b08d636a148dd4c688a6df7add1ed1946af18eb358a9b320de2aca86")[..] + h.finalize(), + hex!("ad154967b08d636a148dd4c688a6df7add1ed1946af18eb358a9b320de2aca86"), ); } diff --git a/streebog/LICENSE-MIT b/streebog/LICENSE-MIT index 78d6d79a4..4abba7d11 100644 --- a/streebog/LICENSE-MIT +++ b/streebog/LICENSE-MIT @@ -1,4 +1,5 @@ Copyright (c) 2016 Artyom Pavlov +Copyright (c) 2016-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/streebog/README.md b/streebog/README.md index fff7ea983..52c023403 100644 --- a/streebog/README.md +++ b/streebog/README.md @@ -7,9 +7,31 @@ [![Project Chat][chat-image]][chat-link] [![Build Status][build-image]][build-link] -Pure Rust implementation of the [Streebog (GOST R 34.11-2012)][1] hash function. +Pure Rust implementation of the [Streebog] cryptographic hash function defined in GOST R 34.11-2012. -[Documentation][docs-link] +## Examples + +```rust +use streebog::{Digest, Streebog256, Streebog512}; +use hex_literal::hex; + +let mut hasher = Streebog256::new(); +hasher.update("The quick brown fox jumps over the lazy dog"); +let hash256 = hasher.finalize(); + +assert_eq!(hash256, hex!("3e7dea7f2384b6c5a3d0e24aaa29c05e89ddd762145030ec22c71a6db8b2c1f4")); + +let mut hasher = Streebog512::new(); +hasher.update("The quick brown fox jumps over the lazy dog."); +let hash512 = hasher.finalize(); + +assert_eq!(hash512, hex!( + "fe0c42f267d921f940faa72bd9fcf84f9f1bd7e9d055e9816e4c2ace1ec83be8" + "2d2957cd59b86e123d8f5adee80b3ca08a017599a9fc1a14d940cf87c77df070" +)); +``` + +Also, see the [examples section] in the RustCrypto/hashes readme. ## Minimum Supported Rust Version @@ -25,10 +47,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 +75,5 @@ dual licensed as above, without any additional terms or conditions. [//]: # (general links) -[1]: https://en.wikipedia.org/wiki/Streebog +[Streebog]: https://en.wikipedia.org/wiki/Streebog +[examples section]: https://github.com/RustCrypto/hashes#Examples diff --git a/streebog/src/lib.rs b/streebog/src/lib.rs index 23a72c8fa..6da989be5 100644 --- a/streebog/src/lib.rs +++ b/streebog/src/lib.rs @@ -1,39 +1,5 @@ -//! An implementation of the [Streebog] cryptographic hash function defined -//! in GOST R 34.11-2012. -//! -//! # Usage -//! ```rust -//! use streebog::{Digest, Streebog256, Streebog512}; -//! use hex_literal::hex; -//! -//! // create Streebog256 hasher state -//! let mut hasher = Streebog256::new(); -//! // write input message -//! hasher.update("The quick brown fox jumps over the lazy dog"); -//! // read hash digest (it will consume hasher) -//! let result = hasher.finalize(); -//! -//! assert_eq!(result[..], hex!(" -//! 3e7dea7f2384b6c5a3d0e24aaa29c05e89ddd762145030ec22c71a6db8b2c1f4 -//! ")[..]); -//! -//! // same for Streebog512 -//! let mut hasher = Streebog512::new(); -//! hasher.update("The quick brown fox jumps over the lazy dog."); -//! let result = hasher.finalize(); -//! -//! assert_eq!(result[..], hex!(" -//! fe0c42f267d921f940faa72bd9fcf84f9f1bd7e9d055e9816e4c2ace1ec83be8 -//! 2d2957cd59b86e123d8f5adee80b3ca08a017599a9fc1a14d940cf87c77df070 -//! ")[..]); -//! ``` -//! -//! See [RustCrypto/hashes][1] readme for additional examples. -//! -//! [Streebog]: https://en.wikipedia.org/wiki/Streebog -//! [1]: https://github.com/RustCrypto/hashes/blob/master/README.md#usage - #![no_std] +#![doc = include_str!("../README.md")] #![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" diff --git a/streebog/tests/mod.rs b/streebog/tests/mod.rs index aeddaefd1..1cba79d92 100644 --- a/streebog/tests/mod.rs +++ b/streebog/tests/mod.rs @@ -21,7 +21,6 @@ new_test!( /// Test vectors from: /// https://github.com/gost-engine/engine/blob/master/test/01-digest.t #[test] -#[rustfmt::skip] fn gost_engine_tests() { let h256 = &mut streebog::Streebog256::new(); let h512 = &mut streebog::Streebog512::new(); @@ -39,24 +38,26 @@ fn gost_engine_tests() { update(h256, h512, b"12345670"); } check( - h256, h512, + h256, + h512, hex!("1906512b86a1283c68cec8419e57113efc562a1d0e95d8f4809542900c416fe4"), - hex!(" - 283587e434864d0d4bea97c0fb10e2dd421572fc859304bdf6a94673d652c590 - 49212bad7802b4fcf5eecc1f8fab569d60f2c20dbd789a7fe4efbd79d8137ee7 - "), + hex!( + "283587e434864d0d4bea97c0fb10e2dd421572fc859304bdf6a94673d652c590" + "49212bad7802b4fcf5eecc1f8fab569d60f2c20dbd789a7fe4efbd79d8137ee7" + ), ); for _ in 0..128 { update(h256, h512, &hex!("0001021584674531")); } check( - h256, h512, + h256, + h512, hex!("2eb1306be3e490f18ff0e2571a077b3831c815c46c7d4fdf9e0e26de4032b3f3"), - hex!(" - 55656e5bcf795b499031a7833cd7dc18fe10d4a47e15be545c6ab3f304a4fe41 - 1c4c39de5b1fc6844880111441e0b92bf1ec2fb7840453fe39a2b70ced461968 - "), + hex!( + "55656e5bcf795b499031a7833cd7dc18fe10d4a47e15be545c6ab3f304a4fe41" + "1c4c39de5b1fc6844880111441e0b92bf1ec2fb7840453fe39a2b70ced461968" + ), ); let mut buf = Vec::new(); @@ -65,12 +66,13 @@ fn gost_engine_tests() { } update(h256, h512, &buf[0..539]); check( - h256, h512, + h256, + h512, hex!("c98a17f9fadff78d08521e4179a7b2e6275f3b1da88339a3cb961a3514e5332e"), - hex!(" - d5ad93fbc9ed7abc1cf28d00827a052b40bea74b04c4fd753102c1bcf9f9dad5 - 142887f8a4cceaa0d64a0a8291592413d6adb956b99138a0023e127ff37bdf08 - "), + hex!( + "d5ad93fbc9ed7abc1cf28d00827a052b40bea74b04c4fd753102c1bcf9f9dad5" + "142887f8a4cceaa0d64a0a8291592413d6adb956b99138a0023e127ff37bdf08" + ), ); for _ in 0..4096 { @@ -81,12 +83,13 @@ fn gost_engine_tests() { } update(h256, h512, b"12345\n"); check( - h256, h512, + h256, + h512, hex!("50e935d725d9359e5991b6b7eba8b3539fca03584d26adf4c827c982ffd49367"), - hex!(" - 1d93645ebfbb477660f98b7d1598e37fbf3bfc8234ead26e2246e1b979e590ac - 46138158a692f9a0c9ac2550758b4d0d4c9fb8af5e595a16d3760c6516443f82 - "), + hex!( + "1d93645ebfbb477660f98b7d1598e37fbf3bfc8234ead26e2246e1b979e590ac" + "46138158a692f9a0c9ac2550758b4d0d4c9fb8af5e595a16d3760c6516443f82" + ), ); } @@ -95,21 +98,20 @@ fn streebog256_rand() { let mut h = Streebog256::new(); feed_rand_16mib(&mut h); assert_eq!( - h.finalize()[..], - hex!("eb5783a2d3f1aa52136701c07c90272a45f017733d898cdfc02302ad2ac8ebed")[..], + h.finalize(), + hex!("eb5783a2d3f1aa52136701c07c90272a45f017733d898cdfc02302ad2ac8ebed"), ); } #[test] -#[rustfmt::skip] fn streebog512_rand() { let mut h = Streebog512::new(); feed_rand_16mib(&mut h); assert_eq!( - h.finalize()[..], - hex!(" - d78479790925e257b1d65bec84cbe9bbd9bf0abcefb9f99aa065cc533187224f - 2bead756c96297dcd17728a838e3117a9123559be655175bf4cdac0ee11fba75 - ")[..], + h.finalize(), + hex!( + "d78479790925e257b1d65bec84cbe9bbd9bf0abcefb9f99aa065cc533187224f" + "2bead756c96297dcd17728a838e3117a9123559be655175bf4cdac0ee11fba75" + ), ); } diff --git a/tiger/LICENSE-MIT b/tiger/LICENSE-MIT index d62c85c68..27404158b 100644 --- a/tiger/LICENSE-MIT +++ b/tiger/LICENSE-MIT @@ -1,5 +1,5 @@ -Copyright (c) 2021 RustCrypto Developers Copyright (c) 2020 Ulrik Mikaelsson +Copyright (c) 2020-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/tiger/README.md b/tiger/README.md index 7ead3daf7..c88d69f12 100644 --- a/tiger/README.md +++ b/tiger/README.md @@ -7,9 +7,24 @@ [![Project Chat][chat-image]][chat-link] [![Build Status][build-image]][build-link] -Pure Rust implementation of the [Tiger] hash function. +Pure Rust implementation of the [Tiger] cryptographic hash algorithms. -[Documentation][docs-link] +Tiger2 is a variant of the original Tiger with a small padding tweak. + +## Examples + +```rust +use tiger::{Tiger, Digest}; +use hex_literal::hex; + +let mut hasher = Tiger::new(); +hasher.update(b"hello world"); +let hash = hasher.finalize(); + +assert_eq!(hash, hex!("4c8fbddae0b6f25832af45e7c62811bb64ec3e43691e9cc3")); +``` + +Also, see the [examples section] in the RustCrypto/hashes readme. ## Minimum Supported Rust Version @@ -25,10 +40,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,3 +68,4 @@ for inclusion in the work by you, as defined in the Apache-2.0 license, without [//]: # (general links) [Tiger]: http://www.cs.technion.ac.il/~biham/Reports/Tiger/tiger/tiger.html +[examples section]: https://github.com/RustCrypto/hashes#Examples diff --git a/tiger/src/lib.rs b/tiger/src/lib.rs index e288b252e..32690d977 100644 --- a/tiger/src/lib.rs +++ b/tiger/src/lib.rs @@ -1,31 +1,5 @@ -//! An implementation of the [Tiger][1] cryptographic hash algorithms. -//! -//! Tiger2 is a variant of the original Tiger with a small padding tweak. -//! -//! # Usage -//! -//! ```rust -//! use hex_literal::hex; -//! use tiger::{Tiger, Digest}; -//! -//! // create a Tiger object -//! let mut hasher = Tiger::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; 24] -//! let result = hasher.finalize(); -//! assert_eq!(result[..], hex!("4c8fbddae0b6f25832af45e7c62811bb64ec3e43691e9cc3")); -//! ``` -//! -//! Also see [RustCrypto/hashes][2] readme. -//! -//! [1]: https://en.wikipedia.org/wiki/Tiger_(hash_function) -//! [2]: https://github.com/RustCrypto/hashes - #![no_std] +#![doc = include_str!("../README.md")] #![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" diff --git a/tiger/tests/mod.rs b/tiger/tests/mod.rs index 09e78d6c3..6adf7156b 100644 --- a/tiger/tests/mod.rs +++ b/tiger/tests/mod.rs @@ -11,8 +11,8 @@ fn tiger_rand() { let mut h = Tiger::new(); feed_rand_16mib(&mut h); assert_eq!( - h.finalize()[..], - hex!("d12f382ecf3250c14aca7726df15b999dfe99f905cf163d2")[..] + h.finalize(), + hex!("d12f382ecf3250c14aca7726df15b999dfe99f905cf163d2"), ); } @@ -21,7 +21,7 @@ fn tiger2_rand() { let mut h = Tiger2::new(); feed_rand_16mib(&mut h); assert_eq!( - h.finalize()[..], - hex!("1bb7a80144c97f831fdefb635477776dd6c164048ce5895d")[..] + h.finalize(), + hex!("1bb7a80144c97f831fdefb635477776dd6c164048ce5895d"), ); } diff --git a/whirlpool/LICENSE-MIT b/whirlpool/LICENSE-MIT index 66cf75563..6c74a37c8 100644 --- a/whirlpool/LICENSE-MIT +++ b/whirlpool/LICENSE-MIT @@ -1,6 +1,7 @@ Copyright (c) 2006-2009 Graydon Hoare Copyright (c) 2009-2013 Mozilla Foundation Copyright (c) 2016 Artyom Pavlov +Copyright (c) 2016-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/whirlpool/README.md b/whirlpool/README.md index c2ca0e84c..8902f78f4 100644 --- a/whirlpool/README.md +++ b/whirlpool/README.md @@ -7,9 +7,36 @@ [![Project Chat][chat-image]][chat-link] [![Build Status][build-image]][build-link] -Pure Rust implementation of the [Whirlpool hash function][1]. +Pure Rust implementation of the [Whirlpool] cryptographic hash algorithm. -[Documentation][docs-link] +This is the algorithm recommended by NESSIE (New European Schemes for +Signatures, Integrity and Encryption; an European research project). + +The constants used by Whirlpool were changed twice (2001 and 2003) - this +crate only implements the most recent standard. The two older Whirlpool +implementations (sometimes called Whirlpool-0 (pre 2001) and Whirlpool-T +(pre 2003)) were not used much anyway (both have never been recommended +by NESSIE). + +For details see this [page][1]. + +## Examples + +```rust +use whirlpool::{Whirlpool, Digest}; +use hex_literal::hex; + +let mut hasher = Whirlpool::new(); +hasher.update(b"Hello Whirlpool"); +let hash = hasher.finalize(); + +assert_eq!(hash, hex!( + "8eaccdc136903c458ea0b1376be2a5fc9dc5b8ce8892a3b4f43366e2610c206c" + "a373816495e63db0fff2ff25f75aa7162f332c9f518c3036456502a8414d300a" +)); +``` + +Also, see the [examples section] in the RustCrypto/hashes readme. ## Minimum Supported Rust Version @@ -25,10 +52,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 +80,6 @@ dual licensed as above, without any additional terms or conditions. [//]: # (general links) -[1]: https://en.wikipedia.org/wiki/Whirlpool_(hash_function) +[Whirlpool]: https://en.wikipedia.org/wiki/Whirlpool_(hash_function) +[1]: https://web.archive.org/web/20171129084214/http://www.larc.usp.br/~pbarreto/WhirlpoolPage.html +[examples section]: https://github.com/RustCrypto/hashes#Examples diff --git a/whirlpool/src/lib.rs b/whirlpool/src/lib.rs index 6e1293cd2..b091adca4 100644 --- a/whirlpool/src/lib.rs +++ b/whirlpool/src/lib.rs @@ -1,41 +1,5 @@ -//! An implementation of the [Whirlpool][1] cryptographic hash algorithm. -//! -//! This is the algorithm recommended by NESSIE (New European Schemes for -//! Signatures, Integrity and Encryption; an European research project). -//! -//! The constants used by Whirlpool were changed twice (2001 and 2003) - this -//! crate only implements the most recent standard. The two older Whirlpool -//! implementations (sometimes called Whirlpool-0 (pre 2001) and Whirlpool-T -//! (pre 2003)) were not used much anyway (both have never been recommended -//! by NESSIE). -//! -//! For details see [http://www.larc.usp.br/~pbarreto/WhirlpoolPage.html](https://web.archive.org/web/20171129084214/http://www.larc.usp.br/~pbarreto/WhirlpoolPage.html). -//! -//! # Usage -//! -//! ```rust -//! use whirlpool::{Whirlpool, Digest}; -//! use hex_literal::hex; -//! -//! // create a hasher object, to use it do not forget to import `Digest` trait -//! let mut hasher = Whirlpool::new(); -//! // write input message -//! hasher.update(b"Hello Whirlpool"); -//! // read hash digest (it will consume hasher) -//! let result = hasher.finalize(); -//! -//! assert_eq!(result[..], hex!(" -//! 8eaccdc136903c458ea0b1376be2a5fc9dc5b8ce8892a3b4f43366e2610c206c -//! a373816495e63db0fff2ff25f75aa7162f332c9f518c3036456502a8414d300a -//! ")[..]); -//! ``` -//! -//! Also see [RustCrypto/hashes][2] readme. -//! -//! [1]: https://en.wikipedia.org/wiki/Whirlpool_(hash_function) -//! [2]: https://github.com/RustCrypto/hashes - #![no_std] +#![doc = include_str!("../README.md")] #![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" diff --git a/whirlpool/tests/mod.rs b/whirlpool/tests/mod.rs index 491348ed0..e0980f39e 100644 --- a/whirlpool/tests/mod.rs +++ b/whirlpool/tests/mod.rs @@ -5,15 +5,14 @@ use whirlpool::{Digest, Whirlpool}; digest::new_test!(whirlpool_main, "whirlpool", Whirlpool, fixed_reset_test); #[test] -#[rustfmt::skip] fn whirlpool_rand() { let mut h = Whirlpool::new(); feed_rand_16mib(&mut h); assert_eq!( - h.finalize()[..], - hex!(" - 8db0acd78686f8160203b53bfb0c0c1ee2332b856732a311f7de8e4ea4c100cc - dd5267e8b63207e644c96d2ef5cfbb53f2519af1904c48fd2ecf937541998b11 - ")[..] + h.finalize(), + hex!( + "8db0acd78686f8160203b53bfb0c0c1ee2332b856732a311f7de8e4ea4c100cc" + "dd5267e8b63207e644c96d2ef5cfbb53f2519af1904c48fd2ecf937541998b11" + ), ); }