Module hmac

HMAC is specified in RFC 2104.

After a Key is constructed, it can be used for multiple signing or verification operations. Separating the construction of the key from the rest of the HMAC operation allows the per-key precomputation to be done only once, instead of it being done in every HMAC operation.

Frequently all the data to be signed in a message is available in a single contiguous piece. In that case, the module-level sign function can be used. Otherwise, if the input is in multiple parts, Context should be used.

Examples:

Signing a value and verifying it wasn’t tampered with

use aws_lc_rs::{hmac, rand};

let rng = rand::SystemRandom::new();
let key = hmac::Key::generate(hmac::HMAC_SHA256, &rng)?;

let msg = "hello, world";

let tag = hmac::sign(&key, msg.as_bytes());

// [We give access to the message to an untrusted party, and they give it
// back to us. We need to verify they didn't tamper with it.]

hmac::verify(&key, msg.as_bytes(), tag.as_ref())?;

Using the one-shot API:

use aws_lc_rs::rand::SecureRandom;
use aws_lc_rs::{digest, hmac, rand};

let msg = "hello, world";

// The sender generates a secure key value and signs the message with it.
// Note that in a real protocol, a key agreement protocol would be used to
// derive `key_value`.
let rng = rand::SystemRandom::new();
let key_value: [u8; digest::SHA256_OUTPUT_LEN] = rand::generate(&rng)?.expose();

let s_key = hmac::Key::new(hmac::HMAC_SHA256, key_value.as_ref());
let tag = hmac::sign(&s_key, msg.as_bytes());

// The receiver (somehow!) knows the key value, and uses it to verify the
// integrity of the message.
let v_key = hmac::Key::new(hmac::HMAC_SHA256, key_value.as_ref());
hmac::verify(&v_key, msg.as_bytes(), tag.as_ref())?;

Using the multi-part API:

use aws_lc_rs::rand::SecureRandom;
use aws_lc_rs::{digest, hmac, rand};

let parts = ["hello", ", ", "world"];

// The sender generates a secure key value and signs the message with it.
// Note that in a real protocol, a key agreement protocol would be used to
// derive `key_value`.
let rng = rand::SystemRandom::new();
let mut key_value: [u8; digest::SHA384_OUTPUT_LEN] = rand::generate(&rng)?.expose();

let s_key = hmac::Key::new(hmac::HMAC_SHA384, key_value.as_ref());
let mut s_ctx = hmac::Context::with_key(&s_key);
for part in &parts {
    s_ctx.update(part.as_bytes());
}
let tag = s_ctx.sign();

// The receiver (somehow!) knows the key value, and uses it to verify the
// integrity of the message.
let v_key = hmac::Key::new(hmac::HMAC_SHA384, key_value.as_ref());
let mut msg = Vec::<u8>::new();
for part in &parts {
    msg.extend(part.as_bytes());
}
hmac::verify(&v_key, &msg.as_ref(), tag.as_ref())?;

Structs

Algorithm

An HMAC algorithm.

Context

A context for multi-step (Init-Update-Finish) HMAC signing.

Key

A key to use for HMAC signing.

Tag

An HMAC tag.

Statics

HMAC_SHA1_FOR_LEGACY_USE_ONLY

HMAC using SHA-1. Obsolete.

HMAC_SHA224

HMAC using SHA-224.

HMAC_SHA256

HMAC using SHA-256.

HMAC_SHA384

HMAC using SHA-384.

HMAC_SHA512

HMAC using SHA-512.

Functions

sign

Calculates the HMAC of data using the key key in one step.

verify

Calculates the HMAC of data using the signing key key, and verifies whether the resultant value equals tag, in one step.

Type Aliases

SignatureDeprecated

A deprecated alias for Tag.

SigningContextDeprecated

Renamed to Context.

SigningKeyDeprecated

Renamed to Key.

VerificationKeyDeprecated

Merged into Key.