rust/bssl-crypto/src/hmac.rs - boringssl - Git at Google

 // Copyright 2023 The BoringSSL Authors
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
 // You may obtain a copy of the License at
 //
 //     https://www.apache.org/licenses/LICENSE-2.0
 //
 // Unless required by applicable law or agreed to in writing, software
 // distributed under the License is distributed on an "AS IS" BASIS,
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.

 //! Hash-based message authentication from <https://datatracker.ietf.org/doc/html/rfc2104>.
 //!
 //! HMAC-SHA256, HMAC-SHA384 and HMAC-SHA512 are supported.
 //!
 //! MACs can be computed in a single shot:
 //!
 //! ```
 //! use bssl_crypto::hmac::HmacSha256;
 //!
 //! let mac: [u8; 32] = HmacSha256::mac(b"key", b"hello");
 //! ```
 //!
 //! Or they can be computed incrementally:
 //!
 //! ```
 //! use bssl_crypto::hmac::HmacSha256;
 //!
 //! let key = bssl_crypto::rand_array();
 //! let mut ctx = HmacSha256::new(&key);
 //! ctx.update(b"hel");
 //! ctx.update(b"lo");
 //! let mac: [u8; 32] = ctx.digest();
 //! ```
 //!
 //! **WARNING** comparing MACs using typical methods will often leak information
 //! about the size of the matching prefix. Use the `verify` method instead.
 //!
 //! If you need to compute many MACs with the same key, contexts can be
 //! cloned:
 //!
 //! ```
 //! use bssl_crypto::hmac::HmacSha256;
 //!
 //! let key = bssl_crypto::rand_array();
 //! let mut keyed_ctx = HmacSha256::new(&key);
 //! let mut ctx1 = keyed_ctx.clone();
 //! ctx1.update(b"foo");
 //! let mut ctx2 = keyed_ctx.clone();
 //! ctx2.update(b"foo");
 //!
 //! assert_eq!(ctx1.digest(), ctx2.digest());
 //! ```

 use crate::{
     digest,
     digest::{Sha256, Sha384, Sha512},
     initialized_struct, sealed, FfiMutSlice, FfiSlice, ForeignTypeRef as _, InvalidSignatureError,
 };
 use core::{ffi::c_uint, marker::PhantomData, ptr};

 /// HMAC-SHA256.
 pub struct HmacSha256(Hmac<32, Sha256>);

 impl HmacSha256 {
     /// Computes the HMAC-SHA256 of `data` as a one-shot operation.
     pub fn mac(key: &[u8], data: &[u8]) -> [u8; 32] {
         hmac::<32, Sha256>(key, data)
     }

     /// Creates a new HMAC-SHA256 operation from a fixed-length key.
     pub fn new(key: &[u8; 32]) -> Self {
         Self(Hmac::new(key))
     }

     /// Creates a new HMAC-SHA256 operation from a variable-length key.
     pub fn new_from_slice(key: &[u8]) -> Self {
         Self(Hmac::new_from_slice(key))
     }

     /// Hashes the provided input into the HMAC operation.
     pub fn update(&mut self, data: &[u8]) {
         self.0.update(data)
     }

     /// Computes the final HMAC value, consuming the object.
     pub fn digest(self) -> [u8; 32] {
         self.0.digest()
     }

     /// Checks that the provided tag value matches the computed HMAC value.
     pub fn verify_slice(self, tag: &[u8]) -> Result<(), InvalidSignatureError> {
         self.0.verify_slice(tag)
     }

     /// Checks that the provided tag value matches the computed HMAC value.
     pub fn verify(self, tag: &[u8; 32]) -> Result<(), InvalidSignatureError> {
         self.0.verify(tag)
     }

     /// Checks that the provided tag value matches the computed HMAC, truncated to the input tag's
     /// length.
     ///
     /// Truncating an HMAC reduces the security of the construction. Callers must ensure `tag`'s
     /// length matches the desired HMAC length and security level.
     pub fn verify_truncated_left(self, tag: &[u8]) -> Result<(), InvalidSignatureError> {
         self.0.verify_truncated_left(tag)
     }
 }

 #[cfg(feature = "std")]
 impl std::io::Write for HmacSha256 {
     fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
         self.update(buf);
         Ok(buf.len())
     }

     fn flush(&mut self) -> std::io::Result<()> {
         Ok(())
     }
 }

 impl Clone for HmacSha256 {
     fn clone(&self) -> Self {
         HmacSha256(self.0.clone())
     }
 }

 /// HMAC-SHA384.
 pub struct HmacSha384(Hmac<48, Sha384>);

 impl HmacSha384 {
     /// Computes the HMAC-SHA384 of `data` as a one-shot operation.
     pub fn mac(key: &[u8], data: &[u8]) -> [u8; 48] {
         hmac::<48, Sha384>(key, data)
     }

     /// Creates a new HMAC-SHA384 operation from a fixed-size key.
     pub fn new(key: &[u8; 48]) -> Self {
         Self(Hmac::new(key))
     }

     /// Creates a new HMAC-SHA384 operation from a variable-length key.
     pub fn new_from_slice(key: &[u8]) -> Self {
         Self(Hmac::new_from_slice(key))
     }

     /// Hashes the provided input into the HMAC operation.
     pub fn update(&mut self, data: &[u8]) {
         self.0.update(data)
     }

     /// Computes the final HMAC value, consuming the object.
     pub fn digest(self) -> [u8; 48] {
         self.0.digest()
     }

     /// Checks that the provided tag value matches the computed HMAC value.
     pub fn verify_slice(self, tag: &[u8]) -> Result<(), InvalidSignatureError> {
         self.0.verify_slice(tag)
     }

     /// Checks that the provided tag value matches the computed HMAC value.
     pub fn verify(self, tag: &[u8; 48]) -> Result<(), InvalidSignatureError> {
         self.0.verify(tag)
     }

     /// Checks that the provided tag value matches the computed HMAC, truncated to the input tag's
     /// length.
     ///
     /// Truncating an HMAC reduces the security of the construction. Callers must ensure `tag`'s
     /// length matches the desired HMAC length and security level.
     pub fn verify_truncated_left(self, tag: &[u8]) -> Result<(), InvalidSignatureError> {
         self.0.verify_truncated_left(tag)
     }
 }

 #[cfg(feature = "std")]
 impl std::io::Write for HmacSha384 {
     fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
         self.update(buf);
         Ok(buf.len())
     }

     fn flush(&mut self) -> std::io::Result<()> {
         Ok(())
     }
 }

 impl Clone for HmacSha384 {
     fn clone(&self) -> Self {
         HmacSha384(self.0.clone())
     }
 }

 /// HMAC-SHA512.
 pub struct HmacSha512(Hmac<64, Sha512>);

 impl HmacSha512 {
     /// Computes the HMAC-SHA512 of `data` as a one-shot operation.
     pub fn mac(key: &[u8], data: &[u8]) -> [u8; 64] {
         hmac::<64, Sha512>(key, data)
     }

     /// Creates a new HMAC-SHA512 operation from a fixed-size key.
     pub fn new(key: &[u8; 64]) -> Self {
         Self(Hmac::new(key))
     }

     /// Creates a new HMAC-SHA512 operation from a variable-length key.
     pub fn new_from_slice(key: &[u8]) -> Self {
         Self(Hmac::new_from_slice(key))
     }

     /// Hashes the provided input into the HMAC operation.
     pub fn update(&mut self, data: &[u8]) {
         self.0.update(data)
     }

     /// Computes the final HMAC value, consuming the object.
     pub fn digest(self) -> [u8; 64] {
         self.0.digest()
     }

     /// Checks that the provided tag value matches the computed HMAC value.
     pub fn verify_slice(self, tag: &[u8]) -> Result<(), InvalidSignatureError> {
         self.0.verify_slice(tag)
     }

     /// Checks that the provided tag value matches the computed HMAC value.
     pub fn verify(self, tag: &[u8; 64]) -> Result<(), InvalidSignatureError> {
         self.0.verify(tag)
     }

     /// Checks that the provided tag value matches the computed HMAC, truncated to the input tag's
     /// length.
     ///
     /// Truncating an HMAC reduces the security of the construction. Callers must ensure `tag`'s
     /// length matches the desired HMAC length and security level.
     pub fn verify_truncated_left(self, tag: &[u8]) -> Result<(), InvalidSignatureError> {
         self.0.verify_truncated_left(tag)
     }
 }

 #[cfg(feature = "std")]
 impl std::io::Write for HmacSha512 {
     fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
         self.update(buf);
         Ok(buf.len())
     }

     fn flush(&mut self) -> std::io::Result<()> {
         Ok(())
     }
 }

 impl Clone for HmacSha512 {
     fn clone(&self) -> Self {
         HmacSha512(self.0.clone())
     }
 }

 /// Private generically implemented function for computing HMAC as a oneshot operation.
 /// This should only be exposed publicly by types with the correct output size `N` which corresponds
 /// to the output size of the provided generic hash function. Ideally `N` would just come from `MD`,
 /// but this is not possible until the Rust language can support the `min_const_generics` feature.
 /// Until then we will have to pass both separately: https://github.com/rust-lang/rust/issues/60551
 #[inline]
 fn hmac<const N: usize, MD: digest::Algorithm>(key: &[u8], data: &[u8]) -> [u8; N] {
     let mut out = [0_u8; N];
     let mut size: c_uint = 0;

     // Safety:
     // - buf always contains N bytes of space
     // - If NULL is returned on error we panic immediately
     let result = unsafe {
         bssl_sys::HMAC(
             MD::get_md(sealed::SealedType).as_ptr(),
             key.as_ffi_void_ptr(),
             key.len(),
             data.as_ffi_ptr(),
             data.len(),
             out.as_mut_ffi_ptr(),
             &mut size as *mut c_uint,
         )
     };
     assert_eq!(size as usize, N);
     assert!(!result.is_null(), "Result of bssl_sys::HMAC was null");

     out
 }

 /// Private generically implemented HMAC instance given a generic hash function and a length `N`,
 /// where `N` is the output size of the hash function. This should only be exposed publicly by
 /// wrapper types with the correct output size `N` which corresponds to the output size of the
 /// provided generic hash function. Ideally `N` would just come from `MD`, but this is not possible
 /// until the Rust language can support the `min_const_generics` feature. Until then we will have to
 /// pass both separately: https://github.com/rust-lang/rust/issues/60551
 struct Hmac<const N: usize, MD: digest::Algorithm> {
     // Safety: this relies on HMAC_CTX being relocatable via `memcpy`, which is
     // not generally true of BoringSSL types. This is fine to rely on only
     // because we do not allow any version skew between bssl-crypto and
     // BoringSSL. It is *not* safe to copy this code in any other project.
     ctx: bssl_sys::HMAC_CTX,
     _marker: PhantomData<MD>,
 }

 impl<const N: usize, MD: digest::Algorithm> Hmac<N, MD> {
     /// Creates a new HMAC operation from a fixed-length key.
     fn new(key: &[u8; N]) -> Self {
         Self::new_from_slice(key)
     }

     /// Creates a new HMAC operation from a variable-length key.
     fn new_from_slice(key: &[u8]) -> Self {
         let mut ret = Self {
             // Safety: type checking will ensure that |ctx| is the correct size
             // for `HMAC_CTX_init`.
             ctx: unsafe { initialized_struct(|ctx| bssl_sys::HMAC_CTX_init(ctx)) },
             _marker: Default::default(),
         };

         // Safety:
         // - HMAC_Init_ex must be called with an initialized context, which
         //   `HMAC_CTX_init` provides.
         // - HMAC_Init_ex may return an error if key is null but the md is different from
         //   before. This is avoided here since key is guaranteed to be non-null.
         // - HMAC_Init_ex returns 0 on allocation failure in which case we panic
         let result = unsafe {
             bssl_sys::HMAC_Init_ex(
                 &mut ret.ctx,
                 key.as_ffi_void_ptr(),
                 key.len(),
                 MD::get_md(sealed::SealedType).as_ptr(),
                 ptr::null_mut(),
             )
         };
         assert!(result > 0, "Allocation failure in bssl_sys::HMAC_Init_ex");
         ret
     }

     /// Hashes the provided input into the HMAC operation.
     fn update(&mut self, data: &[u8]) {
         // Safety: `HMAC_Update` needs an initialized context, but the only way
         // to create this object is via `new_from_slice`, which ensures that.
         let result = unsafe { bssl_sys::HMAC_Update(&mut self.ctx, data.as_ffi_ptr(), data.len()) };
         // HMAC_Update always returns 1.
         assert_eq!(result, 1, "failure in bssl_sys::HMAC_Update");
     }

     /// Computes the final HMAC value, consuming the object.
     fn digest(mut self) -> [u8; N] {
         let mut buf = [0_u8; N];
         let mut size: c_uint = 0;
         // Safety:
         // - HMAC has a fixed size output of N which will never exceed the length of an N
         // length array
         // - `HMAC_Final` needs an initialized context, but the only way
         //  to create this object is via `new_from_slice`, which ensures that.
         // - on allocation failure we panic
         let result =
             unsafe { bssl_sys::HMAC_Final(&mut self.ctx, buf.as_mut_ffi_ptr(), &mut size) };
         assert!(result > 0, "Allocation failure in bssl_sys::HMAC_Final");
         assert_eq!(size as usize, N);
         buf
     }

     /// Checks that the provided tag value matches the computed HMAC value.
     fn verify(self, tag: &[u8; N]) -> Result<(), InvalidSignatureError> {
         self.verify_slice(tag)
     }

     /// Checks that the provided tag value matches the computed HMAC value.
     ///
     /// Returns `Error` if `tag` is not valid or not equal in length
     /// to MAC's output.
     fn verify_slice(self, tag: &[u8]) -> Result<(), InvalidSignatureError> {
         if tag.len() == N {
             self.verify_truncated_left(tag)
         } else {
             Err(InvalidSignatureError)
         }
     }

     /// Checks that the provided tag value matches the computed HMAC, truncated to the input tag's
     /// length.
     ///
     /// Returns `Error` if `tag` is not valid or empty.
     ///
     /// Truncating an HMAC reduces the security of the construction. Callers must ensure `tag`'s
     /// length matches the desired HMAC length and security level.
     fn verify_truncated_left(self, tag: &[u8]) -> Result<(), InvalidSignatureError> {
         let len = tag.len();
         if len == 0 || len > N {
             return Err(InvalidSignatureError);
         }
         let calculated = self.digest();

         // Safety: both `calculated` and `tag` must be at least `len` bytes available.
         // This is true because `len` is the length of `tag` and `len` is <= N,
         // the length of `calculated`, which is checked above.
         let result = unsafe {
             bssl_sys::CRYPTO_memcmp(calculated.as_ffi_void_ptr(), tag.as_ffi_void_ptr(), len)
         };
         if result == 0 {
             Ok(())
         } else {
             Err(InvalidSignatureError)
         }
     }

     fn clone(&self) -> Self {
         let mut ret = Self {
             // Safety: type checking will ensure that |ctx| is the correct size
             // for `HMAC_CTX_init`.
             ctx: unsafe { initialized_struct(|ctx| bssl_sys::HMAC_CTX_init(ctx)) },
             _marker: Default::default(),
         };
         // Safety: `ret.ctx` is initialized and `self.ctx` is valid by
         // construction.
         let result = unsafe { bssl_sys::HMAC_CTX_copy(&mut ret.ctx, &self.ctx) };
         assert_eq!(result, 1);
         ret
     }
 }

 impl<const N: usize, MD: digest::Algorithm> Drop for Hmac<N, MD> {
     fn drop(&mut self) {
         unsafe { bssl_sys::HMAC_CTX_cleanup(&mut self.ctx) }
     }
 }

 #[cfg(test)]
 mod tests {
     use super::*;
     use alloc::boxed::Box;

     #[test]
     fn hmac_sha256() {
         let expected: [u8; 32] = [
             0xb0, 0x34, 0x4c, 0x61, 0xd8, 0xdb, 0x38, 0x53, 0x5c, 0xa8, 0xaf, 0xce, 0xaf, 0xb,
             0xf1, 0x2b, 0x88, 0x1d, 0xc2, 0x0, 0xc9, 0x83, 0x3d, 0xa7, 0x26, 0xe9, 0x37, 0x6c,
             0x2e, 0x32, 0xcf, 0xf7,
         ];
         let key: [u8; 20] = [0x0b; 20];
         let data = b"Hi There";

         let mut hmac = HmacSha256::new_from_slice(&key);
         hmac.update(data);
         assert_eq!(hmac.digest(), expected);

         let mut hmac = HmacSha256::new_from_slice(&key);
         hmac.update(&data[..1]);
         hmac.update(&data[1..]);
         assert_eq!(hmac.digest(), expected);

         let mut hmac = HmacSha256::new_from_slice(&key);
         hmac.update(data);
         assert!(hmac.verify(&expected).is_ok());

         let mut hmac = HmacSha256::new_from_slice(&key);
         hmac.update(data);
         assert!(hmac.verify_truncated_left(&expected[..4]).is_ok());

         let mut hmac = HmacSha256::new_from_slice(&key);
         hmac.update(data);
         assert!(hmac.verify_truncated_left(&expected[4..8]).is_err());

         let mut hmac = HmacSha256::new_from_slice(&key);
         hmac.update(&data[..1]);
         let mut hmac2 = hmac.clone();
         let mut hmac3 = Box::new(hmac2.clone());
         hmac.update(&data[1..]);
         hmac2.update(&data[1..]);
         hmac3.update(&data[1..]);
         assert_eq!(hmac.digest(), expected);
         assert_eq!(hmac2.digest(), expected);
         assert_eq!(hmac3.digest(), expected);
     }

     #[test]
     fn hmac_sha256_fixed_size_key() {
         let expected_hmac = [
             0x19, 0x8a, 0x60, 0x7e, 0xb4, 0x4b, 0xfb, 0xc6, 0x99, 0x3, 0xa0, 0xf1, 0xcf, 0x2b,
             0xbd, 0xc5, 0xba, 0xa, 0xa3, 0xf3, 0xd9, 0xae, 0x3c, 0x1c, 0x7a, 0x3b, 0x16, 0x96,
             0xa0, 0xb6, 0x8c, 0xf7,
         ];
         let key: [u8; 32] = [0x0b; 32];
         let data = b"Hi There";

         let mut hmac = HmacSha256::new(&key);
         hmac.update(data);
         let hmac_result: [u8; 32] = hmac.digest();
         assert_eq!(&hmac_result, &expected_hmac);
     }

     #[test]
     fn hmac_sha384() {
         // We test against some Wycheproof test vectors `hmac_sha384_test.json`.
         let key = &[
             238, 141, 240, 103, 133, 125, 242, 48, 15, 167, 26, 16, 195, 9, 151, 23, 139, 179, 121,
             97, 39, 181, 236, 229, 242, 204, 193, 112, 147, 43, 224, 231, 142, 169, 176, 165, 147,
             108, 9, 21, 126, 103, 28, 231, 236, 159, 197, 16,
         ];
         let mut hmac = HmacSha384::new_from_slice(key);
         hmac.update(b"");
         let hmac_result: [u8; 48] = hmac.digest();
         assert_eq!(
             hmac_result,
             [
                 166, 85, 24, 77, 175, 51, 70, 255, 198, 98, 157, 73, 60, 132, 66, 100, 78, 73, 150,
                 162, 121, 158, 66, 227, 48, 111, 166, 245, 176, 150, 123, 108, 243, 166, 248, 25,
                 186, 184, 155, 206, 41, 125, 29, 26, 89, 7, 178, 208
             ]
         );

         let key = &[
             151, 102, 150, 192, 220, 151, 24, 44, 167, 113, 151, 92, 57, 40, 255, 145, 104, 239,
             137, 205, 116, 12, 210, 41, 40, 88, 253, 145, 96, 104, 167, 2, 188, 29, 247, 198, 205,
             142, 225, 240, 210, 94, 97, 212, 197, 20, 204, 93,
         ];
         hmac = HmacSha384::new_from_slice(key);
         hmac.update(&[43]);
         let hmac_result: [u8; 48] = hmac.digest();
         assert_eq!(
             hmac_result,
             [
                 54, 62, 137, 115, 254, 220, 247, 137, 32, 19, 223, 174, 11, 112, 101, 214, 29, 128,
                 185, 140, 99, 91, 192, 158, 216, 96, 160, 20, 115, 185, 188, 208, 220, 85, 13, 191,
                 102, 207, 13, 96, 31, 233, 203, 243, 174, 89, 98, 13
             ]
         );

         let key = &[
             188, 49, 11, 195, 145, 61, 159, 229, 158, 32, 18, 160, 88, 201, 225, 80, 83, 77, 37,
             97, 30, 54, 32, 108, 240, 124, 202, 239, 225, 83, 243, 142, 176, 234, 173, 153, 65,
             182, 136, 61, 251, 206, 1, 188, 181, 25, 96, 65,
         ];
         hmac = HmacSha384::new_from_slice(key);
         let msg = &[
             159, 7, 71, 215, 57, 107, 251, 224, 28, 243, 232, 83, 97, 229, 0, 133, 224, 169, 26,
             116, 144, 185, 148, 3, 29, 129, 133, 27, 114, 80, 101, 153, 63, 69, 218, 208, 214, 13,
             121, 74, 237, 236, 123, 165, 217, 214, 219, 190, 228,
         ];
         hmac.update(&msg[..20]);
         hmac.update(&msg[20..]);
         let hmac_result: [u8; 48] = hmac.digest();
         assert_eq!(
             hmac_result,
             [
                 58, 134, 73, 143, 120, 195, 251, 126, 179, 183, 179, 216, 47, 103, 125, 45, 254, 1,
                 22, 111, 231, 110, 35, 32, 131, 51, 77, 116, 241, 21, 136, 253, 8, 150, 55, 201,
                 71, 97, 233, 207, 232, 54, 67, 96, 5, 222, 174, 247
             ]
         );
     }

     #[test]
     fn hmac_sha512() {
         let expected: [u8; 64] = [
             135, 170, 124, 222, 165, 239, 97, 157, 79, 240, 180, 36, 26, 29, 108, 176, 35, 121,
             244, 226, 206, 78, 194, 120, 122, 208, 179, 5, 69, 225, 124, 222, 218, 168, 51, 183,
             214, 184, 167, 2, 3, 139, 39, 78, 174, 163, 244, 228, 190, 157, 145, 78, 235, 97, 241,
             112, 46, 105, 108, 32, 58, 18, 104, 84,
         ];
         let key: [u8; 20] = [0x0b; 20];
         let data = b"Hi There";

         let mut hmac = HmacSha512::new_from_slice(&key);
         hmac.update(data);
         assert_eq!(hmac.digest(), expected);

         let mut hmac = HmacSha512::new_from_slice(&key);
         hmac.update(&data[..1]);
         hmac.update(&data[1..]);
         assert_eq!(hmac.digest(), expected);

         let mut hmac = HmacSha512::new_from_slice(&key);
         hmac.update(data);
         assert!(hmac.verify(&expected).is_ok());

         let mut hmac = HmacSha512::new_from_slice(&key);
         hmac.update(data);
         assert!(hmac.verify_truncated_left(&expected[..4]).is_ok());

         let mut hmac = HmacSha512::new_from_slice(&key);
         hmac.update(data);
         assert!(hmac.verify_truncated_left(&expected[4..8]).is_err());

         let mut hmac = HmacSha512::new_from_slice(&key);
         hmac.update(&data[..1]);
         let mut hmac2 = hmac.clone();
         let mut hmac3 = Box::new(hmac.clone());
         hmac.update(&data[1..]);
         hmac2.update(&data[1..]);
         hmac3.update(&data[1..]);
         assert_eq!(hmac.digest(), expected);
         assert_eq!(hmac2.digest(), expected);
         assert_eq!(hmac3.digest(), expected);
     }
 }
	// Copyright 2023 The BoringSSL Authors
	//
	// Licensed under the Apache License, Version 2.0 (the "License");
	// you may not use this file except in compliance with the License.
	// You may obtain a copy of the License at
	//
	// https://www.apache.org/licenses/LICENSE-2.0
	//
	// Unless required by applicable law or agreed to in writing, software
	// distributed under the License is distributed on an "AS IS" BASIS,
	// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	// See the License for the specific language governing permissions and
	// limitations under the License.

	//! Hash-based message authentication from <https://datatracker.ietf.org/doc/html/rfc2104>.
	//!
	//! HMAC-SHA256, HMAC-SHA384 and HMAC-SHA512 are supported.
	//!
	//! MACs can be computed in a single shot:
	//!
	//! ```
	//! use bssl_crypto::hmac::HmacSha256;
	//!
	//! let mac: [u8; 32] = HmacSha256::mac(b"key", b"hello");
	//! ```
	//!
	//! Or they can be computed incrementally:
	//!
	//! ```
	//! use bssl_crypto::hmac::HmacSha256;
	//!
	//! let key = bssl_crypto::rand_array();
	//! let mut ctx = HmacSha256::new(&key);
	//! ctx.update(b"hel");
	//! ctx.update(b"lo");
	//! let mac: [u8; 32] = ctx.digest();
	//! ```
	//!
	//! WARNING comparing MACs using typical methods will often leak information
	//! about the size of the matching prefix. Use the `verify` method instead.
	//!
	//! If you need to compute many MACs with the same key, contexts can be
	//! cloned:
	//!
	//! ```
	//! use bssl_crypto::hmac::HmacSha256;
	//!
	//! let key = bssl_crypto::rand_array();
	//! let mut keyed_ctx = HmacSha256::new(&key);
	//! let mut ctx1 = keyed_ctx.clone();
	//! ctx1.update(b"foo");
	//! let mut ctx2 = keyed_ctx.clone();
	//! ctx2.update(b"foo");
	//!
	//! assert_eq!(ctx1.digest(), ctx2.digest());
	//! ```

	use crate::{
	digest,
	digest::{Sha256, Sha384, Sha512},
	initialized_struct, sealed, FfiMutSlice, FfiSlice, ForeignTypeRef as _, InvalidSignatureError,
	};
	use core::{ffi::c_uint, marker::PhantomData, ptr};

	/// HMAC-SHA256.
	pub struct HmacSha256(Hmac<32, Sha256>);

	impl HmacSha256 {
	/// Computes the HMAC-SHA256 of `data` as a one-shot operation.
	pub fn mac(key: &[u8], data: &[u8]) -> [u8; 32] {
	hmac::<32, Sha256>(key, data)
	}

	/// Creates a new HMAC-SHA256 operation from a fixed-length key.
	pub fn new(key: &[u8; 32]) -> Self {
	Self(Hmac::new(key))
	}

	/// Creates a new HMAC-SHA256 operation from a variable-length key.
	pub fn new_from_slice(key: &[u8]) -> Self {
	Self(Hmac::new_from_slice(key))
	}

	/// Hashes the provided input into the HMAC operation.
	pub fn update(&mut self, data: &[u8]) {
	self.0.update(data)
	}

	/// Computes the final HMAC value, consuming the object.
	pub fn digest(self) -> [u8; 32] {
	self.0.digest()
	}

	/// Checks that the provided tag value matches the computed HMAC value.
	pub fn verify_slice(self, tag: &[u8]) -> Result<(), InvalidSignatureError> {
	self.0.verify_slice(tag)
	}

	/// Checks that the provided tag value matches the computed HMAC value.
	pub fn verify(self, tag: &[u8; 32]) -> Result<(), InvalidSignatureError> {
	self.0.verify(tag)
	}

	/// Checks that the provided tag value matches the computed HMAC, truncated to the input tag's
	/// length.
	///
	/// Truncating an HMAC reduces the security of the construction. Callers must ensure `tag`'s
	/// length matches the desired HMAC length and security level.
	pub fn verify_truncated_left(self, tag: &[u8]) -> Result<(), InvalidSignatureError> {
	self.0.verify_truncated_left(tag)
	}
	}

	#[cfg(feature = "std")]
	impl std::io::Write for HmacSha256 {
	fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
	self.update(buf);
	Ok(buf.len())
	}

	fn flush(&mut self) -> std::io::Result<()> {
	Ok(())
	}
	}

	impl Clone for HmacSha256 {
	fn clone(&self) -> Self {
	HmacSha256(self.0.clone())
	}
	}

	/// HMAC-SHA384.
	pub struct HmacSha384(Hmac<48, Sha384>);

	impl HmacSha384 {
	/// Computes the HMAC-SHA384 of `data` as a one-shot operation.
	pub fn mac(key: &[u8], data: &[u8]) -> [u8; 48] {
	hmac::<48, Sha384>(key, data)
	}

	/// Creates a new HMAC-SHA384 operation from a fixed-size key.
	pub fn new(key: &[u8; 48]) -> Self {
	Self(Hmac::new(key))
	}

	/// Creates a new HMAC-SHA384 operation from a variable-length key.
	pub fn new_from_slice(key: &[u8]) -> Self {
	Self(Hmac::new_from_slice(key))
	}

	/// Hashes the provided input into the HMAC operation.
	pub fn update(&mut self, data: &[u8]) {
	self.0.update(data)
	}

	/// Computes the final HMAC value, consuming the object.
	pub fn digest(self) -> [u8; 48] {
	self.0.digest()
	}

	/// Checks that the provided tag value matches the computed HMAC value.
	pub fn verify_slice(self, tag: &[u8]) -> Result<(), InvalidSignatureError> {
	self.0.verify_slice(tag)
	}

	/// Checks that the provided tag value matches the computed HMAC value.
	pub fn verify(self, tag: &[u8; 48]) -> Result<(), InvalidSignatureError> {
	self.0.verify(tag)
	}

	/// Checks that the provided tag value matches the computed HMAC, truncated to the input tag's
	/// length.
	///
	/// Truncating an HMAC reduces the security of the construction. Callers must ensure `tag`'s
	/// length matches the desired HMAC length and security level.
	pub fn verify_truncated_left(self, tag: &[u8]) -> Result<(), InvalidSignatureError> {
	self.0.verify_truncated_left(tag)
	}
	}

	#[cfg(feature = "std")]
	impl std::io::Write for HmacSha384 {
	fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
	self.update(buf);
	Ok(buf.len())
	}

	fn flush(&mut self) -> std::io::Result<()> {
	Ok(())
	}
	}

	impl Clone for HmacSha384 {
	fn clone(&self) -> Self {
	HmacSha384(self.0.clone())
	}
	}

	/// HMAC-SHA512.
	pub struct HmacSha512(Hmac<64, Sha512>);

	impl HmacSha512 {
	/// Computes the HMAC-SHA512 of `data` as a one-shot operation.
	pub fn mac(key: &[u8], data: &[u8]) -> [u8; 64] {
	hmac::<64, Sha512>(key, data)
	}

	/// Creates a new HMAC-SHA512 operation from a fixed-size key.
	pub fn new(key: &[u8; 64]) -> Self {
	Self(Hmac::new(key))
	}

	/// Creates a new HMAC-SHA512 operation from a variable-length key.
	pub fn new_from_slice(key: &[u8]) -> Self {
	Self(Hmac::new_from_slice(key))
	}

	/// Hashes the provided input into the HMAC operation.
	pub fn update(&mut self, data: &[u8]) {
	self.0.update(data)
	}

	/// Computes the final HMAC value, consuming the object.
	pub fn digest(self) -> [u8; 64] {
	self.0.digest()
	}

	/// Checks that the provided tag value matches the computed HMAC value.
	pub fn verify_slice(self, tag: &[u8]) -> Result<(), InvalidSignatureError> {
	self.0.verify_slice(tag)
	}

	/// Checks that the provided tag value matches the computed HMAC value.
	pub fn verify(self, tag: &[u8; 64]) -> Result<(), InvalidSignatureError> {
	self.0.verify(tag)
	}

	/// Checks that the provided tag value matches the computed HMAC, truncated to the input tag's
	/// length.
	///
	/// Truncating an HMAC reduces the security of the construction. Callers must ensure `tag`'s
	/// length matches the desired HMAC length and security level.
	pub fn verify_truncated_left(self, tag: &[u8]) -> Result<(), InvalidSignatureError> {
	self.0.verify_truncated_left(tag)
	}
	}

	#[cfg(feature = "std")]
	impl std::io::Write for HmacSha512 {
	fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
	self.update(buf);
	Ok(buf.len())
	}

	fn flush(&mut self) -> std::io::Result<()> {
	Ok(())
	}
	}

	impl Clone for HmacSha512 {
	fn clone(&self) -> Self {
	HmacSha512(self.0.clone())
	}
	}

	/// Private generically implemented function for computing HMAC as a oneshot operation.
	/// This should only be exposed publicly by types with the correct output size `N` which corresponds
	/// to the output size of the provided generic hash function. Ideally `N` would just come from `MD`,
	/// but this is not possible until the Rust language can support the `min_const_generics` feature.
	/// Until then we will have to pass both separately: https://github.com/rust-lang/rust/issues/60551
	#[inline]
	fn hmac<const N: usize, MD: digest::Algorithm>(key: &[u8], data: &[u8]) -> [u8; N] {
	let mut out = [0_u8; N];
	let mut size: c_uint = 0;

	// Safety:
	// - buf always contains N bytes of space
	// - If NULL is returned on error we panic immediately
	let result = unsafe {
	bssl_sys::HMAC(
	MD::get_md(sealed::SealedType).as_ptr(),
	key.as_ffi_void_ptr(),
	key.len(),
	data.as_ffi_ptr(),
	data.len(),
	out.as_mut_ffi_ptr(),
	&mut size as *mut c_uint,
	)
	};
	assert_eq!(size as usize, N);
	assert!(!result.is_null(), "Result of bssl_sys::HMAC was null");

	out
	}

	/// Private generically implemented HMAC instance given a generic hash function and a length `N`,
	/// where `N` is the output size of the hash function. This should only be exposed publicly by
	/// wrapper types with the correct output size `N` which corresponds to the output size of the
	/// provided generic hash function. Ideally `N` would just come from `MD`, but this is not possible
	/// until the Rust language can support the `min_const_generics` feature. Until then we will have to
	/// pass both separately: https://github.com/rust-lang/rust/issues/60551
	struct Hmac<const N: usize, MD: digest::Algorithm> {
	// Safety: this relies on HMAC_CTX being relocatable via `memcpy`, which is
	// not generally true of BoringSSL types. This is fine to rely on only
	// because we do not allow any version skew between bssl-crypto and
	// BoringSSL. It is not safe to copy this code in any other project.
	ctx: bssl_sys::HMAC_CTX,
	_marker: PhantomData<MD>,
	}

	impl<const N: usize, MD: digest::Algorithm> Hmac<N, MD> {
	/// Creates a new HMAC operation from a fixed-length key.
	fn new(key: &[u8; N]) -> Self {
	Self::new_from_slice(key)
	}

	/// Creates a new HMAC operation from a variable-length key.
	fn new_from_slice(key: &[u8]) -> Self {
	let mut ret = Self {
	// Safety: type checking will ensure that \|ctx\| is the correct size
	// for `HMAC_CTX_init`.
	ctx: unsafe { initialized_struct(\|ctx\| bssl_sys::HMAC_CTX_init(ctx)) },
	_marker: Default::default(),
	};

	// Safety:
	// - HMAC_Init_ex must be called with an initialized context, which
	// `HMAC_CTX_init` provides.
	// - HMAC_Init_ex may return an error if key is null but the md is different from
	// before. This is avoided here since key is guaranteed to be non-null.
	// - HMAC_Init_ex returns 0 on allocation failure in which case we panic
	let result = unsafe {
	bssl_sys::HMAC_Init_ex(
	&mut ret.ctx,
	key.as_ffi_void_ptr(),
	key.len(),
	MD::get_md(sealed::SealedType).as_ptr(),
	ptr::null_mut(),
	)
	};
	assert!(result > 0, "Allocation failure in bssl_sys::HMAC_Init_ex");
	ret
	}

	/// Hashes the provided input into the HMAC operation.
	fn update(&mut self, data: &[u8]) {
	// Safety: `HMAC_Update` needs an initialized context, but the only way
	// to create this object is via `new_from_slice`, which ensures that.
	let result = unsafe { bssl_sys::HMAC_Update(&mut self.ctx, data.as_ffi_ptr(), data.len()) };
	// HMAC_Update always returns 1.
	assert_eq!(result, 1, "failure in bssl_sys::HMAC_Update");
	}

	/// Computes the final HMAC value, consuming the object.
	fn digest(mut self) -> [u8; N] {
	let mut buf = [0_u8; N];
	let mut size: c_uint = 0;
	// Safety:
	// - HMAC has a fixed size output of N which will never exceed the length of an N
	// length array
	// - `HMAC_Final` needs an initialized context, but the only way
	// to create this object is via `new_from_slice`, which ensures that.
	// - on allocation failure we panic
	let result =
	unsafe { bssl_sys::HMAC_Final(&mut self.ctx, buf.as_mut_ffi_ptr(), &mut size) };
	assert!(result > 0, "Allocation failure in bssl_sys::HMAC_Final");
	assert_eq!(size as usize, N);
	buf
	}

	/// Checks that the provided tag value matches the computed HMAC value.
	fn verify(self, tag: &[u8; N]) -> Result<(), InvalidSignatureError> {
	self.verify_slice(tag)
	}

	/// Checks that the provided tag value matches the computed HMAC value.
	///
	/// Returns `Error` if `tag` is not valid or not equal in length
	/// to MAC's output.
	fn verify_slice(self, tag: &[u8]) -> Result<(), InvalidSignatureError> {
	if tag.len() == N {
	self.verify_truncated_left(tag)
	} else {
	Err(InvalidSignatureError)
	}
	}

	/// Checks that the provided tag value matches the computed HMAC, truncated to the input tag's
	/// length.
	///
	/// Returns `Error` if `tag` is not valid or empty.
	///
	/// Truncating an HMAC reduces the security of the construction. Callers must ensure `tag`'s
	/// length matches the desired HMAC length and security level.
	fn verify_truncated_left(self, tag: &[u8]) -> Result<(), InvalidSignatureError> {
	let len = tag.len();
	if len == 0 \|\| len > N {
	return Err(InvalidSignatureError);
	}
	let calculated = self.digest();

	// Safety: both `calculated` and `tag` must be at least `len` bytes available.
	// This is true because `len` is the length of `tag` and `len` is <= N,
	// the length of `calculated`, which is checked above.
	let result = unsafe {
	bssl_sys::CRYPTO_memcmp(calculated.as_ffi_void_ptr(), tag.as_ffi_void_ptr(), len)
	};
	if result == 0 {
	Ok(())
	} else {
	Err(InvalidSignatureError)
	}
	}

	fn clone(&self) -> Self {
	let mut ret = Self {
	// Safety: type checking will ensure that \|ctx\| is the correct size
	// for `HMAC_CTX_init`.
	ctx: unsafe { initialized_struct(\|ctx\| bssl_sys::HMAC_CTX_init(ctx)) },
	_marker: Default::default(),
	};
	// Safety: `ret.ctx` is initialized and `self.ctx` is valid by
	// construction.
	let result = unsafe { bssl_sys::HMAC_CTX_copy(&mut ret.ctx, &self.ctx) };
	assert_eq!(result, 1);
	ret
	}
	}

	impl<const N: usize, MD: digest::Algorithm> Drop for Hmac<N, MD> {
	fn drop(&mut self) {
	unsafe { bssl_sys::HMAC_CTX_cleanup(&mut self.ctx) }
	}
	}

	#[cfg(test)]
	mod tests {
	use super::*;
	use alloc::boxed::Box;

	#[test]
	fn hmac_sha256() {
	let expected: [u8; 32] = [
	0xb0, 0x34, 0x4c, 0x61, 0xd8, 0xdb, 0x38, 0x53, 0x5c, 0xa8, 0xaf, 0xce, 0xaf, 0xb,
	0xf1, 0x2b, 0x88, 0x1d, 0xc2, 0x0, 0xc9, 0x83, 0x3d, 0xa7, 0x26, 0xe9, 0x37, 0x6c,
	0x2e, 0x32, 0xcf, 0xf7,
	];
	let key: [u8; 20] = [0x0b; 20];
	let data = b"Hi There";

	let mut hmac = HmacSha256::new_from_slice(&key);
	hmac.update(data);
	assert_eq!(hmac.digest(), expected);

	let mut hmac = HmacSha256::new_from_slice(&key);
	hmac.update(&data[..1]);
	hmac.update(&data[1..]);
	assert_eq!(hmac.digest(), expected);

	let mut hmac = HmacSha256::new_from_slice(&key);
	hmac.update(data);
	assert!(hmac.verify(&expected).is_ok());

	let mut hmac = HmacSha256::new_from_slice(&key);
	hmac.update(data);
	assert!(hmac.verify_truncated_left(&expected[..4]).is_ok());

	let mut hmac = HmacSha256::new_from_slice(&key);
	hmac.update(data);
	assert!(hmac.verify_truncated_left(&expected[4..8]).is_err());

	let mut hmac = HmacSha256::new_from_slice(&key);
	hmac.update(&data[..1]);
	let mut hmac2 = hmac.clone();
	let mut hmac3 = Box::new(hmac2.clone());
	hmac.update(&data[1..]);
	hmac2.update(&data[1..]);
	hmac3.update(&data[1..]);
	assert_eq!(hmac.digest(), expected);
	assert_eq!(hmac2.digest(), expected);
	assert_eq!(hmac3.digest(), expected);
	}

	#[test]
	fn hmac_sha256_fixed_size_key() {
	let expected_hmac = [
	0x19, 0x8a, 0x60, 0x7e, 0xb4, 0x4b, 0xfb, 0xc6, 0x99, 0x3, 0xa0, 0xf1, 0xcf, 0x2b,
	0xbd, 0xc5, 0xba, 0xa, 0xa3, 0xf3, 0xd9, 0xae, 0x3c, 0x1c, 0x7a, 0x3b, 0x16, 0x96,
	0xa0, 0xb6, 0x8c, 0xf7,
	];
	let key: [u8; 32] = [0x0b; 32];
	let data = b"Hi There";

	let mut hmac = HmacSha256::new(&key);
	hmac.update(data);
	let hmac_result: [u8; 32] = hmac.digest();
	assert_eq!(&hmac_result, &expected_hmac);
	}

	#[test]
	fn hmac_sha384() {
	// We test against some Wycheproof test vectors `hmac_sha384_test.json`.
	let key = &[
	238, 141, 240, 103, 133, 125, 242, 48, 15, 167, 26, 16, 195, 9, 151, 23, 139, 179, 121,
	97, 39, 181, 236, 229, 242, 204, 193, 112, 147, 43, 224, 231, 142, 169, 176, 165, 147,
	108, 9, 21, 126, 103, 28, 231, 236, 159, 197, 16,
	];
	let mut hmac = HmacSha384::new_from_slice(key);
	hmac.update(b"");
	let hmac_result: [u8; 48] = hmac.digest();
	assert_eq!(
	hmac_result,
	[
	166, 85, 24, 77, 175, 51, 70, 255, 198, 98, 157, 73, 60, 132, 66, 100, 78, 73, 150,
	162, 121, 158, 66, 227, 48, 111, 166, 245, 176, 150, 123, 108, 243, 166, 248, 25,
	186, 184, 155, 206, 41, 125, 29, 26, 89, 7, 178, 208
	]
	);

	let key = &[
	151, 102, 150, 192, 220, 151, 24, 44, 167, 113, 151, 92, 57, 40, 255, 145, 104, 239,
	137, 205, 116, 12, 210, 41, 40, 88, 253, 145, 96, 104, 167, 2, 188, 29, 247, 198, 205,
	142, 225, 240, 210, 94, 97, 212, 197, 20, 204, 93,
	];
	hmac = HmacSha384::new_from_slice(key);
	hmac.update(&[43]);
	let hmac_result: [u8; 48] = hmac.digest();
	assert_eq!(
	hmac_result,
	[
	54, 62, 137, 115, 254, 220, 247, 137, 32, 19, 223, 174, 11, 112, 101, 214, 29, 128,
	185, 140, 99, 91, 192, 158, 216, 96, 160, 20, 115, 185, 188, 208, 220, 85, 13, 191,
	102, 207, 13, 96, 31, 233, 203, 243, 174, 89, 98, 13
	]
	);

	let key = &[
	188, 49, 11, 195, 145, 61, 159, 229, 158, 32, 18, 160, 88, 201, 225, 80, 83, 77, 37,
	97, 30, 54, 32, 108, 240, 124, 202, 239, 225, 83, 243, 142, 176, 234, 173, 153, 65,
	182, 136, 61, 251, 206, 1, 188, 181, 25, 96, 65,
	];
	hmac = HmacSha384::new_from_slice(key);
	let msg = &[
	159, 7, 71, 215, 57, 107, 251, 224, 28, 243, 232, 83, 97, 229, 0, 133, 224, 169, 26,
	116, 144, 185, 148, 3, 29, 129, 133, 27, 114, 80, 101, 153, 63, 69, 218, 208, 214, 13,
	121, 74, 237, 236, 123, 165, 217, 214, 219, 190, 228,
	];
	hmac.update(&msg[..20]);
	hmac.update(&msg[20..]);
	let hmac_result: [u8; 48] = hmac.digest();
	assert_eq!(
	hmac_result,
	[
	58, 134, 73, 143, 120, 195, 251, 126, 179, 183, 179, 216, 47, 103, 125, 45, 254, 1,
	22, 111, 231, 110, 35, 32, 131, 51, 77, 116, 241, 21, 136, 253, 8, 150, 55, 201,
	71, 97, 233, 207, 232, 54, 67, 96, 5, 222, 174, 247
	]
	);
	}

	#[test]
	fn hmac_sha512() {
	let expected: [u8; 64] = [
	135, 170, 124, 222, 165, 239, 97, 157, 79, 240, 180, 36, 26, 29, 108, 176, 35, 121,
	244, 226, 206, 78, 194, 120, 122, 208, 179, 5, 69, 225, 124, 222, 218, 168, 51, 183,
	214, 184, 167, 2, 3, 139, 39, 78, 174, 163, 244, 228, 190, 157, 145, 78, 235, 97, 241,
	112, 46, 105, 108, 32, 58, 18, 104, 84,
	];
	let key: [u8; 20] = [0x0b; 20];
	let data = b"Hi There";

	let mut hmac = HmacSha512::new_from_slice(&key);
	hmac.update(data);
	assert_eq!(hmac.digest(), expected);

	let mut hmac = HmacSha512::new_from_slice(&key);
	hmac.update(&data[..1]);
	hmac.update(&data[1..]);
	assert_eq!(hmac.digest(), expected);

	let mut hmac = HmacSha512::new_from_slice(&key);
	hmac.update(data);
	assert!(hmac.verify(&expected).is_ok());

	let mut hmac = HmacSha512::new_from_slice(&key);
	hmac.update(data);
	assert!(hmac.verify_truncated_left(&expected[..4]).is_ok());

	let mut hmac = HmacSha512::new_from_slice(&key);
	hmac.update(data);
	assert!(hmac.verify_truncated_left(&expected[4..8]).is_err());

	let mut hmac = HmacSha512::new_from_slice(&key);
	hmac.update(&data[..1]);
	let mut hmac2 = hmac.clone();
	let mut hmac3 = Box::new(hmac.clone());
	hmac.update(&data[1..]);
	hmac2.update(&data[1..]);
	hmac3.update(&data[1..]);
	assert_eq!(hmac.digest(), expected);
	assert_eq!(hmac2.digest(), expected);
	assert_eq!(hmac3.digest(), expected);
	}
	}