HMAC (Hash-based Message Authentication Code)

HMAC is a specific type of Message Authentication Code (MAC) that involves a cryptographic hash function (like SHA-256 or SHA-3) and a secret cryptographic key. Its primary purpose is to simultaneously verify both the data integrity and the authenticity of a message. This means HMAC can ensure that a message has not been altered (integrity) and that it originates from a legitimate sender who possesses the correct secret key (authenticity).

How HMAC Works:

The construction of HMAC is defined in RFC 2104. It works by performing two nested applications of a cryptographic hash function, using two different padded versions of the secret key. This structure provides stronger security properties compared to simply hashing the message with the key concatenated, which can be vulnerable to length extension attacks.

1. Key Preparation:
* If the secret key is longer than the hash function's block size, it is first hashed to produce a shorter key.
* If the key is shorter than the block size, it is padded with zeros up to the block size.
* Two padded keys are derived:
* `key_ipad`: The padded key XORed with `ipad` (inner pad, a repeating byte 0x36).
* `key_opad`: The padded key XORed with `opad` (outer pad, a repeating byte 0x5C).

2. Inner Hash:
* The message is concatenated with `key_ipad`.
* The hash function `H` is applied to this concatenation: `H(key_ipad || message)`. This produces an intermediate hash value.

3. Outer Hash:
* The `key_opad` is concatenated with the result of the inner hash.
* The hash function `H` is applied again: `H(key_opad || H(key_ipad || message))`.
* The final output of this process is the HMAC tag (also known as the HMAC digest).

Key Security Properties and Benefits:

* Integrity: Any unauthorized modification to the message will cause the recomputed HMAC tag to differ from the original tag, indicating tampering.
* Authenticity: Only parties who possess the exact secret key can compute or verify the correct HMAC tag. this prevents attackers from forging messages or their tags.
* Replay Protection (with additional measures): While HMAC itself doesn't inherently prevent replay attacks, it's a foundational component. Coupled with sequence numbers or timestamps, it can help protect against replaying old, valid messages.
* Resilience: HMAC's construction mitigates the risks of length extension attacks that affect plain hash functions, making it a robust choice for message authentication.
* Algorithm Agnostic: HMAC can be used with any cryptographically secure hash function (e.g., MD5, SHA-1, SHA-256, SHA-512, SHA-3). SHA-256 is a common and recommended choice today.

Common Use Cases:

* API Authentication: Many web APIs use HMAC to authenticate requests. A client calculates an HMAC of the request data using a shared secret key and sends it along with the request. The server then recomputes the HMAC and compares it to the received one.
* Data Integrity: Ensuring that data stored in a database or transmitted over a network has not been tampered with.
* Secure Communication Protocols: HMAC is a fundamental component of protocols like TLS/SSL, IPsec, and SSH for message authentication.
* Token-based Authentication: JSON Web Tokens (JWT) often use HMAC (e.g., HS256) for signing to verify their integrity and authenticity.

Difference from Digital Signatures:

While both provide authenticity and integrity, HMAC uses symmetric-key cryptography (same secret key for sender and receiver), whereas digital signatures use asymmetric-key (public/private key pair). Digital signatures offer non-repudiation (proof that a specific sender sent the message), which HMAC does not, as anyone with the secret key can generate a valid tag.

use hmac::{Hmac, Mac, MacAuthenticate};
use sha2::Sha256;
use hex; // For converting the tag bytes to a hexadecimal string for display

fn main() {
    // 1. Define the secret key and message
    // In a real application, the key should be securely generated and stored,
    // and ideally have enough entropy (e.g., 256 bits for SHA256).
    let key = b"a-very-secret-and-strong-key-for-hmac-authentication-1234567890";
    let message = b"This is the message to be authenticated.";

    println!("Original Message: {}", std::str::from_utf8(message).unwrap_or("[Non-UTF8 Message]"));
    println!("Secret Key: {}", std::str::from_utf8(key).unwrap_or("[Non-UTF8 Key]"));

    // 2. Create a new HMAC instance with SHA256 as the underlying hash function.
    //    `Hmac::new_from_slice` returns a Result, so we unwrap it.
    //    The key can be of any length; it will be padded or hashed internally to fit.
    let mut mac = Hmac::<Sha256>::new_from_slice(key)
        .expect("HMAC can be initialized with a key of any length.");

    // 3. Update the HMAC with the message data.
    mac.update(message);

    // 4. Finalize the HMAC to get the authentication tag.
    let result = mac.finalize();
    let tag_bytes = result.into_bytes();

    println!("\nGenerated HMAC Tag (bytes): {:?}", tag_bytes);
    println!("Generated HMAC Tag (hex):   {}", hex::encode(&tag_bytes));

    // --- Verification Process ---
    println!("\n--- Verification ---");

    // Scenario 1: Verify with the original message and key (should succeed)
    println!("\nAttempting to verify with the CORRECT message and key...");
    let mut mac_verifier_correct = Hmac::<Sha256>::new_from_slice(key)
        .expect("HMAC can be initialized with a key of any length.");
    mac_verifier_correct.update(message);
    
    // The `verify_slice` method performs a constant-time comparison to prevent timing attacks.
    match mac_verifier_correct.verify_slice(&tag_bytes) {
        Ok(_) => println!("  Verification SUCCESSFUL! Message is authentic and untampered."),
        Err(_) => println!("  Verification FAILED! (This should not happen for correct input)."),
    }

    // Scenario 2: Verify with an altered message (should fail)
    let altered_message = b"This is the message to be authenticated. (altered)";
    println!("\nAttempting to verify with an ALTERED message: {}", std::str::from_utf8(altered_message).unwrap_or("[Non-UTF8 Message]"));

    let mut mac_verifier_altered = Hmac::<Sha256>::new_from_slice(key)
        .expect("HMAC can be initialized with a key of any length.");
    mac_verifier_altered.update(altered_message);

    match mac_verifier_altered.verify_slice(&tag_bytes) {
        Ok(_) => println!("  Verification SUCCESSFUL! (THIS SHOULD NOT HAPPEN for altered message)."),
        Err(_) => println!("  Verification FAILED for altered message (as expected). Message integrity compromised."),
    }

    // Scenario 3: Verify with an incorrect key (should fail, demonstrating authenticity failure)
    let incorrect_key = b"an-incorrect-and-different-secret-key";
    println!("\nAttempting to verify with an INCORRECT key: {}", std::str::from_utf8(incorrect_key).unwrap_or("[Non-UTF8 Key]"));

    let mut mac_verifier_wrong_key = Hmac::<Sha256>::new_from_slice(incorrect_key)
        .expect("HMAC can be initialized with a key of any length.");
    mac_verifier_wrong_key.update(message);

    match mac_verifier_wrong_key.verify_slice(&tag_bytes) {
        Ok(_) => println!("  Verification SUCCESSFUL! (THIS SHOULD NOT HAPPEN for incorrect key)."),
        Err(_) => println!("  Verification FAILED for incorrect key (as expected). Message authenticity compromised."),
    }
}