Interface KemContext

All Superinterfaces:

AutoCloseable, Closeable, CryptoContext

All Known Implementing Classes:

BikeKemContext, CmceKemContext, FrodoKemContext, HqcKemContext, KyberKemContext, NtruKemContext, NtrulPrimeKemContext, SaberKemContext, SntruPrimeKemContext, XWingKemContext

public non-sealed interface KemContext
extends CryptoContext

Context for performing key encapsulation and decapsulation (KEM) operations.

A KemContext encapsulates the state for algorithms that exchange shared secrets using asymmetric primitives. KEMs are widely used in post-quantum cryptography and hybrid key exchange protocols.

Lifecycle

• Create a context via ZeroEchoSession#createContext(...) for the KeyUsage.ENCAPSULATE or KeyUsage.DECAPSULATE role.
• Call encapsulate() when acting as an initiator. The result includes both the ciphertext to send and the derived shared secret.
• Call decapsulate(byte[]) when acting as a responder, supplying the received ciphertext to recover the same shared secret.
• Dispose of the context with CryptoContext.close() to release resources.

Security considerations

• The shared secret must be immediately fed into a key-derivation function (KDF). Applications should zeroize the byte array after use.
• Structural ciphertext validation is algorithm-specific. KEMs with implicit rejection may return a pseudorandom secret for an invalid, correctly sized ciphertext; a returned secret does not authenticate the peer.
• Contexts are not guaranteed to be thread-safe; use one instance per flow.

Since:

1.0

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static final class	KemContext.KemResult	Encapsulation result holding both ciphertext and shared secret.

Method Summary

Modifier and Type	Method	Description
byte[]	decapsulate(byte[] ciphertext)	Performs decapsulation of the given ciphertext to recover the shared secret.
KemContext.KemResult	encapsulate()	Performs encapsulation, generating both the encapsulated ciphertext and the derived shared secret.

Methods inherited from interface CryptoContext

algorithm, close, key

Method Details

encapsulate

KemContext.KemResult encapsulate()
                          throws IOException

Performs encapsulation, generating both the encapsulated ciphertext and the derived shared secret.

Returns:

a KemContext.KemResult containing the ciphertext to transmit and the raw shared secret

Throws:

IOException - if encapsulation fails or the provider encounters an error

decapsulate

byte[] decapsulate(byte[] ciphertext)
            throws IOException

Performs decapsulation of the given ciphertext to recover the shared secret.

Parameters:

ciphertext - the peer’s encapsulation ciphertext

Returns:

a new byte array containing the raw shared secret

Throws:

IOException - if decapsulation fails or the input is invalid