Class HybridKexBuilder

java.lang.Object
zeroecho.sdk.builders.HybridKexBuilder
public final class HybridKexBuilder extends Object
Fluent builder for constructing hybrid KEX contexts.

The builder supports the two practical hybrid variants:

  • CLASSIC_AGREEMENT + KEM_ADAPTER (classic peer public is provided out-of-band)
  • PAIR_MESSAGE + KEM_ADAPTER (classic public key is carried in the hybrid message)

The builder also supports transcript binding and optional policy enforcement before returning the context.

Usage sketch

HybridKexContext ctx = HybridKexBuilder.builder()
    .profile(HybridKexProfile.defaultProfile(32))
    .transcript(new HybridKexTranscript().addUtf8("suite", "X25519+MLKEM768"))
    .policy(new HybridKexPolicy(128, 192, 32))
    .classicAgreement()
        .algorithm("Xdh").spec(XdhSpec.X25519)
        .privateKey(alicePriv).peerPublic(bobPub)
    .pqcKem()
        .algorithm("ML-KEM").peerPublic(bobPqcPub)
    .buildInitiator();

Instances are mutable and not thread-safe.

Since:
1.0

  • Method Details

    • builder

      public static HybridKexBuilder builder(ZeroEchoSession session)
      Creates a new builder instance.
      Parameters:
      session - explicit runtime configuration
      Returns:
      new builder
      Throws:
      NullPointerException - if session is null

    • profile

      public HybridKexBuilder profile(HybridKexProfile profile)
      Sets the hybrid profile (HKDF salt/info/output length).
      Parameters:
      profile - profile (must not be null)
      Returns:
      this builder

    • transcript

      public HybridKexBuilder transcript(HybridKexTranscript transcript)
      Optional transcript used to bind HKDF info.

      If provided, its bytes are concatenated to the profile hkdfInfo with a single zero byte separator. This preserves the profile label as a domain separator while incorporating handshake context.

      Parameters:
      transcript - transcript (may be null to clear)
      Returns:
      this builder

    • policy

      public HybridKexBuilder policy(HybridKexPolicy policy)
      Optional hybrid policy enforcement.
      Parameters:
      policy - policy (may be null to clear)
      Returns:
      this builder

    • classicAgreement

      public HybridKexBuilder.ClassicAgreement classicAgreement()
      Selects the classic leg in HybridKexBuilder.ClassicMode.CLASSIC_AGREEMENT mode.

      In this mode, the classic peer public key is assumed to be available out-of-band (for example via a certificate, a directory, or a higher-level handshake message). The hybrid wire message therefore typically carries only the PQC payload (KEM ciphertext), while the classic leg is configured via AgreementContext.setPeerPublic(PublicKey).

      Calling this method resets any previously configured PAIR_MESSAGE inputs (classicKeyPair) to prevent ambiguous configuration.

      Returns:
      classic agreement configurator
      Since:
      1.0

    • classicPairMessage

      public HybridKexBuilder.ClassicPairMessage classicPairMessage()
      Selects the classic leg in HybridKexBuilder.ClassicMode.PAIR_MESSAGE mode.

      In this mode, the classic leg is message-capable: the public key is carried as an explicit classic message (typically an SPKI encoding) and becomes part of the hybrid peer message. This enables a fully message-oriented handshake where both legs contribute to the wire payload (classic public-key message + PQC ciphertext).

      Calling this method resets any previously configured CLASSIC_AGREEMENT inputs (classicPrivate and classicPeerPublic) to prevent ambiguous configuration.

      Returns:
      classic pair-message configurator
      Since:
      1.0

    • pqcKem

      public HybridKexBuilder.PqcKem pqcKem()
      Selects configuration of the post-quantum leg (KEM adapter).

      The PQC leg is always treated as a message-based agreement:

      Returns:
      PQC KEM configurator
      Since:
      1.0

    • buildInitiator

      public HybridKexContext buildInitiator()
      Builds initiator-side context.
      Returns:
      initiator context

    • buildResponder

      public HybridKexContext buildResponder()
      Builds responder-side context.
      Returns:
      responder context

    • exporterFromOkm

      public HybridKexExporter exporterFromOkm(byte[] okm)
      Creates an exporter seeded from a derived OKM value.
      Parameters:
      okm - derived OKM (for example HybridKexContext.deriveSecret())
      Returns:
      exporter