Class HybridKexContexts

java.lang.Object

zeroecho.sdk.hybrid.kex.HybridKexContexts

public final class HybridKexContexts
extends Object

Factory utilities for constructing hybrid key exchange (KEX) contexts.

This class implements the SDK-level composition layer for hybrid key exchange. It does not introduce new core contracts; instead, it composes existing core contexts:

• AgreementContext for the classic (pre-quantum) leg (e.g. X25519, ECDH, DH), and
• MessageAgreementContext for the post-quantum leg (typically a KEM-style agreement, e.g. ML-KEM exposed as KeyUsage.AGREEMENT).

Handshake model

The two legs have different wire semantics:

• Classic leg generally uses a peer public key supplied out-of-band (certificate, directory, or a higher-level handshake message). This is represented by AgreementContext.setPeerPublic(java.security.PublicKey) and does not necessarily produce any explicit "to-be-sent" bytes.
• PQC leg is message-based: the initiator produces an encapsulation message (e.g. KEM ciphertext) via MessageAgreementContext.getPeerMessage(), and the responder consumes it via MessageAgreementContext.setPeerMessage(byte[]).

HybridKexContext unifies these semantics by emitting and consuming a single hybrid peer message that carries both legs (with the classic part typically empty for classic-only public-key exchange).

Error handling

Context construction is in-memory and reports configuration or provider failures through the security exception model of ZeroEchoSession. I/O failures remain associated with later stream processing.

Thread safety

This factory is stateless and thread-safe. Produced contexts are mutable and not thread-safe.

Since:

1.0

Method Summary

Modifier and Type	Method	Description
static HybridKexContext	initiator(ZeroEchoSession session, HybridKexProfile profile, String classicAlgId, PrivateKey classicInitiatorPrivate, PublicKey classicPeerPublic, ContextSpec classicSpec, String pqcAlgId, PublicKey pqcPeerPublic, ContextSpec pqcSpec)	Creates an initiator-side hybrid KEX context.
static HybridKexContext	initiatorPairMessage(ZeroEchoSession session, HybridKexProfile profile, String classicAlgId, KeyPairKey classicInitiatorKeyPair, ContextSpec classicSpec, String pqcAlgId, PublicKey pqcPeerPublic, ContextSpec pqcSpec)	Creates an initiator-side hybrid KEX where the classic leg is message-based (PAIR_MESSAGE).
static HybridKexContext	responder(ZeroEchoSession session, HybridKexProfile profile, String classicAlgId, PrivateKey classicResponderPrivate, PublicKey classicPeerPublic, ContextSpec classicSpec, String pqcAlgId, PrivateKey pqcResponderPrivate, ContextSpec pqcSpec)	Creates a responder-side hybrid KEX context.
static HybridKexContext	responderPairMessage(ZeroEchoSession session, HybridKexProfile profile, String classicAlgId, KeyPairKey classicResponderKeyPair, ContextSpec classicSpec, String pqcAlgId, PrivateKey pqcResponderPrivate, ContextSpec pqcSpec)	Creates a responder-side hybrid KEX where the classic leg is message-based (PAIR_MESSAGE).

Methods inherited from class Object

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

Method Details

initiator

public static HybridKexContext initiator(ZeroEchoSession session,
 HybridKexProfile profile,
 String classicAlgId,
 PrivateKey classicInitiatorPrivate,
 PublicKey classicPeerPublic,
 ContextSpec classicSpec,
 String pqcAlgId,
 PublicKey pqcPeerPublic,
 ContextSpec pqcSpec)

Creates an initiator-side hybrid KEX context.

This method constructs:

• a classic AgreementContext from the initiator's classic PrivateKey and configures it with the peer's classic PublicKey, and
• a PQC MessageAgreementContext from the peer's PQC PublicKey (encapsulation side).

The returned HybridKexContext will typically produce a peer message whose PQC part is non-empty (e.g. KEM ciphertext), while the classic part is empty unless the chosen classic implementation itself supports message mode.

Parameters:

session - explicit policy and audit boundary

profile - hybrid profile defining HKDF binding and output length

classicAlgId - classic agreement algorithm identifier (for example "X25519", "ECDH", "DH")

classicInitiatorPrivate - initiator private key for the classic leg

classicPeerPublic - peer public key for the classic leg

