Class XmssSignatureContext

java.lang.Object
zeroecho.core.alg.xmss.XmssSignatureContext
All Implemented Interfaces:
Closeable, AutoCloseable, CryptoContext, SignatureContext, TagEngine<Signature>
public final class XmssSignatureContext extends Object implements SignatureContext
Streaming signature context for XMSS (eXtended Merkle Signature Scheme).

XMSS is a stateful hash-based signature scheme standardized in RFC 8391. Unlike SLH-DSA/SPHINCS+, XMSS maintains a leaf index in the private key and each signing operation advances that index irreversibly.

This generic context cannot sign; freshly enrolled keys may use StatefulSigner. Private-key construction fails before provider initialization or signature-size discovery and never consumes a leaf. Verification remains available.

Usage — verification


XmssSignatureContext vctx = new XmssSignatureContext(alg, publicKey);
vctx.setExpectedTag(signature);
try (InputStream in = vctx.wrap(bodyWithoutTrailer)) {
    in.transferTo(OutputStream.nullOutputStream());
}

Signature length formula

For a digest output length of n bytes and tree height h:

  • n = 32 (SHA-256 / SHAKE-128): sig_len = 4 + 32 * (68 + h)
  • n = 64 (SHA-512 / SHAKE-256): sig_len = 4 + 64 * (132 + h)

The values 68 = 1 + 67 (index + WOTS+ p) and 132 = 1 + 131 reflect the Winternitz parameter counts p for w = 16 (the value used in the BC implementation for these parameter sets).

Thread-safety

Instances are stateful and not thread-safe. Use one instance per signing or verification operation.

Since:
1.0

  • Constructor Details

    • XmssSignatureContext

      public XmssSignatureContext(CryptoAlgorithm algorithm, PrivateKey privateKey) throws GeneralSecurityException
      Rejects XMSS signing without using or changing the private key.
      Parameters:
      algorithm - owning algorithm descriptor
      privateKey - private key
      Throws:
      UnsupportedRoleException - always; use the explicit durable capability
      GeneralSecurityException - retained for source compatibility

    • XmssSignatureContext

      public XmssSignatureContext(CryptoAlgorithm algorithm, PublicKey publicKey) throws GeneralSecurityException
      Creates an XMSS verification context bound to the given public key.

      The expected signature length is derived from key parameters without any signing operation.

      Parameters:
      algorithm - owning algorithm descriptor; must not be null
      publicKey - an XMSS public key (XMSSKey); must not be null
      Throws:
      GeneralSecurityException - if the key type is unrecognized or the JCA engine cannot be initialized

  • Method Details

    • algorithm

      public CryptoAlgorithm algorithm()
      Description copied from interface: CryptoContext
      Returns the algorithm that created this context.
      Specified by:
      algorithm in interface CryptoContext
      Returns:
      the algorithm definition that owns this context

    • key

      public Key key()
      Description copied from interface: CryptoContext
      Returns the key bound to this context.

      For unkeyed contexts such as digests, this may be NullKey.INSTANCE.

      Specified by:
      key in interface CryptoContext
      Returns:
      the cryptographic key or sentinel bound to this context

    • close

      public void close()
      Description copied from interface: CryptoContext
      Completes the context's implementation-specific cleanup.

      Implementations release resources they explicitly own; cleanup can be a no-op for contexts holding only borrowed or garbage-collected state. The bound key remains caller-owned: closing a context never destroys the key. Callers that own a destroyable key must destroy it explicitly after all contexts and other consumers have released it. Streams returned by the context have independent lifecycles: callers must complete and close those streams before closing the context. This method does not promise to finalize stream output or verify authentication tags.

      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
      Description copied from interface: TagEngine
      Wraps the given upstream stream with a filtering stream that both passes bytes through and updates the tag engine state.

      In produce mode, the wrapper emits the original data followed by the generated tag trailer when EOF is reached. In verify mode, the wrapper validates the expected tag either immediately or at EOF, depending on the engine and the configured verification approach.

      Specified by:
      wrap in interface TagEngine<Signature>
      Parameters:
      upstream - source of plaintext or ciphertext; must not be null
      Returns:
      a new stream that applies tag computation or verification
      Throws:
      IOException - if wrapping fails or the engine cannot allocate required resources

    • tagLength

      public int tagLength()
      Description copied from interface: TagEngine
      Returns the fixed length in bytes of the final authentication tag.

      Higher layers use this value to strip or append trailers during stream processing.

      Specified by:
      tagLength in interface TagEngine<Signature>
      Returns:
      the tag length in bytes

    • setExpectedTag

      public void setExpectedTag(byte[] expected)
      Description copied from interface: TagEngine
      Supplies the expected tag for verify mode.

      Engines may verify immediately if the computed tag is already known, or they may defer verification until EOF. This method is invoked at most once per wrapped stream.

      The default implementation throws UnsupportedOperationException. Engines that support verification must override this method.

      Specified by:
      setExpectedTag in interface TagEngine<Signature>
      Parameters:
      expected - expected tag value; implementations may defensively copy this array

    • setVerificationApproach

      public void setVerificationApproach(ThrowingBiPredicate.VerificationBiPredicate<Signature> strategy)
      Description copied from interface: TagEngine
      Sets the verification approach used to compare computed and expected tags.

      Typical implementations will default to a constant-time comparison for byte[] values. Callers may replace or decorate the strategy, for example with ThrowingBiPredicate.VerificationBiPredicate.getThrowOnMismatch() to raise an exception on mismatch, or ThrowingBiPredicate.VerificationBiPredicate.getFlagOkInCtx(conflux.CtxInterface, conflux.Key) to record the outcome in a context.

      Specified by:
      setVerificationApproach in interface TagEngine<Signature>
      Parameters:
      strategy - the verification predicate to use; must not be null

    • getVerificationCore

      public ThrowingBiPredicate.VerificationBiPredicate<Signature> getVerificationCore()
      Description copied from interface: TagEngine
      Returns the current verification approach.
      Specified by:
      getVerificationCore in interface TagEngine<Signature>
      Returns:
      the verification predicate in use; never null after initialization