Struct Hmac

Source

pub struct Hmac<H: Hash> { /* private fields */ }

Expand description

Hashed-Based Message Authentication Codes HMAC.

§Generic `H`

This denotes which hashing function you wish to use under the hood. Options are:

Sha224
Sha256
Sha384
Sha512
Sha3_224
Sha3_256
Sha3_384
Sha3_512

§Non-FIPS / Legacy

Md5
Sha (SHA-1)

§Example

use wolf_crypto::mac::hmac::{Hmac, Sha256};
 
let mut hmac = Hmac::<Sha256>::new([42u8; 32]);
 
hmac.update(b"hello world, ")?;
hmac.update(b"beautiful weather.")?;
 
let parts = hmac.finalize();
 
let mut hmac = Hmac::<Sha256>::new([42u8; 32]);
 
hmac.update(b"hello world, beautiful weather.")?;
 
let all = hmac.finalize();
 
assert_eq!(parts, all);

Implementations§

Source §

impl<H: Hash> Hmac<H>

Source

pub fn new<K>(key: K) -> Self
where K: GenericKey<Size = H::KeyLen>,

Create a new Hmac instance.

§Arguments

key - The key material to initialize the Hmac instance with. This can be the size of the digest or greater (for example, Sha256 means a 256-bit (32 byte) or larger key).

§Example

use wolf_crypto::{mac::hmac::{Hmac, Sha3_512, KeySlice}, MakeOpaque};

// we can provide the exact size of our digest:
let hmac = Hmac::<Sha3_512>::new([42u8; 64]);

// or we can provide a larger key, however this does not
// come with much benefit.
let hmac = KeySlice::new(&[42u8; 128])
    .opaque_map(Hmac::<Sha3_512>::new)
    .unwrap();

Source

pub fn update(&mut self, data: &[u8]) -> Result<&mut Self, Unspecified>

Updates the message to authenticate using HMAC.

§Arguments

data - The buffer containing the message to append.

§Errors

If the length of data is greater than u32::MAX.

§Example

use wolf_crypto::{mac::hmac::{Hmac, Sha3_256}, ct_eq};

let mut hmac = Hmac::<Sha3_256>::new([42; 32]);
hmac.update("hello world".as_bytes())?;

let out = hmac.finalize();

let mut hmac = Hmac::<Sha3_256>::new([42; 32]);
hmac.update("hello world".as_bytes())?;

let other = hmac.finalize();

// Always check in constant-time!! (Digest does this for us)
assert_eq!(out, other);

Source

pub fn update_sized<const C: usize>( &mut self, data: &[u8; C], ) -> Result<&mut Self, Unspecified>

Updates the message to authenticate using HMAC.

The distinction between this and update is that the safety checks are performed over the constant C, thus during compilation time.

§Arguments

data - The fixed-size buffer containing the message to append.

§Errors

If the length of data is greater than u32::MAX.

§Example

use wolf_crypto::mac::hmac::{Hmac, Sha3_256};

let mut hmac = Hmac::<Sha3_256>::new([42; 32]);
hmac.update_sized(b"hello world")?;

// It is generally recommended to use `finalize` instead.
let mut out = [0u8; 32];
hmac.finalize_into(&mut out);

let mut hmac = Hmac::<Sha3_256>::new([42; 32]);
hmac.update_sized(b"hello world")?;

// Always check in constant-time!!
assert!(hmac.compare_digest(&out));

Source

pub fn finalize_into(self, output: &mut H::Digest)

Compute the final hash of the HMAC instance’s message into the output buffer.

§Arguments

output - The buffer to write the digest to.

§Note

It is generally recommended to use finalize in favor of this, as mistakes happen, finalize’s returned Digest type can help prevent these mistakes.

§Example

use wolf_crypto::mac::hmac::{Hmac, Sha3_256};

let mut hmac = Hmac::<Sha3_256>::new([42; 32]);
hmac.update(b"hello world")?;

let mut out = [0u8; 32];
hmac.finalize_into(&mut out);

let mut hmac = Hmac::<Sha3_256>::new([42; 32]);
hmac.update(b"hello world")?;

// Always check in constant-time!!
assert!(hmac.compare_digest(&out));

Source

pub fn finalize_into_slice(self, output: &mut [u8]) -> Result<(), InvalidSize>

Compute the final hash of the HMAC instance’s message into the output buffer.

§Arguments

output - The buffer to write the digest to.

§Errors

If the length of output is less than the result of size (the digest size) for the underlying hashing function.

§Note

It is generally recommended to use finalize in favor of this, as mistakes happen, finalize’s returned Digest type can help prevent these mistakes.

§Example

use wolf_crypto::{mac::hmac::{Hmac, Sha3_256}, ct_eq};

let mut hmac = Hmac::<Sha3_256>::new([42; 32]);
hmac.update(b"hello world")?;

let mut out = [0u8; 32];
hmac.finalize_into_slice(out.as_mut_slice())?;

let mut hmac = Hmac::<Sha3_256>::new([42; 32]);
hmac.update(b"hello world")?;

let mut other = [0u8; 32];
hmac.finalize_into_slice(other.as_mut_slice())?;

// Always check in constant-time!!
// (either using the Digest type or ct_eq directly)
assert!(ct_eq(&out, &other));

Source

pub fn finalize(self) -> Digest<H::Digest>

Compute the final hash of the HMAC instance’s message.

§Returns

The resulting final digest for the underlying hash function. The type returned (Digest) has PartialEq utilities which all are in constant-time.

§Example

use wolf_crypto::{mac::hmac::{Hmac, Sha3_256}, ct_eq};

let mut hmac = Hmac::<Sha3_256>::new([42; 32]);
hmac.update(b"hello world")?;

let out = hmac.finalize();

let mut hmac = Hmac::<Sha3_256>::new([42; 32]);
hmac.update(b"hello world")?;

let other = hmac.finalize();

// Always check in constant-time!! (Digest does this for us)
assert_eq!(out, other);

Source

pub fn compare_digest(self, other: &H::Digest) -> bool

Ensure that other is equivalent to the current message in constant-time.

§Arguments

other - The digest to compare with.

§Returns

true if the digests were equivalent, false otherwise.

§Note

If you do not have a fixed size buffer of the digest size, see compare_digest_slice. Or, you can use the finalize method which returns a type who’s PartialEq implementations are all in constant-time.

Source