Class HybridDerived

java.lang.Object
zeroecho.sdk.hybrid.derived.HybridDerived
public final class HybridDerived extends Object
Builder-style utility for deriving purpose-separated key material from a hybrid KEX exporter and applying it to streaming algorithm builders.

This class does not implement new cryptographic primitives. It derives keying bytes via HKDF labels (using HybridKexExporter) and injects them into existing builder instances.

Labeling

Derivation uses a base label, plus fixed suffixes for individual fields:

  • label + "/key" for the secret key
  • label + "/aad" for AEAD AAD (optional, if derived)

A caller-supplied transcript binding (public handshake context) may be included and will be passed to the exporter as info. This improves cross-protocol separation and reduces configuration mistakes.

Thread safety

Instances are mutable and not thread-safe.

Since:
1.0

  • Method Details

    • from

      public static HybridDerived from(HybridKexExporter exporter)
      Creates a new derived-material builder backed by an exporter.
      Parameters:
      exporter - exporter seeded from a hybrid KEX result (must not be null)
      Returns:
      new derived-material builder
      Throws:
      NullPointerException - if exporter is null
      Since:
      1.0

    • label

      public HybridDerived label(String label)
      Sets the base label used for purpose separation.

      The label should identify the protocol purpose of the derived material, for example "app/enc" or "handshake/confirm".

      Parameters:
      label - base label (must not be null or empty)
      Returns:
      this builder
      Throws:
      NullPointerException - if label is null
      IllegalArgumentException - if label is empty
      Since:
      1.0

    • transcript

      public HybridDerived transcript(byte[] transcript)
      Sets transcript binding bytes used as exporter info.

      The transcript should contain only public context (negotiated suite, public keys/messages, channel binding, etc.). It must not contain secrets.

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

    • aad

      public HybridDerived aad(byte[] aad)
      Supplies explicit AAD bytes to be injected into AEAD builders.

      If set, no AAD derivation is performed.

      Parameters:
      aad - AAD bytes (may be null to clear)
      Returns:
      this builder
      Since:
      1.0

    • deriveAad

      public HybridDerived deriveAad(int aadLen)
      Requests deterministic derivation of AAD bytes from the exporter.

      This is optional. Many applications prefer to keep AAD as an application-defined, already-available public context. If derived, the AAD is separated using label + "/aad".

      Parameters:
      aadLen - number of bytes to derive (must be >= 1)
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if aadLen < 1
      Since:
      1.0

    • applyToAesGcm

      public AesDataContentBuilder applyToAesGcm(AesDataContentBuilder aes, int keyBits)
      Derives an AES key and applies it with optional AAD to the provided AES builder.

      The returned value is the same builder instance to preserve fluent pipeline construction.

      Parameters:
      aes - AES builder to configure (must not be null)
      keyBits - AES key size in bits (128/192/256)
      Returns:
      the provided builder instance
      Throws:
      NullPointerException - if aes is null
      IllegalArgumentException - if keyBits is invalid
      Since:
      1.0

    • applyToChaChaAead

      public ChaChaDataContentBuilder applyToChaChaAead(ChaChaDataContentBuilder chacha, int keyBits)
      Derives a ChaCha key and applies it with optional AAD to the provided ChaCha builder.

      The returned value is the same builder instance to preserve fluent pipeline construction.

      Parameters:
      chacha - ChaCha builder to configure (must not be null)
      keyBits - key size in bits (typically 256)
      Returns:
      the provided builder instance
      Throws:
      NullPointerException - if chacha is null
      IllegalArgumentException - if keyBits is invalid
      Since:
      1.0

    • applyToHmac

      public HmacDataContentBuilder applyToHmac(HmacDataContentBuilder hmac)
      Derives a MAC key using the builder's recommended size and applies it to the provided HMAC builder.

      This is the preferred integration method because it avoids duplicated configuration: the HMAC variant is chosen by the builder (HmacDataContentBuilder.spec()), and the key size recommendation is provided by HmacDataContentBuilder.recommendedKeyBits().

      The returned value is the same builder instance to preserve fluent pipeline construction.

      Parameters:
      hmac - HMAC builder to configure (must not be null)
      Returns:
      the provided builder instance
      Throws:
      NullPointerException - if hmac is null
      IllegalStateException - if this HybridDerived instance is missing required base configuration
      Since:
      1.0

    • applyToHmac

      public HmacDataContentBuilder applyToHmac(HmacDataContentBuilder hmac, int keyBits)
      Derives a MAC key of an explicit size (override) and applies it to the provided HMAC builder.

      This overload exists for advanced use-cases where the application intentionally chooses a key size different from HmacSpec.recommendedKeyBits(), for example to align a policy across different MAC functions or to satisfy interoperability constraints.

      Because HMAC accepts arbitrary key lengths, this method does not attempt to validate semantic suitability of keyBits. Applications that require stricter controls should enforce them via policy (for example minimum bit strength) and use transcript-bound labels to guarantee key separation.

      The returned value is the same builder instance to preserve fluent pipeline construction.

      Parameters:
      hmac - HMAC builder to configure (must not be null)
      keyBits - key size in bits (must be a positive multiple of 8)
      Returns:
      the provided builder instance
      Throws:
      NullPointerException - if hmac is null
      IllegalArgumentException - if keyBits is invalid
      IllegalStateException - if this HybridDerived instance is missing required base configuration
      Since:
      1.0