# Module ring::hmac [−] [src]

HMAC is specified in RFC 2104.

After a `SigningKey` or `VerificationKey` 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, `SigningContext` should be used.

# Use Case: Multi-party Communication

Examples: TLS, SSH, and IPSEC record/packet authentication.

The key that is used to sign messages to send to other parties should be a `SigningKey`; `SigningContext` or `sign` should be used for the signing. Each key that is used to authenticate messages received from peers should be a `VerificationKey`; `verify` should be used for the authentication. All of the keys should have distinct, independent, values.

# Use Case: One-party Anti-tampering Protection

Examples: Signed cookies, stateless CSRF protection.

The key that is used to sign the data should be a `SigningKey`; `SigningContext` or `sign` should be used for the signing. Use `verify_with_own_key` to verify the signature using the signing key; this is equivalent to, but more efficient than, constructing a `VerificationKey` with the same value as the signing key and then calling `verify`.

# Use Case: Key Derivation and Password Hashing

Examples: HKDF, PBKDF2, the TLS PRF.

All keys used during the key derivation should be `SigningKey`s; `SigningContext` should usually be used for the HMAC calculations. The code for `ring::pbkdf2` and the code for `ring::hkdf` are good examples of how to use `ring::hmac` efficiently for key derivation.

# Examples:

## Signing a value and verifying it wasn't tampered with

    use ring::{digest, hmac, rand};

    let rng = rand::SystemRandom::new();
    let key = hmac::SigningKey::generate(&digest::SHA256, &rng)?;

    let msg = "hello, world";

    let signature = 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_with_own_key(&key, msg.as_bytes(), signature.as_ref())?;

## Using the one-shot API:

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

    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 mut key_value = [0u8; 32];
    let rng = rand::SystemRandom::new();
    rng.fill(&mut key_value)?;

    let s_key = hmac::SigningKey::new(&digest::SHA256, key_value.as_ref());
    let signature = 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::VerificationKey::new(&digest::SHA256, key_value.as_ref());
    hmac::verify(&v_key, msg.as_bytes(), signature.as_ref())?;

## Using the multi-part API:

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

    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 mut key_value = [0u8; 48];
    let rng = rand::SystemRandom::new();
    rng.fill(&mut key_value)?;

    let s_key = hmac::SigningKey::new(&digest::SHA384, key_value.as_ref());
    let mut s_ctx = hmac::SigningContext::with_key(&s_key);
    for part in &parts {
        s_ctx.update(part.as_bytes());
    }
    let signature = s_ctx.sign();

    // The receiver (somehow!) knows the key value, and uses it to verify the
    // integrity of the message.
    let v_key = hmac::VerificationKey::new(&digest::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(), signature.as_ref())?;

## Structs

Signature | An HMAC signature.
SigningContext | A context for multi-step (Init-Update-Finish) HMAC signing.
SigningKey | A key to use for HMAC signing.
VerificationKey | A key to use for HMAC authentication.

## Functions

recommended_key_len | Returns the recommended key length for HMAC using the given digest algorithm.
sign | Calculates the HMAC of `data` using the key `key` in one step.
verify | Calculates the HMAC of `data` using the key `key`, and verifies whether the resultant value equals `signature`, in one step.
verify_with_own_key | Calculates the HMAC of `data` using the signing key `key`, and verifies whether the resultant value equals `signature`, in one step.

# Help

## Keyboard Shortcuts

?
  Show this help dialog
S
  Focus the search field
⇤
  Move up in search results
⇥
  Move down in search results
⏎
  Go to active search result
+
  Collapse/expand all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)