hmac

hmac is RustCrypto’s generic implementation of HMAC (Hash-based Message Authentication Code), the algorithm underlying JWT signing, TLS handshakes, and countless API request-signing schemes. Rather than baking in one hash function, it is generic over any hash implementing the digest crate’s EagerHash trait, so the same Hmac<D> type works with SHA-256, SHA-512, SHA-3, or any other RustCrypto digest by swapping a type parameter.

The crate lives in the RustCrypto/MACs monorepo alongside sibling MAC algorithms (CMAC, PMAC, CBC-MAC, Retail MAC, Belt-MAC), all built on the same shared digest/crypto-common trait foundation that underlies the wider RustCrypto ecosystem. It is #![no_std], making it usable in embedded and constrained environments, and is one of the most widely depended-upon crates in the Rust ecosystem for authenticated message integrity.

What You Get

• A Hmac<D> type generic over any hash implementing digest::block_api::EagerHash, so switching hash functions is a type-parameter change
• SimpleHmac and SimpleHmacReset variants for hash functions that don’t implement the EagerHash block-level optimization
• #![no_std] support for embedded and constrained targets with no heap or OS dependency
• An optional zeroize feature to securely wipe key material from memory when a Hmac instance is dropped
• A Reset variant (HmacReset) allowing an HMAC instance to be reused across multiple messages without reallocating state

Common Use Cases

• Signing and verifying JWTs using the HS256/HS384/HS512 algorithm family
• Implementing HMAC-based request signing for API authentication (e.g. AWS SigV4-style signing schemes)
• TLS and other cryptographic protocol implementations that need HMAC as a building block for key derivation (HKDF) or record authentication
• Embedded firmware needing message authentication without a heap allocator, via the crate’s no_std support

Under The Hood

Architecture - The hmac crate lives in the RustCrypto/MACs workspace (hmac/) alongside sibling crates (cmac/, pmac/, cbc-mac/, retail-mac/, belt-mac/) that share the same digest/crypto-common trait foundation used across all of RustCrypto’s hash and cipher crates. Internally, src/lib.rs defines the public Hmac<D>/HmacReset<D> types via the digest::buffer_fixed! macro, which wires up the generic block-buffering logic once and reuses it for both variants; block_api.rs implements the actual inner/outer-pad HMAC construction at the block level for hashes that support eager block processing, while simple.rs/simple_reset.rs provide a fallback implementation for hashes that don’t.

Tech Stack - Pure Rust, #![no_std], with a single runtime dependency on the digest crate (itself part of the RustCrypto trait ecosystem). Rust edition 2024, MSRV 1.85. Dev-dependencies pull in concrete hash implementations (md-5, sha1, sha2, streebog) purely for testing against known test vectors, not as runtime dependencies of the published crate.

Code Quality - The crate has a dedicated tests/ directory for integration-level test-vector verification in addition to a small, focused src/ implementation (548 total lines across lib.rs, block_api.rs, simple.rs, simple_reset.rs, utils.rs), consistent with RustCrypto’s project-wide convention of validating primitives against published standard test vectors (RFC 2104, FIPS 198-1). Licensed under dual MIT/Apache-2.0, the standard RustCrypto licensing convention, with LICENSE-MIT and LICENSE-APACHE both present in the crate directory.

API Design - The API follows the shared digest/crypto-common trait conventions used across all RustCrypto crates: construct via KeyInit::new_from_slice, feed data via the Mac trait’s update, then finalize via finalize/verify_slice. This trait-based consistency means learning hmac’s API transfers directly to every other RustCrypto MAC or hash crate, at the cost of needing some familiarity with the digest crate’s trait hierarchy up front.