Class LmsSignatureContext

java.lang.Object
zeroecho.core.alg.lms.LmsSignatureContext
All Implemented Interfaces:
Closeable, AutoCloseable, CryptoContext, SignatureContext, TagEngine<Signature>
public final class LmsSignatureContext extends Object implements SignatureContext
Streaming signature context for LMS (Leighton–Micali Signatures).

LMS is a stateful hash-based one-time signature scheme standardized in RFC 8554. Each LMS private key is a Merkle tree of Winternitz OTS (LMOTS) keys; every signing operation consumes one leaf and is therefore irreversible.

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


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

Thread-safety

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

Since:
1.0

  • Constructor Details

    • LmsSignatureContext

      public LmsSignatureContext(CryptoAlgorithm algorithm, PrivateKey privateKey) throws GeneralSecurityException
      Rejects LMS 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

    • LmsSignatureContext

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

      The expected signature length is derived from the LMS/LMOTS parameter set encoded in the public key, without any signing operation.

      Parameters:
      algorithm - owning algorithm descriptor; must not be null
      publicKey - an LMS public key; must not be null
      Throws:
      GeneralSecurityException - if the key is invalid or the signature length cannot be determined

  • 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