Class JcaDigestContext

java.lang.Object

zeroecho.core.alg.digest.JcaDigestContext

All Implemented Interfaces:

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

public final class JcaDigestContext
extends Object
implements DigestContext

Digest context that adapts a JCA MessageDigest to a pull-based streaming pipeline.

JcaDigestContext implements DigestContext for Sha2Sha3Algorithm by delegating to a JCA MessageDigest and exposing the TagEngine contract. As data is read from the wrapped stream the digest state is updated; at end-of-stream the digest is finalized and either appended as a trailer (produce mode) or compared against an expected tag (verify mode).

Features

• Supports SHA-2, SHA-3, and SHAKE digests as defined by DigestSpec.
• Provides pull-stream semantics via wrap(java.io.InputStream).
• Two modes:
  • Produce mode: appends the computed digest as a trailer.
  • Verify mode: computes the digest and compares it to an expected tag using a pluggable verification approach (see setVerificationApproach(ThrowingBiPredicate.VerificationBiPredicate)).
• For XOFs (SHAKE), the output length is explicitly controlled by DigestSpec.

Verification approach

Verification is delegated to a ThrowingBiPredicate.VerificationBiPredicate over byte[]. The default core returned by getVerificationCore() performs constant-time byte comparison (ByteVerificationStrategy). If no strategy is set explicitly, the effective verifier defaults to getVerificationCore().getThrowOnMismatch(), causing a mismatch to be signaled as an I/O error at end-of-stream.

Thread-safety

Instances are stateful and not thread-safe. Each context may wrap exactly one stream; subsequent calls to wrap(java.io.InputStream) are rejected.

Since:

1.0

Constructor Summary

Constructors

Constructor	Description
JcaDigestContext(CryptoAlgorithm algorithm, MessageDigest md, DigestSpec spec)	Creates a new digest context bound to a JCA MessageDigest.

Method Summary

Modifier and Type	Method	Description
CryptoAlgorithm	algorithm()	Returns the CryptoAlgorithm definition that created this context.
void	close()	Closes the active digest stream if one was opened.
ThrowingBiPredicate.VerificationBiPredicate<byte[]>	getVerificationCore()	Returns the core verification predicate for digest tags.
Key	key()	Returns the key associated with this context.
void	setExpectedTag(byte[] expected)	Installs an expected digest tag for verification mode.
void	setVerificationApproach(ThrowingBiPredicate.VerificationBiPredicate<byte[]> strategy)	Sets the verification approach used to compare computed and expected digests.
int	tagLength()	Returns the digest length in bytes.
InputStream	wrap(InputStream upstream)	Wraps an upstream InputStream in a digesting pipeline stage.

Methods inherited from class Object

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

Constructor Details

JcaDigestContext

public JcaDigestContext(CryptoAlgorithm algorithm,
 MessageDigest md,
 DigestSpec spec)

Creates a new digest context bound to a JCA MessageDigest.

This constructor is normally invoked by Sha2Sha3Algorithm:

MessageDigest md = MessageDigest.getInstance(spec.algorithm().jca());
return new JcaDigestContext(algo, md, spec);

Parameters:

algorithm - the owning algorithm descriptor

md - JCA message digest implementation

spec - digest parameters (algorithm, output length for XOFs)

Throws:

NullPointerException - if any parameter is null

IllegalArgumentException - if the output length for an XOF is invalid

Method Details

algorithm

public CryptoAlgorithm algorithm()

Returns the CryptoAlgorithm definition that created this context.

Specified by:

algorithm in interface CryptoContext

Returns:

algorithm descriptor

key

public Key key()

Returns the key associated with this context.

Digests are unkeyed; this method always returns null.

Specified by:

key in interface CryptoContext

Returns:

always null

close

public void close()

Closes the active digest stream if one was opened.

The close operation is non-throwing; any underlying IOException is suppressed to preserve pipeline robustness.

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 InputStream in a digesting pipeline stage.

Data read from the returned stream is passed through unchanged while being accumulated into the underlying MessageDigest. At end-of-stream the digest is finalized and either emitted as a trailer (produce mode) or compared to the expected tag (verify mode).

This method may be called at most once per context instance.

Specified by:

wrap in interface TagEngine<byte[]>

Parameters:

upstream - the input stream to wrap; must not be null

Returns:

a stream that transparently digests data

Throws:

IOException - if stream initialization fails

IllegalStateException - if wrap was already invoked on this instance

NullPointerException - if upstream is null

tagLength

public int tagLength()

Returns the digest length in bytes.

Specified by:

tagLength in interface TagEngine<byte[]>

Returns:

output length of the digest or XOF

setExpectedTag

public void setExpectedTag(byte[] expected)

Installs an expected digest tag for verification mode.

When provided, the context operates in verification mode: at end-of-stream the computed digest is compared against this tag using the effective verification strategy. Passing null clears the tag and leaves the mode unchanged.

Specified by:

setExpectedTag in interface TagEngine<byte[]>

Parameters:

expected - expected digest bytes; copied defensively (may be null to clear)

setVerificationApproach

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

Sets the verification approach used to compare computed and expected digests.

If no strategy is set explicitly, the effective verifier defaults to getVerificationCore().getThrowOnMismatch().

Specified by:

setVerificationApproach in interface TagEngine<byte[]>

Parameters:

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

getVerificationCore

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

Returns the core verification predicate for digest tags.

The default core is a constant-time byte-array comparison implemented by ByteVerificationStrategy.

Specified by:

getVerificationCore in interface TagEngine<byte[]>

Returns:

base verification predicate (never null)