classicSpec - optional classic context spec (may be null if the algorithm supports a default)

pqcAlgId - post-quantum agreement algorithm identifier (for example "ML-KEM" exposed via KeyUsage.AGREEMENT)

pqcPeerPublic - peer public key for the PQC leg (encapsulation side)

pqcSpec - optional PQC context spec (may be null if the algorithm supports a default)

Returns:

initiator-side HybridKexContext

Throws:

NullPointerException - if any required argument is null

Since:

1.0

responder

public static HybridKexContext responder(ZeroEchoSession session,
 HybridKexProfile profile,
 String classicAlgId,
 PrivateKey classicResponderPrivate,
 PublicKey classicPeerPublic,
 ContextSpec classicSpec,
 String pqcAlgId,
 PrivateKey pqcResponderPrivate,
 ContextSpec pqcSpec)

Creates a responder-side hybrid KEX context.

This method constructs:

• a classic AgreementContext from the responder's classic PrivateKey and configures it with the peer's classic PublicKey, and
• a PQC MessageAgreementContext from the responder's PQC PrivateKey (decapsulation side).

The returned HybridKexContext is typically used after receiving the initiator's hybrid peer message and passing it to HybridKexContext.setPeerMessage(byte[]).

Parameters:

session - explicit policy and audit boundary

profile - hybrid profile defining HKDF binding and output length

classicAlgId - classic agreement algorithm identifier

classicResponderPrivate - responder private key for the classic leg

classicPeerPublic - peer public key for the classic leg

classicSpec - optional classic context spec (may be null)

pqcAlgId - post-quantum agreement algorithm identifier

pqcResponderPrivate - responder private key for the PQC leg (decapsulation side)

pqcSpec - optional PQC context spec (may be null)

Returns:

responder-side HybridKexContext

Throws:

NullPointerException - if any required argument is null

Since:

1.0

initiatorPairMessage

public static HybridKexContext initiatorPairMessage(ZeroEchoSession session,
 HybridKexProfile profile,
 String classicAlgId,
 KeyPairKey classicInitiatorKeyPair,
 ContextSpec classicSpec,
 String pqcAlgId,
 PublicKey pqcPeerPublic,
 ContextSpec pqcSpec)

Creates an initiator-side hybrid KEX where the classic leg is message-based (PAIR_MESSAGE).

The classic message is the SPKI encoding of the initiator's classic public key as produced by the underlying MessageAgreementContext. The PQC message is the PQC encapsulation payload (typically KEM ciphertext).

Parameters:

session - explicit policy and audit boundary

profile - hybrid profile defining HKDF binding and output length

classicAlgId - classic agreement algorithm identifier (e.g. "X25519", "ECDH", "DH")

classicInitiatorKeyPair - classic initiator key pair wrapped as KeyPairKey

classicSpec - classic context spec (may be null if supported)

pqcAlgId - post-quantum agreement algorithm identifier (e.g. "ML-KEM")

pqcPeerPublic - PQC peer public key (encapsulation side)

pqcSpec - optional PQC context spec (may be null)

Returns:

initiator-side HybridKexContext

Throws:

NullPointerException - if any required argument is null

Since:

1.0

responderPairMessage

public static HybridKexContext responderPairMessage(ZeroEchoSession session,
 HybridKexProfile profile,
 String classicAlgId,
 KeyPairKey classicResponderKeyPair,
 ContextSpec classicSpec,
 String pqcAlgId,
 PrivateKey pqcResponderPrivate,
 ContextSpec pqcSpec)

Creates a responder-side hybrid KEX where the classic leg is message-based (PAIR_MESSAGE).

The responder must call HybridKexContext.setPeerMessage(byte[]) with the initiator's hybrid message before calling HybridKexContext.deriveSecret().

Parameters:

session - explicit policy and audit boundary

profile - hybrid profile defining HKDF binding and output length

classicAlgId - classic agreement algorithm identifier

classicResponderKeyPair - classic responder key pair wrapped as KeyPairKey

classicSpec - classic context spec (may be null)

pqcAlgId - post-quantum agreement algorithm identifier

pqcResponderPrivate - PQC responder private key (decapsulation side)

pqcSpec - optional PQC context spec (may be null)

Returns:

responder-side HybridKexContext

Throws:

NullPointerException - if any required argument is null

Since:

1.0