From 77c0f52ed9cb74a95e3d43e063f2862efc99ee36 Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Tue, 14 May 2024 14:04:29 +1000 Subject: [PATCH] Rename hmac types The `hmac` types are named differently to the other hash types. At this stage there is not that much difference between them and it is not immediately obvious why they get a different naming scheme. As we do for the other hash types use `Hash` and `HashEngine` with the expectation that user differentiate by using the module path. With this patch applied users use `hmac::Hash` instead of `Hmac`. --- src/hmac.rs | 97 ++++++++++++++++++++++++++-------------------------- src/impls.rs | 20 +++++------ src/lib.rs | 2 -- 3 files changed, 58 insertions(+), 61 deletions(-) diff --git a/src/hmac.rs b/src/hmac.rs index a1da810..f1bb652 100644 --- a/src/hmac.rs +++ b/src/hmac.rs @@ -12,17 +12,17 @@ use core::{fmt, ops, str}; use hex::DisplayHex; -use crate::{FromSliceError, HashEngine}; +use crate::FromSliceError; -/// A hash computed from a RFC 2104 HMAC. Parameterized by the underlying hash function. +/// A hash computed from a RFC 2104 HMAC. Parameterized by the size of the underlying hash function. #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] -pub struct Hmac([u8; N]); +pub struct Hash([u8; N]); -impl Hmac { +impl Hash { /// Returns a hash engine that is ready to be used for the data. pub fn engine() -> E where - E: HashEngine, + E: crate::HashEngine, { E::new() } @@ -32,7 +32,7 @@ impl Hmac { /// This is equivalent to calling `Hash::from_byte_array(engine.finalize())`. pub fn from_engine(engine: E) -> Self where - E: HashEngine, + E: crate::HashEngine, { let digest = engine.finalize(); Self::from_byte_array(digest) @@ -88,8 +88,8 @@ impl Hmac { } #[cfg(feature = "schemars")] -impl schemars::JsonSchema for Hmac { - fn schema_name() -> std::string::String { "Hmac".to_owned() } +impl schemars::JsonSchema for Hash { + fn schema_name() -> std::string::String { "Hash".to_owned() } fn json_schema(gen: &mut schemars::gen::SchemaGenerator) -> schemars::schema::Schema { let mut schema: schemars::schema::SchemaObject = ::json_schema(gen).into(); @@ -102,7 +102,7 @@ impl schemars::JsonSchema for Hmac { } } -impl str::FromStr for Hmac { +impl str::FromStr for Hash { type Err = hex::HexToArrayError; fn from_str(s: &str) -> Result { use hex::FromHex; @@ -112,78 +112,78 @@ impl str::FromStr for Hmac { } } -impl fmt::Display for Hmac { +impl fmt::Display for Hash { fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { fmt::LowerHex::fmt(self, f) } } -impl fmt::Debug for Hmac { +impl fmt::Debug for Hash { fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { write!(f, "{:#}", self) } } -impl fmt::LowerHex for Hmac { +impl fmt::LowerHex for Hash { fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { // FIXME: Can't use hex_fmt_exact because of N. fmt::LowerHex::fmt(&self.0.as_hex(), f) } } -impl fmt::UpperHex for Hmac { +impl fmt::UpperHex for Hash { fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { // FIXME: Can't use hex_fmt_exact because of N. fmt::UpperHex::fmt(&self.0.as_hex(), f) } } -impl ops::Index for Hmac { +impl ops::Index for Hash { type Output = u8; fn index(&self, index: usize) -> &u8 { &self.0[index] } } -impl ops::Index> for Hmac { +impl ops::Index> for Hash { type Output = [u8]; fn index(&self, index: ops::Range) -> &[u8] { &self.0[index] } } -impl ops::Index> for Hmac { +impl ops::Index> for Hash { type Output = [u8]; fn index(&self, index: ops::RangeFrom) -> &[u8] { &self.0[index] } } -impl ops::Index> for Hmac { +impl ops::Index> for Hash { type Output = [u8]; fn index(&self, index: ops::RangeTo) -> &[u8] { &self.0[index] } } -impl ops::Index for Hmac { +impl ops::Index for Hash { type Output = [u8]; fn index(&self, index: ops::RangeFull) -> &[u8] { &self.0[index] } } -impl AsRef<[u8]> for Hmac { +impl AsRef<[u8]> for Hash { fn as_ref(&self) -> &[u8] { &self.0 } } #[cfg(feature = "serde")] -impl crate::serde_macros::serde_details::SerdeHash for Hmac { +impl crate::serde_macros::serde_details::SerdeHash for Hash { const N: usize = N; - fn from_slice_delegated(sl: &[u8]) -> Result { Hmac::from_slice(sl) } + fn from_slice_delegated(sl: &[u8]) -> Result { Hash::from_slice(sl) } } #[cfg(feature = "serde")] -impl serde::Serialize for Hmac { +impl serde::Serialize for Hash { fn serialize(&self, s: S) -> Result { crate::serde_macros::serde_details::SerdeHash::serialize(self, s) } } #[cfg(feature = "serde")] -impl<'de, const N: usize> crate::serde::Deserialize<'de> for Hmac { +impl<'de, const N: usize> crate::serde::Deserialize<'de> for Hash { fn deserialize>(d: D) -> Result { crate::serde_macros::serde_details::SerdeHash::deserialize(d) } } -/// Pair of underlying hash midstates which represent the current state of an `HmacEngine`. -pub struct HmacMidState { +/// Pair of underlying hash midstates which represent the current state of an `HashEngine`. +pub struct MidState { /// Midstate of the inner hash engine pub inner: E::Midstate, /// Midstate of the outer hash engine @@ -192,16 +192,16 @@ pub struct HmacMidState { /// Pair of underlying hash engines, used for the inner and outer hash of HMAC. #[derive(Clone)] -pub struct HmacEngine { +pub struct HashEngine { iengine: E, oengine: E, } -impl Default for HmacEngine { - fn default() -> Self { HmacEngine::new(&[]) } +impl Default for HashEngine { + fn default() -> Self { HashEngine::new(&[]) } } -impl HmacEngine { +impl HashEngine { /// Constructs a new keyed HMAC from `key`. /// /// We only support hash engines whose internal block sizes are ≤ 128 bytes. @@ -209,15 +209,15 @@ impl HmacEngine { /// # Panics /// /// Larger block sizes will result in a panic. - pub fn new(key: &[u8]) -> HmacEngine { + pub fn new(key: &[u8]) -> HashEngine { debug_assert!(E::BLOCK_SIZE <= 128); let mut ipad = [0x36u8; 128]; let mut opad = [0x5cu8; 128]; - let mut ret = HmacEngine { iengine: E::default(), oengine: E::default() }; + let mut ret = HashEngine { iengine: E::default(), oengine: E::default() }; if key.len() > E::BLOCK_SIZE { - let hash = ::hash(key); + let hash = ::hash(key); for (b_i, b_h) in ipad.iter_mut().zip(hash.as_ref()) { *b_i ^= *b_h; } @@ -239,9 +239,9 @@ impl HmacEngine { } } -impl HashEngine for HmacEngine { +impl crate::HashEngine for HashEngine { type Digest = E::Digest; - type Midstate = HmacMidstate; + type Midstate = Midstate; const BLOCK_SIZE: usize = E::BLOCK_SIZE; #[inline] @@ -259,22 +259,22 @@ impl HashEngine for HmacEngine { #[inline] fn midstate(&self) -> Self::Midstate { - HmacMidstate { inner: self.iengine.midstate(), outer: self.oengine.midstate() } + Midstate { inner: self.iengine.midstate(), outer: self.oengine.midstate() } } #[inline] - fn from_midstate(midstate: HmacMidstate, length: usize) -> Self { - HmacEngine { + fn from_midstate(midstate: Midstate, length: usize) -> Self { + HashEngine { iengine: E::from_midstate(midstate.inner, length), oengine: E::from_midstate(midstate.outer, length), } } } -/// Pair of underlying hash engine midstates which represent the current state of an `HmacEngine`. +/// Pair of underlying hash engine midstates which represent the current state of an `HashEngine`. // TODO: Use derives? //#[derive(Copy, Clone, PartialEq, Eq, Default, PartialOrd, Ord, Hash)] -pub struct HmacMidstate { +pub struct Midstate { /// Midstate of the inner hash engine. pub inner: E::Midstate, /// Midstate of the outer hash engine. @@ -402,7 +402,7 @@ mod tests { ]; for test in tests { - let mut engine = HmacEngine::::new(&test.key); + let mut engine = HashEngine::::new(&test.key); engine.input(&test.input); let hash = engine.finalize(); assert_eq!(&hash[..], &test.output[..]); @@ -413,10 +413,9 @@ mod tests { #[cfg(feature = "serde")] #[test] fn hmac_sha512_serde() { + use crate::hmac; use serde_test::{assert_tokens, Configure, Token}; - use crate::Hmac; - #[rustfmt::skip] static HASH_BYTES: [u8; 64] = [ 0x8b, 0x41, 0xe1, 0xb7, 0x8a, 0xd1, 0x15, 0x21, @@ -429,7 +428,7 @@ mod tests { 0x0b, 0x2d, 0x8a, 0x60, 0x0b, 0xdf, 0x4c, 0x0c, ]; - let hash = Hmac::<64>::from_slice(&HASH_BYTES).expect("right number of bytes"); + let hash = hmac::Hash::<64>::from_slice(&HASH_BYTES).expect("right number of bytes"); assert_tokens(&hash.compact(), &[Token::BorrowedBytes(&HASH_BYTES[..])]); assert_tokens( @@ -446,8 +445,8 @@ mod tests { use super::*; use crate::sha256; - let engine: HmacEngine = Default::default(); - let hmac = Hmac::from_engine(engine); + let engine: HashEngine = Default::default(); + let hmac = Hash::from_engine(engine); let hint = hmac.0.iter().size_hint().1; println!("hint: {:?}", hint); @@ -458,11 +457,11 @@ mod tests { mod benches { use test::Bencher; - use crate::{sha256, HashEngine, HmacEngine}; + use crate::{sha256, HashEngine, HashEngine}; #[bench] pub fn hmac_sha256_10(bh: &mut Bencher) { - let mut engine: HmacEngine = Default::default(); + let mut engine: HashEngine = Default::default(); let bytes = [1u8; 10]; bh.iter(|| { engine.input(&bytes); @@ -472,7 +471,7 @@ mod benches { #[bench] pub fn hmac_sha256_1k(bh: &mut Bencher) { - let mut engine: HmacEngine = Default::default(); + let mut engine: HashEngine = Default::default(); let bytes = [1u8; 1024]; bh.iter(|| { engine.input(&bytes); @@ -482,7 +481,7 @@ mod benches { #[bench] pub fn hmac_sha256_64k(bh: &mut Bencher) { - let mut engine: HmacEngine = Default::default(); + let mut engine: HashEngine = Default::default(); let bytes = [1u8; 65536]; bh.iter(|| { engine.input(&bytes); diff --git a/src/impls.rs b/src/impls.rs index 4b1ea0c..a9ebd9e 100644 --- a/src/impls.rs +++ b/src/impls.rs @@ -7,7 +7,7 @@ use bitcoin_io::impl_write; -use crate::{ripemd160, sha1, sha256, sha256t, sha512, siphash24, HashEngine, HmacEngine}; +use crate::{hmac, ripemd160, sha1, sha256, sha256t, sha512, siphash24, HashEngine as _}; impl_write!( sha1::HashEngine, @@ -54,7 +54,7 @@ impl_write!( |_us| { Ok(()) } ); -impl bitcoin_io::Write for HmacEngine { +impl bitcoin_io::Write for hmac::HashEngine { #[inline] fn write(&mut self, buf: &[u8]) -> Result { use crate::HashEngine as _; @@ -67,7 +67,7 @@ impl bitcoin_io::Write for HmacEngine { } #[cfg(feature = "std")] -impl std::io::Write for HmacEngine { +impl std::io::Write for hmac::HashEngine { #[inline] fn write(&mut self, buf: &[u8]) -> std::io::Result { self.input(buf); @@ -92,7 +92,7 @@ impl_write!( mod tests { use bitcoin_io::Write; - use crate::{ripemd160, sha1, sha256, sha512, siphash24, HashEngine as _, Hmac, HmacEngine}; + use crate::{hmac, ripemd160, sha1, sha256, sha512, siphash24, HashEngine as _}; macro_rules! write_test { ($mod:ident, $exp_empty:expr, $exp_256:expr, $exp_64k:expr,) => { @@ -151,24 +151,24 @@ mod tests { #[test] fn hmac() { - let mut engine = HmacEngine::::new(&[0xde, 0xad, 0xbe, 0xef]); + let mut engine = hmac::HashEngine::::new(&[0xde, 0xad, 0xbe, 0xef]); engine.write_all(&[]).unwrap(); assert_eq!( - format!("{}", Hmac::from_engine(engine)), + format!("{}", hmac::Hash::from_engine(engine)), "bf5515149cf797955c4d3194cca42472883281951697c8375d9d9b107f384225" ); - let mut engine = HmacEngine::::new(&[0xde, 0xad, 0xbe, 0xef]); + let mut engine = hmac::HashEngine::::new(&[0xde, 0xad, 0xbe, 0xef]); engine.write_all(&[1; 256]).unwrap(); assert_eq!( - format!("{}", Hmac::from_engine(engine)), + format!("{}", hmac::Hash::from_engine(engine)), "59c9aca10c81c73cb4c196d94db741b6bf2050e0153d5a45f2526bff34675ac5" ); - let mut engine = HmacEngine::::new(&[0xde, 0xad, 0xbe, 0xef]); + let mut engine = hmac::HashEngine::::new(&[0xde, 0xad, 0xbe, 0xef]); engine.write_all(&[99; 64000]).unwrap(); assert_eq!( - format!("{}", Hmac::from_engine(engine)), + format!("{}", hmac::Hash::from_engine(engine)), "30df499717415a395379a1eaabe50038036e4abb5afc94aa55c952f4aa57be08" ); } diff --git a/src/lib.rs b/src/lib.rs index dfbb959..668a5b6 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -129,8 +129,6 @@ pub mod siphash24; use core::{convert, fmt, hash}; -pub use hmac::{Hmac, HmacEngine}; - /// A hashing engine which bytes can be serialized into. pub trait HashEngine: Clone + Default { /// The digest returned by this hash engine.