Class KemDataContentBuilder

java.lang.Object

zeroecho.sdk.builders.alg.KemDataContentBuilder

All Implemented Interfaces:

DataContentBuilder<DataContent>

public final class KemDataContentBuilder
extends Object
implements DataContentBuilder<DataContent>

KEM-based envelope builder that first collects KEM parameters and only then delegates to an explicit symmetric builder for the payload.

This builder fixes the earlier unintuitive flow where each symmetric builder duplicated KEM settings. With KemDataContentBuilder you configure the KEM once (algorithm id, recipient key, KDF) and then select which payload cipher to use by supplying an AesDataContentBuilder or a ChaChaDataContentBuilder. The derived symmetric key is injected into the provided symmetric builder prior to building the payload stage.

Header format

The produced envelope prepends the KEM encapsulation ciphertext using the following simple framing:

  length L in Pack7 format
  L bytes of KEM ciphertext
  [payload stream produced by the symmetric builder]

The symmetric builder (AES or ChaCha) remains fully responsible for its own optional header (IV, AAD tag, etc.) which follows immediately after the KEM prefix.

Usage

// Encryption
DataContent content = DataContentChainBuilder.encrypt()
    .add(PlainStringBuilder.builder().value("hello"))
    .add(KemDataContentBuilder.builder()
           .kem("ML-KEM")
           .recipientPublic(recipientPub)
           .hkdfSha256("KEM-demo".getBytes(StandardCharsets.US_ASCII))
           .withAes(AesDataContentBuilder.builder().modeGcm(128).withHeader()))
    .build();

// Decryption
DataContent plain = DataContentChainBuilder.decrypt()
    .add(PlainBytesBuilder.builder().bytes(cipherBytes))
    .add(KemDataContentBuilder.builder()
           .kem("ML-KEM")
           .recipientPrivate(recipientPriv)
           .hkdfSha256("KEM-demo".getBytes(StandardCharsets.US_ASCII))
           .withAes(AesDataContentBuilder.builder().modeGcm(128).withHeader()))
    .build();

Thread-safety

Instances are not thread-safe. Create a new builder per pipeline/use.

Since:

1.0

Method Summary

Modifier and Type	Method	Description
DataContent	build(boolean encrypt)	Builds the KEM envelope stage in either encryption or decryption mode.
static KemDataContentBuilder	builder(ZeroEchoSession session)	Returns a new KemDataContentBuilder.
KemDataContentBuilder	derivedKeyBytes(int bytes)	Sets the number of derived key bytes to feed into the selected symmetric builder.
KemDataContentBuilder	directSecret()	Disables HKDF and uses the shared secret directly (or truncated) for the symmetric key.
KemDataContentBuilder	hkdfSha256(byte[] info)	Configures HKDF-SHA256 as the key derivation function using the provided info context string.
KemDataContentBuilder	kem(String id)	Sets the canonical KEM algorithm identifier to use (e.g., "ML-KEM").
KemDataContentBuilder	maxKemCiphertextLen(int maxBytes)	Sets a safety limit for the KEM ciphertext length accepted in decryption.
KemDataContentBuilder	recipientPrivate(PrivateKey k)	Sets the recipient private key for decapsulation (decryption path).
KemDataContentBuilder	recipientPublic(PublicKey k)	Sets the recipient public key for encapsulation (encryption path).
KemDataContentBuilder	withAes(AesDataContentBuilder b)	Selects AES as the payload cipher and supplies a configured AesDataContentBuilder that will receive the derived key.
KemDataContentBuilder	withChaCha(ChaChaDataContentBuilder b)	Selects ChaCha20/ChaCha20-Poly1305 as the payload cipher and supplies a configured ChaChaDataContentBuilder that will receive the derived key.

Methods inherited from class Object

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

Method Details

builder

public static KemDataContentBuilder builder(ZeroEchoSession session)

Returns a new KemDataContentBuilder.

Parameters:

session - active session used to create cryptographic contexts

