Module cmac 

Available on crate feature crypto only.

CMAC is specified in RFC 4493 and NIST SP 800-38B.

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 CMAC operation allows the per-key precomputation to be done only once, instead of it being done in every CMAC 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::cmac;

let key = cmac::Key::generate(cmac::AES_128)?;

let msg = "hello, world";

let tag = cmac::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.]

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

Using the one-shot API:

use aws_lc_rs::{cmac, 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; 16] = rand::generate(&rng)?.expose();

let s_key = cmac::Key::new(cmac::AES_128, key_value.as_ref())?;
let tag = cmac::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 = cmac::Key::new(cmac::AES_128, key_value.as_ref())?;
cmac::verify(&v_key, msg.as_bytes(), tag.as_ref())?;

Using the multi-part API:

use aws_lc_rs::{cmac, 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 key_value: [u8; 32] = rand::generate(&rng)?.expose();

let s_key = cmac::Key::new(cmac::AES_256, key_value.as_ref())?;
let mut s_ctx = cmac::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 = cmac::Key::new(cmac::AES_256, key_value.as_ref())?;
let mut msg = Vec::<u8>::new();
for part in &parts {
    msg.extend(part.as_bytes());
}
cmac::verify(&v_key, &msg.as_ref(), tag.as_ref())?;

Structs

Algorithm

A CMAC algorithm.

Context

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

Key

A key to use for CMAC signing.

Tag

A CMAC tag.

Constants

AES_128

CMAC using AES-128.

AES_192

CMAC using AES-192.

AES_256

CMAC using AES-256.

TDES_FOR_LEGACY_USE_ONLY

CMAC using 3DES (Triple DES). Obsolete

Functions

sign

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

verify

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