Package zeroecho.sdk.builders.alg

package zeroecho.sdk.builders.alg

Streaming cryptographic builders for symmetric encryption, signatures, MACs, digests, and KEM envelopes.

Classes in this package provide small, composable builders that configure cryptographic operations and produce streaming DataContent stages. The emphasis is on zero-copy streaming where feasible, clear separation between configuration (builders) and execution (content stages), and provider-agnostic algorithm lookup via the central registry.

Design goals

• Enable large-payload processing without materializing data in memory.
• Keep configuration fluent and explicit; keep execution pipeline-friendly.
• Resolve algorithms through the registry so applications can swap JCA providers easily.
• Offer explicit control of headers, trailers, and verification behavior where applicable.

Builders overview

• AesDataContentBuilder and ChaChaDataContentBuilder - stream symmetric encryption and decryption.
• HmacDataContentBuilder - compute or verify MAC tags in a streaming pipeline.
• DigestDataContentBuilder - compute digests/XOFs and, where supported, emit textual encodings.
• RsaEncDataContentBuilder and ElgamalEncDataContentBuilder - wrap asymmetric encryption.
• RsaSigDataContentBuilder - performs streaming RSA signatures and verification; other signature algorithms use the session-bound trailer builder in zeroecho.sdk.builders.
• KemDataContentBuilder - implement KEM-first envelopes and inject the derived key into a chosen symmetric payload builder.

Streaming model

Each builder implements a content-builder contract and produces a DataContent stage when built. The stage uses the registry to obtain a core context and attaches to an upstream InputStream; output is produced lazily as the stream is read. Signature and MAC stages can pass the body through while appending or verifying a trailing tag; symmetric stages may emit a compact header with non-secret parameters such as IV, nonce, tag length, or AAD hints.

Signatures and MACs

Signature and MAC builders support:

• Pass-through: output the message body while a trailing signature is captured or verified.
• Emit-only: consume the body and output only the signature (or a boolean verification result, when selected).

MAC builders mirror this pattern and can verify against an expected tag or a tag carried in the input trailer.

KEM envelopes

KemDataContentBuilder first collects KEM parameters (algorithm id, recipient key, KDF configuration), runs encapsulation or decapsulation to derive a symmetric key, and then injects that key into an explicit symmetric payload builder such as AesDataContentBuilder or ChaChaDataContentBuilder. This avoids duplicating KEM configuration across symmetric builders and matches a natural envelope workflow.

Key management

• Use a caller-supplied key object.
• Generate a new key or key pair using an algorithm-specific key-generation spec.
• Import a key from standard encodings (for example, X.509 public or PKCS#8 private) or other supported forms.

Builders typically provide convenience methods for common defaults (for example, AES-GCM or Ed25519).

Error handling and verification

• Verification failures usually surface as IOException at end-of-stream in verify mode.
• Some builders offer explicit emit-boolean modes or callbacks to report verification outcomes without throwing.
• Configuration errors (incompatible keys/specs) are detected early by underlying core factories.

Usage pattern

// A builder in this package produces a DataContent stage:
zeroecho.sdk.content.api.DataContent content = ...;

// Wire the upstream and stream the result to an output sink:
content.setInput(upstreamContent);
try (java.io.InputStream in = content.getStream()) {
    in.transferTo(out);
}

Thread safety

• Builder instances are mutable and not thread-safe; configure and use each instance on a single thread.
• Produced content stages are single-use; create a fresh instance per pipeline run.

Since:

1.0

Related Packages

Package	Description
zeroecho.sdk.builders	Builders for composing streaming data-content pipelines across core sources and algorithm-specific stages.
zeroecho.sdk.builders.core	Core builders for composing streaming DataContent pipelines and plain sources.

Class	Description
AesDataContentBuilder	Fluent builder that exposes AES as a DataContent in pull‑mode.
ChaChaDataContentBuilder	ChaChaDataContentBuilder builds streaming ChaCha20 and ChaCha20-Poly1305 pipelines that encrypt or decrypt as an InputStream is consumed.
DigestDataContentBuilder	DigestDataContentBuilder constructs streaming pipelines that compute message digests while reading an InputStream.
ElgamalEncDataContentBuilder	ElgamalEncDataContentBuilder builds streaming ElGamal encryption or decryption pipelines that operate as an InputStream is consumed.
HmacDataContentBuilder	HmacDataContentBuilder constructs streaming pipelines that compute or verify HMAC tags while an InputStream is consumed.
HmacDataContentBuilder.Mode	Mode selects whether the pipeline computes an HMAC tag or verifies one.
KemDataContentBuilder	KEM-based envelope builder that first collects KEM parameters and only then delegates to an explicit symmetric builder for the payload.
RsaEncDataContentBuilder	RsaEncDataContentBuilder builds streaming RSA encryption or decryption pipelines that operate while an InputStream is consumed.
RsaSigDataContentBuilder	RsaSigDataContentBuilder builds streaming RSA signature pipelines that sign or verify as an InputStream is consumed.
RsaSigDataContentBuilder.Mode	Mode selects whether the builder signs or verifies.