Expand description
Stateful streaming MAC context (init / update / sign / verify).
Uniform init / update / sign | verify API across HMAC, CMAC,
KMAC and GMAC. Designed in the same spirit as
crate::cipher::ctx::Cipher: caller-provided output buffers,
reusable across many messages by re-calling Mac::init,
constant-time tag comparison on verify, and Poly1305 left out
on purpose because it is a one-time MAC and would be unsafe to
expose behind a “init then reuse” object.
§Cycle of life
new(algo)
│
▼
init(key) (HMAC, CMAC, KMAC default)
init_kmac(key, custom) (KMAC with customization string)
init_with_nonce(key, n) (GMAC)
│
▼
update(data) ──┐
│ (0..N times)
▼
sign(out) or verify(expected_tag)§Example: HMAC-SHA-256
use arcana::mac::ctx::{Mac, Algorithm};
let mut m = Mac::new(Algorithm::HmacSha256);
m.init(b"secret-key").unwrap();
m.update(b"hello, ").unwrap();
m.update(b"world!").unwrap();
let mut tag = [0u8; 32];
let n = m.sign(&mut tag).unwrap();
assert_eq!(n, 32);§Side-channel posture
Per arcana/doc/sca/countermeasures/hmac.rst:
| Family | Threat | Status | Roadmap item |
|---|---|---|---|
| All families | Timing on tag verify | implemented | silentops::ct_eq — constant-time tag compare |
| HMAC-SHA-2 | Carry-based DPA (Belenky TCHES 2023/3) | vulnerable | T2-D — first-order Boolean masking of SHA-2 |
| HMAC-SHA-3 | DPA on Keccak (no addition → no CDPA) | low risk | none scheduled (Keccak has no carry chain) |
| CMAC | Inherits AES leak (cf. crate::cipher::aes) | vulnerable | T1-A (AES) → T2-G (masked AES); CMAC inherits |
| KMAC | DPA on Keccak | low risk | none scheduled |
| GMAC | DPA on GF(2^128) GHASH multiplier | vulnerable | T2-H — CT carry-less multiplier |
§⚠ HMAC-SHA-2: Belenky et al. TCHES 2023/3 (CDPA)
belenky2023_cdpa_hmac_sha2 proves that any implementation
of HMAC-SHA-2, even pure parallel hardware, leaks the secret
key in 30 K – 275 K traces under Carry-based Differential
Power Analysis. Software implementations leak even more
easily because the SHA-2 additions are explicit instructions
on a sequential pipeline.
For deployments where the threat model includes a level-2
attacker with EM / power probes (which is the baseline of any
lab-class evaluation), HMAC-SHA-2 keys in arcana must be
assumed extractable until T2-D ships.
T2-D will land a MaskedSha256 / MaskedSha512 behind the
sca-protected Cargo feature (mirroring quantica’s masking
convention). The masked variant is mathematically transparent
(bit-identical output) and routes through this Mac ctx
transparently when the feature is on.
Structs§
- Mac
- Stateful MAC context.