Returns:

fresh builder instance

kem

public KemDataContentBuilder kem(String id)

Sets the canonical KEM algorithm identifier to use (e.g., "ML-KEM").

Parameters:

id - algorithm identifier resolved by the builder's ZeroEchoSession

Returns:

this builder

Throws:

NullPointerException - if id is null

recipientPublic

public KemDataContentBuilder recipientPublic(PublicKey k)

Sets the recipient public key for encapsulation (encryption path).

Parameters:

k - recipient public key

Returns:

this builder

Throws:

NullPointerException - if k is null

recipientPrivate

public KemDataContentBuilder recipientPrivate(PrivateKey k)

Sets the recipient private key for decapsulation (decryption path).

Parameters:

k - recipient private key

Returns:

this builder

Throws:

NullPointerException - if k is null

hkdfSha256

public KemDataContentBuilder hkdfSha256(byte[] info)

Configures HKDF-SHA256 as the key derivation function using the provided info context string. If not set, a default constant is used.

Parameters:

info - application/context info; copied defensively; may be empty but must not be null

Returns:

this builder

Throws:

NullPointerException - if info is null

directSecret

public KemDataContentBuilder directSecret()

Disables HKDF and uses the shared secret directly (or truncated) for the symmetric key. This is usually discouraged unless the KEM already outputs a uniformly random key.

Returns:

this builder

maxKemCiphertextLen

public KemDataContentBuilder maxKemCiphertextLen(int maxBytes)

Sets a safety limit for the KEM ciphertext length accepted in decryption. Values up to the algorithm's maximum should be allowed.

Parameters:

maxBytes - maximum number of ciphertext bytes; must be positive

Returns:

this builder

Throws:

IllegalArgumentException - if maxBytes is not positive

withAes

public KemDataContentBuilder withAes(AesDataContentBuilder b)

Selects AES as the payload cipher and supplies a configured AesDataContentBuilder that will receive the derived key.

The builder instance will be mutated to inject the derived key. Supply a fresh instance per pipeline to avoid cross-use.

Parameters:

b - AES payload builder to use

Returns:

this builder

Throws:

NullPointerException - if b is null

See Also:

• derivedKeyBytes(int)

withChaCha

public KemDataContentBuilder withChaCha(ChaChaDataContentBuilder b)

Selects ChaCha20/ChaCha20-Poly1305 as the payload cipher and supplies a configured ChaChaDataContentBuilder that will receive the derived key.

The builder instance will be mutated to inject the derived key. Supply a fresh instance per pipeline to avoid cross-use.

Parameters:

b - ChaCha payload builder to use

Returns:

this builder

Throws:

NullPointerException - if b is null

See Also:

• derivedKeyBytes(int)

derivedKeyBytes

public KemDataContentBuilder derivedKeyBytes(int bytes)

Sets the number of derived key bytes to feed into the selected symmetric builder. Defaults to 32 (AES-256 or ChaCha20).

Parameters:

bytes - number of key bytes; typical values are 16, 24, or 32

Returns:

this builder

Throws:

IllegalArgumentException - if bytes is not positive

build

public DataContent build(boolean encrypt)

Builds the KEM envelope stage in either encryption or decryption mode.

On encryption, the returned DataContent will:

1. encapsulate with the configured KEM and recipient public key,
2. derive a symmetric key via HKDF-SHA256 (or directly),
3. inject the key into the selected symmetric builder,
4. prepend the KEM encapsulation ciphertext, and
5. stream the symmetric payload output.

On decryption, it will:

1. read and decapsulate the KEM ciphertext using the recipient private key,
2. derive the symmetric key,
3. inject it into the symmetric builder, and
4. stream-decrypt the remaining payload bytes.

Specified by:

build in interface DataContentBuilder<DataContent>

Parameters:

encrypt - true to build the encryption stage, false for decryption

Returns:

a DataContent representing the configured KEM envelope

Throws:

IllegalStateException - if required parameters are missing or invalid