From d2632d3d8ab218f6cfecaac414367299cdf523c7 Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Mon, 24 Jun 2024 11:49:20 +1000 Subject: [PATCH 1/3] hashes: Re-export Hkdf Re-export `Hkdf` from the crate root. While we are at it group the re-exports and skip formatting as is convention around here. --- hashes/src/lib.rs | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/hashes/src/lib.rs b/hashes/src/lib.rs index 09a57d410..a505d9759 100644 --- a/hashes/src/lib.rs +++ b/hashes/src/lib.rs @@ -126,7 +126,12 @@ pub mod siphash24; use core::{convert, fmt, hash}; -pub use hmac::{Hmac, HmacEngine}; +#[rustfmt::skip] // Keep public re-exports separate. +#[doc(inline)] +pub use self::{ + hkdf::Hkdf, + hmac::{Hmac, HmacEngine}, +}; /// A hashing engine which bytes can be serialized into. pub trait HashEngine: Clone + Default { From 264d08005439cde5bc2369e47357fe4594593ddd Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Mon, 24 Jun 2024 11:58:19 +1000 Subject: [PATCH 2/3] hashes: Add hash type alias' In an effort to make the `hashes` crate more ergonomic to use add a bunch of alias' to the crate root - use re-exports where possible and type alias' where required. We intentionally do not rename the `foo::Hash` types so that uses have a choice of either using the module path to differentiate or to use the alias. Update the crate level docs to use the alias' because they are more terse with no loss of clarity. --- hashes/src/lib.rs | 71 ++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 61 insertions(+), 10 deletions(-) diff --git a/hashes/src/lib.rs b/hashes/src/lib.rs index a505d9759..7830d1558 100644 --- a/hashes/src/lib.rs +++ b/hashes/src/lib.rs @@ -12,25 +12,25 @@ //! Hashing a single byte slice or a string: //! //! ```rust -//! use bitcoin_hashes::{sha256, GeneralHash as _}; +//! use bitcoin_hashes::Sha256; //! //! let bytes = [0u8; 5]; -//! let hash_of_bytes = sha256::Hash::hash(&bytes); -//! let hash_of_string = sha256::Hash::hash("some string".as_bytes()); +//! let hash_of_bytes = Sha256::hash(&bytes); +//! let hash_of_string = Sha256::hash("some string".as_bytes()); //! ``` //! //! //! Hashing content from a reader: //! //! ```rust -//! use bitcoin_hashes::{sha256, GeneralHash as _}; +//! use bitcoin_hashes::Sha256; //! //! #[cfg(std)] //! # fn main() -> std::io::Result<()> { //! let mut reader: &[u8] = b"hello"; // in real code, this could be a `File` or `TcpStream` -//! let mut engine = sha256::HashEngine::default(); +//! let mut engine = Sha256::engine(); //! std::io::copy(&mut reader, &mut engine)?; -//! let hash = sha256::Hash::from_engine(engine); +//! let hash = Sha256::from_engine(engine); //! # Ok(()) //! # } //! @@ -39,10 +39,10 @@ //! ``` //! //! -//! Hashing content by [`std::io::Write`] on HashEngine: +//! Hashing content by [`std::io::Write`] on `HashEngine`: //! //! ```rust -//! use bitcoin_hashes::{sha256, Hash as _}; +//! use bitcoin_hashes::Sha256; //! use std::io::Write; //! //! #[cfg(std)] @@ -50,11 +50,11 @@ //! let mut part1: &[u8] = b"hello"; //! let mut part2: &[u8] = b" "; //! let mut part3: &[u8] = b"world"; -//! let mut engine = sha256::HashEngine::default(); +//! let mut engine = Sha256::engine(); //! engine.write_all(part1)?; //! engine.write_all(part2)?; //! engine.write_all(part3)?; -//! let hash = sha256::Hash::from_engine(engine); +//! let hash = Sha256::from_engine(engine); //! # Ok(()) //! # } //! @@ -133,6 +133,57 @@ pub use self::{ hmac::{Hmac, HmacEngine}, }; +/// SHA-1: Alias for the [`sha1::Hash`] hash type. +#[doc(inline)] +pub use sha1::Hash as Sha1; + +/// SHA-256: Alias for the [`sha256::Hash`] hash type. +#[doc(inline)] +pub use sha256::Hash as Sha256; + +/// SHA-384: Alias for the [`sha384::Hash`] hash type. +#[doc(inline)] +pub use sha384::Hash as Sha384; + +/// SHA-512: Alias for the [`sha512::Hash`] hash type. +#[doc(inline)] +pub use sha512::Hash as Sha512; + +/// SHA-512-256: Alias for the [`sha512_256::Hash`] hash type. +#[doc(inline)] +pub use sha512_256::Hash as Sha512_256; + +/// RIPEMD-160: Alias for the [`ripemd160::Hash`] hash type. +#[doc(inline)] +pub use ripemd160::Hash as Ripemd160; + +/// SipHash-2-4: Alias for the [`siphash24::Hash`] hash type. +#[doc(inline)] +pub use siphash24::Hash as Siphash24; + +/// HASH-160: Alias for the [`hash160::Hash`] hash type. +#[doc(inline)] +pub use hash160::Hash as Hash160; + +/// Double SHA-256: Alias for the [`sha256d::Hash`] hash type. +#[doc(inline)] +pub use sha256d::Hash as Sha256d; + +/// Tagged SHA-256: Type alias for the [`sha256t::Hash`] hash type. +pub type Sha256t = sha256t::Hash; + +/// HMAC-SHA-256: Type alias for the [`Hmac`] type. +pub type HmacSha256 = Hmac; + +/// HMAC-SHA-512: Type alias for the [`Hmac`] type. +pub type HmacSha512 = Hmac; + +/// HKDF-HMAC-SHA-256: Type alias for the [`Hkdf`] type. +pub type HkdfSha256 = Hkdf; + +/// HKDF-HMAC-SHA-512: Type alias for the [`Hkdf`] type. +pub type HkdfSha512 = Hkdf; + /// A hashing engine which bytes can be serialized into. pub trait HashEngine: Clone + Default { /// Byte array representing the internal state of the hash engine. From 872ba938cc5f37664b80db5d17876d072181b436 Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Mon, 24 Jun 2024 12:07:04 +1000 Subject: [PATCH 3/3] api: Run just check-api --- api/hashes/all-features.txt | 15 +++++++++++++++ api/hashes/alloc-only.txt | 15 +++++++++++++++ api/hashes/no-features.txt | 15 +++++++++++++++ 3 files changed, 45 insertions(+) diff --git a/api/hashes/all-features.txt b/api/hashes/all-features.txt index 2af40a445..5635a6739 100644 --- a/api/hashes/all-features.txt +++ b/api/hashes/all-features.txt @@ -1,4 +1,13 @@ +#[repr(transparent)] pub struct bitcoin_hashes::Hash160(_) #[repr(transparent)] pub struct bitcoin_hashes::Hmac(_) +#[repr(transparent)] pub struct bitcoin_hashes::Ripemd160(_) +#[repr(transparent)] pub struct bitcoin_hashes::Sha1(_) +#[repr(transparent)] pub struct bitcoin_hashes::Sha256(_) +#[repr(transparent)] pub struct bitcoin_hashes::Sha256d(_) +#[repr(transparent)] pub struct bitcoin_hashes::Sha384(_) +#[repr(transparent)] pub struct bitcoin_hashes::Sha512(_) +#[repr(transparent)] pub struct bitcoin_hashes::Sha512_256(_) +#[repr(transparent)] pub struct bitcoin_hashes::Siphash24(_) #[repr(transparent)] pub struct bitcoin_hashes::hash160::Hash(_) #[repr(transparent)] pub struct bitcoin_hashes::hmac::Hmac(_) #[repr(transparent)] pub struct bitcoin_hashes::ripemd160::Hash(_) @@ -1006,6 +1015,7 @@ pub mod bitcoin_hashes::sha512 pub mod bitcoin_hashes::sha512_256 pub mod bitcoin_hashes::siphash24 pub struct bitcoin_hashes::FromSliceError +pub struct bitcoin_hashes::Hkdf pub struct bitcoin_hashes::HmacEngine pub struct bitcoin_hashes::hkdf::Hkdf pub struct bitcoin_hashes::hkdf::MaxLengthError @@ -1028,6 +1038,11 @@ pub trait bitcoin_hashes::sha256t::Tag pub type bitcoin_hashes::GeneralHash::Engine: bitcoin_hashes::HashEngine pub type bitcoin_hashes::Hash::Bytes: hex_conservative::parse::FromHex + core::marker::Copy pub type bitcoin_hashes::HashEngine::MidState +pub type bitcoin_hashes::HkdfSha256 = bitcoin_hashes::hkdf::Hkdf +pub type bitcoin_hashes::HkdfSha512 = bitcoin_hashes::hkdf::Hkdf +pub type bitcoin_hashes::HmacSha256 = bitcoin_hashes::hmac::Hmac +pub type bitcoin_hashes::HmacSha512 = bitcoin_hashes::hmac::Hmac +pub type bitcoin_hashes::Sha256t = bitcoin_hashes::sha256t::Hash pub type bitcoin_hashes::hash160::Hash::Bytes = [u8; 20] pub type bitcoin_hashes::hash160::Hash::Engine = bitcoin_hashes::sha256::HashEngine pub type bitcoin_hashes::hash160::Hash::Err = hex_conservative::error::HexToArrayError diff --git a/api/hashes/alloc-only.txt b/api/hashes/alloc-only.txt index b72c9ddc6..8624a8836 100644 --- a/api/hashes/alloc-only.txt +++ b/api/hashes/alloc-only.txt @@ -1,4 +1,13 @@ +#[repr(transparent)] pub struct bitcoin_hashes::Hash160(_) #[repr(transparent)] pub struct bitcoin_hashes::Hmac(_) +#[repr(transparent)] pub struct bitcoin_hashes::Ripemd160(_) +#[repr(transparent)] pub struct bitcoin_hashes::Sha1(_) +#[repr(transparent)] pub struct bitcoin_hashes::Sha256(_) +#[repr(transparent)] pub struct bitcoin_hashes::Sha256d(_) +#[repr(transparent)] pub struct bitcoin_hashes::Sha384(_) +#[repr(transparent)] pub struct bitcoin_hashes::Sha512(_) +#[repr(transparent)] pub struct bitcoin_hashes::Sha512_256(_) +#[repr(transparent)] pub struct bitcoin_hashes::Siphash24(_) #[repr(transparent)] pub struct bitcoin_hashes::hash160::Hash(_) #[repr(transparent)] pub struct bitcoin_hashes::hmac::Hmac(_) #[repr(transparent)] pub struct bitcoin_hashes::ripemd160::Hash(_) @@ -847,6 +856,7 @@ pub mod bitcoin_hashes::sha512 pub mod bitcoin_hashes::sha512_256 pub mod bitcoin_hashes::siphash24 pub struct bitcoin_hashes::FromSliceError +pub struct bitcoin_hashes::Hkdf pub struct bitcoin_hashes::HmacEngine pub struct bitcoin_hashes::hkdf::Hkdf pub struct bitcoin_hashes::hkdf::MaxLengthError @@ -868,6 +878,11 @@ pub trait bitcoin_hashes::sha256t::Tag pub type bitcoin_hashes::GeneralHash::Engine: bitcoin_hashes::HashEngine pub type bitcoin_hashes::Hash::Bytes: hex_conservative::parse::FromHex + core::marker::Copy pub type bitcoin_hashes::HashEngine::MidState +pub type bitcoin_hashes::HkdfSha256 = bitcoin_hashes::hkdf::Hkdf +pub type bitcoin_hashes::HkdfSha512 = bitcoin_hashes::hkdf::Hkdf +pub type bitcoin_hashes::HmacSha256 = bitcoin_hashes::hmac::Hmac +pub type bitcoin_hashes::HmacSha512 = bitcoin_hashes::hmac::Hmac +pub type bitcoin_hashes::Sha256t = bitcoin_hashes::sha256t::Hash pub type bitcoin_hashes::hash160::Hash::Bytes = [u8; 20] pub type bitcoin_hashes::hash160::Hash::Engine = bitcoin_hashes::sha256::HashEngine pub type bitcoin_hashes::hash160::Hash::Err = hex_conservative::error::HexToArrayError diff --git a/api/hashes/no-features.txt b/api/hashes/no-features.txt index 41f965a48..b37136ef5 100644 --- a/api/hashes/no-features.txt +++ b/api/hashes/no-features.txt @@ -1,4 +1,13 @@ +#[repr(transparent)] pub struct bitcoin_hashes::Hash160(_) #[repr(transparent)] pub struct bitcoin_hashes::Hmac(_) +#[repr(transparent)] pub struct bitcoin_hashes::Ripemd160(_) +#[repr(transparent)] pub struct bitcoin_hashes::Sha1(_) +#[repr(transparent)] pub struct bitcoin_hashes::Sha256(_) +#[repr(transparent)] pub struct bitcoin_hashes::Sha256d(_) +#[repr(transparent)] pub struct bitcoin_hashes::Sha384(_) +#[repr(transparent)] pub struct bitcoin_hashes::Sha512(_) +#[repr(transparent)] pub struct bitcoin_hashes::Sha512_256(_) +#[repr(transparent)] pub struct bitcoin_hashes::Siphash24(_) #[repr(transparent)] pub struct bitcoin_hashes::hash160::Hash(_) #[repr(transparent)] pub struct bitcoin_hashes::hmac::Hmac(_) #[repr(transparent)] pub struct bitcoin_hashes::ripemd160::Hash(_) @@ -846,6 +855,7 @@ pub mod bitcoin_hashes::sha512 pub mod bitcoin_hashes::sha512_256 pub mod bitcoin_hashes::siphash24 pub struct bitcoin_hashes::FromSliceError +pub struct bitcoin_hashes::Hkdf pub struct bitcoin_hashes::HmacEngine pub struct bitcoin_hashes::hkdf::Hkdf pub struct bitcoin_hashes::hkdf::MaxLengthError @@ -867,6 +877,11 @@ pub trait bitcoin_hashes::sha256t::Tag pub type bitcoin_hashes::GeneralHash::Engine: bitcoin_hashes::HashEngine pub type bitcoin_hashes::Hash::Bytes: hex_conservative::parse::FromHex + core::marker::Copy pub type bitcoin_hashes::HashEngine::MidState +pub type bitcoin_hashes::HkdfSha256 = bitcoin_hashes::hkdf::Hkdf +pub type bitcoin_hashes::HkdfSha512 = bitcoin_hashes::hkdf::Hkdf +pub type bitcoin_hashes::HmacSha256 = bitcoin_hashes::hmac::Hmac +pub type bitcoin_hashes::HmacSha512 = bitcoin_hashes::hmac::Hmac +pub type bitcoin_hashes::Sha256t = bitcoin_hashes::sha256t::Hash pub type bitcoin_hashes::hash160::Hash::Bytes = [u8; 20] pub type bitcoin_hashes::hash160::Hash::Engine = bitcoin_hashes::sha256::HashEngine pub type bitcoin_hashes::hash160::Hash::Err = hex_conservative::error::HexToArrayError