Package zeroecho.core.alg.hmac

package zeroecho.core.alg.hmac
HMAC algorithms, streaming MAC contexts, and key specifications.

This package integrates Hash-based Message Authentication Code (HMAC) into the core layer. It provides the algorithm descriptor, a streaming MAC context that can produce or verify tags, operation specifications for choosing the digest family, and key specifications for generation and import.

Scope and responsibilities

  • Register a canonical HMAC algorithm and declare the KeyUsage.MAC role.
  • Expose a streaming MacContext that appends tags in produce mode or verifies an expected tag at end of stream in verify mode.
  • Provide immutable specs for selecting the HMAC variant and destroyable specs for importing raw key material.
  • Encapsulate JCA/JCE interop and provider checks behind small factories.

Components

  • HmacAlgorithm: algorithm descriptor that wires the MAC role to a streaming context and registers symmetric key builders for generation and import.
  • HmacMacContext: streaming MAC context backed by Mac; supports produce and verify modes under a clear verification policy.
  • HmacSpec: operation specification selecting the HMAC variant (e.g., SHA-256/384/512).
  • HmacKeyGenSpec: parameters for generating secret keys for a specific HMAC variant.
  • HmacKeyImportSpec: wrapper for importing existing raw keys, with Base64/hex helpers.
  • HmacStream: internal passthrough input stream implementing the byte-pumping and trailer/verification logic for the MAC context.

Design notes

  • Algorithm descriptors are immutable and safe to share.
  • Streaming contexts are stateful and not thread-safe; use a new instance per wrapped stream.
  • Key specification classes defensively copy input and output byte arrays.
  • Verification behavior is explicit: failures either throw or are recorded in a caller-provided context.
Since:
1.0