Class XWingKemContext

java.lang.Object
zeroecho.core.alg.xwing.XWingKemContext
All Implemented Interfaces:
Closeable, AutoCloseable, CryptoContext, KemContext
public final class XWingKemContext extends Object implements KemContext
KEM context for the X-Wing hybrid post-quantum key encapsulation mechanism.

X-Wing combines X25519 (classical) and ML-KEM-768 (post-quantum) into a single hybrid KEM as specified in draft-connolly-cfrg-xwing-kem. It provides security if either component is secure.

Because there is no JCA provider binding for X-Wing in BouncyCastle 1.86, this context uses the low-level BC API (pqc.crypto.xwing.*) directly. The keys must therefore be instances of XWingPublicKey (encapsulate mode) or XWingPrivateKey (decapsulate mode) as produced by XWingAlgorithm.

Thread-safety

Instances are not thread-safe. Sequential operations in the configured role are supported while the borrowed key remains usable; no single-use guard is maintained. Closing this context does not destroy the borrowed key.

Since:
1.0

  • Constructor Details

    • XWingKemContext

      public XWingKemContext(CryptoAlgorithm algorithm, PublicKey k)
      Creates a context in encapsulation role bound to the given public key.
      Parameters:
      algorithm - the owning algorithm instance; must not be null
      k - an XWingPublicKey; must not be null
      Throws:
      NullPointerException - if any argument is null
      IllegalArgumentException - if the key is not an imported or generated X-Wing public key

    • XWingKemContext

      public XWingKemContext(CryptoAlgorithm algorithm, PrivateKey k)
      Creates a context in decapsulation role bound to the given private key.
      Parameters:
      algorithm - the owning algorithm instance; must not be null
      k - an XWingPrivateKey; must not be null
      Throws:
      NullPointerException - if any argument is null
      IllegalArgumentException - if the key is not an imported or generated X-Wing private key
      IllegalStateException - if the private key was destroyed

  • 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

    • encapsulate

      public KemContext.KemResult encapsulate() throws IOException
      Encapsulates a fresh shared secret to the recipient's X-Wing public key.
      Specified by:
      encapsulate in interface KemContext
      Returns:
      ciphertext and shared secret
      Throws:
      IllegalStateException - if this context is in decapsulation mode
      IOException - if encapsulation fails

    • decapsulate

      public byte[] decapsulate(byte[] ciphertext) throws IOException
      Decapsulates an X-Wing ciphertext using the bound private key.
      Specified by:
      decapsulate in interface KemContext
      Parameters:
      ciphertext - the encapsulated bytes produced by the peer's encapsulate() call
      Returns:
      the recovered shared secret
      Throws:
      IllegalStateException - if this context is in encapsulation mode
      IOException - if decapsulation fails
      IllegalArgumentException - if the ciphertext is null or not exactly 1120 bytes