Class HmacMacContext

java.lang.Object

zeroecho.core.alg.hmac.HmacMacContext

All Implemented Interfaces:

Closeable, AutoCloseable, CryptoContext, MacContext, TagEngine<byte[]>

public final class HmacMacContext
extends Object
implements MacContext

Streaming HMAC context backed by the JCA Mac API.

HmacMacContext implements MacContext and integrates with the TagEngine contract to support both production and verification in a pull-based streaming pipeline. One instance is intended for one wrapped stream.

TagEngine contract

• Produce mode (no expected tag set): wrap(InputStream) returns a pass-through stream that emits the full body followed by the computed MAC as a trailer.
• Verify mode (expected tag set): the stream emits only the body. At EOF, the computed MAC is compared with the expected tag using the configured verification approach set via setVerificationApproach(VerificationBiPredicate). Decorators such as ThrowingBiPredicate.VerificationBiPredicate.getThrowOnMismatch() or ThrowingBiPredicate.VerificationBiPredicate.getFlagOkInCtx(conflux.CtxInterface, conflux.Key) may be used to control error signaling.

CryptoContext contract

• algorithm() returns the owning CryptoAlgorithm.
• key() returns the SecretKey used for the MAC.
• close() closes the active wrapped stream (idempotent).

Verification approach

The core comparison strategy is provided by getVerificationCore(), which by default returns a constant-time byte-array comparator (ByteVerificationStrategy). If no explicit strategy is set, wrap(InputStream) applies that core strategy decorated with getThrowOnMismatch() so that mismatches raise an exception at EOF.

Thread-safety

This context is stateful and not thread-safe. After wrap(InputStream) has been called once, further calls are rejected.

Usage example

Produce HMAC-SHA256 trailer

SecretKey key = session.keyBuilders().symmetric().generate("HMAC", HmacKeyGenSpec.sha256(256));
HmacMacContext ctx = new HmacMacContext(CryptoAlgorithms.require("HMAC"), key, "HmacSHA256");
try (InputStream in = ctx.wrap(new FileInputStream("data.bin"))) {
    in.transferTo(OutputStream.nullOutputStream()); // body then MAC trailer
}

Verify with explicit strategy

HmacMacContext ctx = new HmacMacContext(CryptoAlgorithms.require("HMAC"), key, "HmacSHA256");
ctx.setVerificationApproach(ctx.getVerificationCore().getThrowOnMismatch());
ctx.setExpectedTag(expectedTag);
try (InputStream in = ctx.wrap(new FileInputStream("body.bin"))) {
    in.transferTo(OutputStream.nullOutputStream()); // throws on mismatch at EOF
}

Since:

1.0

Constructor Summary

Constructors

Constructor	Description
HmacMacContext(CryptoAlgorithm algorithm, SecretKey key, String macName)	Constructs an HMAC context for the given algorithm and key.

Method Summary

Modifier and Type	Method	Description
CryptoAlgorithm	algorithm()	Returns the algorithm descriptor associated with this context.
void	close()	Closes the active wrapped stream, if any.
ThrowingBiPredicate.VerificationBiPredicate<byte[]>	getVerificationCore()	Returns the core verification predicate for HMAC tags.
Key	key()	Returns the key used for HMAC operations.
void	setExpectedTag(byte[] expected)	Sets the expected tag for verification mode.
void	setVerificationApproach(ThrowingBiPredicate.VerificationBiPredicate<byte[]> strategy)	Sets the verification approach used in verify mode to compare the expected and computed tags.
int	tagLength()	Returns the MAC tag length in bytes.
InputStream	wrap(InputStream upstream)	Wraps an upstream input stream with HMAC computation.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

HmacMacContext

public HmacMacContext(CryptoAlgorithm algorithm,
 SecretKey key,
 String macName)
               throws GeneralSecurityException

Constructs an HMAC context for the given algorithm and key.

The constructor probes the MAC length by initializing a JCA Mac instance with the given key.

Parameters:

algorithm - owning algorithm descriptor

key - JCA secret key for HMAC

macName - canonical MAC algorithm name (e.g., "HmacSHA256")

Throws:

NullPointerException - if any argument is null

GeneralSecurityException - if the algorithm cannot be initialized with the given key

Method Details

algorithm

public CryptoAlgorithm algorithm()

Returns the algorithm descriptor associated with this context.

Specified by:

algorithm in interface CryptoContext

Returns:

owning algorithm

key

public Key key()

Returns the key used for HMAC operations.

Specified by:

key in interface CryptoContext

Returns:

JCA secret key

close

public void close()

Closes the active wrapped stream, if any.

Idempotent: multiple calls are safe. Any underlying I/O exceptions are suppressed.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Specified by:

close in interface CryptoContext

wrap

public InputStream wrap(InputStream upstream)
                 throws IOException

Wraps an upstream input stream with HMAC computation.

In produce mode, the returned stream emits the body followed by the computed tag. In verify mode, it emits the body only and validates at EOF using the configured verification approach (default: throw on mismatch).

Specified by:

wrap in interface TagEngine<byte[]>

Parameters:

upstream - input stream to wrap; must not be null

Returns:

wrapped input stream

Throws:

IOException - if initialization fails

IllegalStateException - if this context has already been used

NullPointerException - if upstream is null

tagLength

public int tagLength()

Returns the MAC tag length in bytes.

Specified by:

tagLength in interface TagEngine<byte[]>

Returns:

tag length

setExpectedTag

public void setExpectedTag(byte[] expected)

Sets the expected tag for verification mode.

Passing null clears verification and reverts to produce mode. The value is copied defensively. If a wrapped stream is already active, the expected tag of the underlying stream is updated as well.

Specified by:

setExpectedTag in interface TagEngine<byte[]>

Parameters:

expected - expected tag, or null to disable verification

setVerificationApproach

public void setVerificationApproach(ThrowingBiPredicate.VerificationBiPredicate<byte[]> strategy)

Sets the verification approach used in verify mode to compare the expected and computed tags.

If no strategy is set explicitly, the context will use getVerificationCore() decorated with ThrowingBiPredicate.VerificationBiPredicate.getThrowOnMismatch() so that mismatches raise an exception at EOF.

Specified by:

setVerificationApproach in interface TagEngine<byte[]>

Parameters:

strategy - verification predicate; may be null to keep the default

getVerificationCore

public ThrowingBiPredicate.VerificationBiPredicate<byte[]> getVerificationCore()

Returns the core verification predicate for HMAC tags.

The default core is a constant-time byte-array comparison implemented by ByteVerificationStrategy. Callers may decorate it with ThrowingBiPredicate.VerificationBiPredicate.getThrowOnMismatch() or ThrowingBiPredicate.VerificationBiPredicate.getFlagOkInCtx(conflux.CtxInterface, conflux.Key) depending on the desired reporting behavior.

Specified by:

getVerificationCore in interface TagEngine<byte[]>

Returns:

the base verification predicate (never null)