Package zeroecho.sdk.builders

package zeroecho.sdk.builders

Builders for composing streaming data-content pipelines across core sources and algorithm-specific stages.

This package groups the top-level builder APIs used by the SDK to create streaming DataContent pipelines. It ties together the generic chain and plain-source builders from zeroecho.sdk.builders.core with the algorithm-focused builders from zeroecho.sdk.builders.alg, and provides cross-cutting utilities such as TagTrailerDataContentBuilder.

What lives where

• Core builders - generic composition and plain sources in zeroecho.sdk.builders.core:
  • DataContentBuilder - minimal contract implemented by all builders.
  • DataContentChainBuilder - chains multiple stages in encrypt or decrypt mode.
  • PlainBytesBuilder, PlainStringBuilder, PlainFileBuilder - plain, non-cryptographic sources.
• Algorithm builders - streaming crypto stages in zeroecho.sdk.builders.alg:
  • Symmetric encryption: AesDataContentBuilder, ChaChaDataContentBuilder.
  • Asymmetric encryption: RsaEncDataContentBuilder, ElgamalEncDataContentBuilder.
  • RSA signatures: RsaSigDataContentBuilder; generic signature trailers use SignatureTrailerDataContentBuilder.
  • MAC and digest: HmacDataContentBuilder, DigestDataContentBuilder.
  • KEM envelopes: KemDataContentBuilder (derives a symmetric key and injects it into a chosen symmetric payload builder).
• Cross-cutting:
  • TagTrailerDataContentBuilder - appends or verifies an authentication tag carried as an input trailer using a TagEngine.
  • SignatureTrailerDataContentBuilder - signature-specialized trailer builder intended to replace TagTrailerDataContentBuilder<Signature> in most signature use cases. It can wrap existing signature engines and construct single-algorithm and hybrid signature contexts.

Chaining model

Pipelines are assembled by creating a DataContentChainBuilder in encrypt or decrypt mode and adding builder stages in order. Each stage is built in the selected mode, linked to the previous tail via setInput(...) and exposed as a single tail DataContent.

Headers, trailers, and verification

• Symmetric builders can emit compact headers containing non-secret parameters (for example, IV or nonce) and parse them on decrypt.
• Signature and MAC builders support pass-through or emit-only forms for signatures or tags.
• TagTrailerDataContentBuilder focuses on trailer-style tags with explicit verify policies.
• SignatureTrailerDataContentBuilder provides the corresponding trailer functionality specialized for digital signatures, including hybrid signature construction.

Typical usage

// Build a simple HMAC trailer pipeline over a plain string and append the tag.
zeroecho.sdk.content.api.DataContent macEnc =
    zeroecho.sdk.builders.core.DataContentChainBuilder.encrypt()
        .add(zeroecho.sdk.builders.core.PlainStringBuilder.builder().value("hello"))
        .add(new zeroecho.sdk.builders.TagTrailerDataContentBuilder(
                zeroecho.core.tag.TagEngineBuilder.hmac(secretKey, zeroecho.core.alg.hmac.HmacSpec.sha256())))
        .build();

// Build the corresponding verification pipeline that strips the trailer and throws on mismatch.
zeroecho.sdk.content.api.DataContent macDec =
    zeroecho.sdk.builders.core.DataContentChainBuilder.decrypt()
        .add(new zeroecho.sdk.builders.TagTrailerDataContentBuilder(
                zeroecho.core.tag.TagEngineBuilder.hmac(secretKey, zeroecho.core.alg.hmac.HmacSpec.sha256())))
        .build();

Thread safety

• Builder instances are mutable and not thread-safe; configure and use each instance on a single thread.
• Produced DataContent stages are single-use and should not be shared across pipelines.

Since:

1.0

Related Packages

Package	Description
zeroecho.sdk	Consumer-facing ZeroEcho runtime and high-level integration APIs.
zeroecho.sdk.builders.alg	Streaming cryptographic builders for symmetric encryption, signatures, MACs, digests, and KEM envelopes.
zeroecho.sdk.builders.core	Core builders for composing streaming DataContent pipelines and plain sources.
zeroecho.sdk.guard	Multi-recipient envelope for symmetric payloads with pluggable recipients, reusable openers, and a compact header.
zeroecho.sdk.io	Stream utilities for SDK pipelines.
zeroecho.sdk.util	Utility helpers for provider setup, key derivation, randomness, encoding, and X.509 handling.

Classes

Class	Description
HybridKexBuilder	Fluent builder for constructing hybrid KEX contexts.
HybridKexBuilder.ClassicAgreement	Configurator for the classic leg in HybridKexBuilder.ClassicMode.CLASSIC_AGREEMENT mode.
HybridKexBuilder.ClassicPairMessage	Configurator for the classic leg in HybridKexBuilder.ClassicMode.PAIR_MESSAGE mode.
HybridKexBuilder.PqcKem	Configurator for the PQC leg (KEM adapter).
SignatureTrailerDataContentBuilder	Signature-specific trailer builder for DataContent pipelines.
SignatureTrailerDataContentBuilder.HybridSelector	Helper entry for hybrid signature construction.
SignatureTrailerDataContentBuilder.SingleSelector	Helper entry for single-algorithm signature construction.
TagTrailerDataContentBuilder<T>	Builder for DataContent pipelines that attach or verify an authentication tag at end of stream.