Crate oxicrypto_mac

Expand description

Pure Rust MAC implementations for the OxiCrypto stack.

Provides Mac and StreamingMac trait wrappers for:

HMAC-SHA-256 / SHA-384 / SHA-512 (one-shot + streaming + truncated)
HMAC-SHA3-256 / SHA3-512
Poly1305 (one-time MAC)
CMAC-AES-128 / CMAC-AES-256
KMAC128 / KMAC256 (SP 800-185, via tiny-keccak)

All MAC verifications use constant-time comparison via the subtle crate.

§Hash-agnostic HMAC

hmac_streaming_hash::StreamingHashHmac provides a generic HMAC adapter that accepts any oxicrypto_core::StreamingHash implementation.

§Architecture: Internal Consistency with oxicrypto-kdf and oxicrypto-hash

§HKDF / PBKDF2 internal consistency

oxicrypto-kdf (HKDF and PBKDF2) and oxicrypto-mac (HMAC) currently use separate call paths to the same underlying hmac workspace crate. This is an intentional architecture decision:

Both oxicrypto-kdf and oxicrypto-mac ultimately delegate to the same hmac = "0.13" crate — Cargo deduplicates the single copy at build time. Behavior is therefore byte-for-byte identical; there is no actual inconsistency in outputs.
Refactoring oxicrypto-kdf to route HKDF/PBKDF2 calls through oxicrypto-mac’s public HmacSha256/HmacSha512 types would add a crate dependency edge (oxicrypto-kdf → oxicrypto-mac) and require plumbing the KDF trait bounds through the Mac trait boundary — a non-trivial refactor with no output correctness benefit (the outputs are already identical).
This is deferred as a post-1.0 ergonomic cleanup. Until then, callers that need HKDF-then-HMAC in the same context can use oxicrypto-kdf for key derivation and oxicrypto-mac for MAC computation independently, relying on the fact that both use the same underlying hmac implementation.

oxicrypto-mac KMAC128/KMAC256 use tiny-keccak 2.0.2 (with the kmac feature), while oxicrypto-hash SHA3 uses the sha3 0.12 crate. Both implement the same Keccak-f[1600] permutation internally, so there is no cryptographic inconsistency — the sponge state is not logically shared.

Sharing the sponge context between crates would require either:

Moving KMAC into oxicrypto-hash and re-exporting it from oxicrypto-mac, or
Exposing sha3 internal sponge state, which that crate deliberately does not.

tiny-keccak is kept as the KMAC backend because it provides the correct KMAC domain separation (pad byte 0x04 vs Keccak 0x01) and the SP 800-185-compliant encode_string / bytepad encoding. This is a correct, tested, and auditable choice. The minor code-size duplication of having two Keccak implementations is accepted as a pragmatic trade-off until a unified SP 800-185 implementation is available in the sha3 workspace dep.

Re-exports§

pub use hmac_streaming_hash::hmac_with_streaming_hash;
pub use hmac_streaming_hash::StreamingHashHmac;
pub use hmac_streaming_hash::StreamingHashHmacSession;
pub use tls::mac_name_for_suite;
pub use tls::negotiate_mac;
pub use tls::TlsCipherSuite;

Modules§

hmac_streaming_hash: Generic HMAC adapter that accepts any StreamingHash implementation.
tls: TLS cipher suite → MAC negotiation.

Structs§

CmacAes128: CMAC-AES-128 message authentication code (16-byte tag).
CmacAes256: CMAC-AES-256 message authentication code (16-byte tag).
HmacSha3_256: HMAC-SHA3-256 message authentication code (32-byte tag).
HmacSha3_512: HMAC-SHA3-512 message authentication code (64-byte tag).
HmacSha256: HMAC-SHA-256 message authentication code (32-byte tag).
HmacSha384: HMAC-SHA-384 message authentication code (48-byte tag).
HmacSha512: HMAC-SHA-512 message authentication code (64-byte tag).
HmacSha256Keyed: Pre-keyed HMAC-SHA-256 instance; implements StreamingMac.
HmacSha384Keyed: Pre-keyed HMAC-SHA-384 instance; implements StreamingMac.
HmacSha512Keyed: Pre-keyed HMAC-SHA-512 instance; implements StreamingMac.
HmacStreamingAdapter: Generic streaming MAC adapter wrapping hmac::Hmac<D>.
Kmac128: KMAC128 message authentication code (SP 800-185).
Kmac256: KMAC256 message authentication code (SP 800-185).
Poly1305Mac: Poly1305 one-time message authentication code (16-byte tag).

Functions§

blake3_keyed_mac: BLAKE3 keyed-hash MAC (BLAKE3 spec §2.7).
blake3_keyed_mac_verify: Verify a BLAKE3 keyed-hash MAC in constant time.
hmac_sha256_to_vec: Compute an HMAC-SHA-256 tag and return it as a 32-byte Vec<u8>.
hmac_sha256_verify_truncated: Verify the first truncated_tag.len() bytes of an HMAC-SHA-256 MAC.
hmac_sha384_to_vec: Compute an HMAC-SHA-384 tag and return it as a 48-byte Vec<u8>.
hmac_sha512_to_vec: Compute an HMAC-SHA-512 tag and return it as a 64-byte Vec<u8>.
kmac128_xof: KMAC128 with variable-length output (XOF mode, SP 800-185 §4.3.1).
kmac256_xof: KMAC256 with variable-length output (XOF mode, SP 800-185 §4.3.1).

Type Aliases§

HmacSha256Streaming: Streaming HMAC-SHA-256 adapter.
HmacSha384Streaming: Streaming HMAC-SHA-384 adapter.
HmacSha512Streaming: Streaming HMAC-SHA-512 adapter.