ZeroEcho API

ZeroEcho Library

ZeroEcho is a layered cryptography library delivered as the lib module. It exposes a minimal core of cryptographic primitives and a higher-level SDK of composition tools. The design favors clear separation of responsibilities, safe defaults, and extensibility for future algorithms and pipelines.

Table of registered cryptographic algorithms with grouped columns for families and key usages.

Registered cryptographic algorithms

Algorithm ID	Display Name	Family					Key usage									Default spec
		AGREEMENT	ASYMMETRIC	DIGEST	KEM	SYMMETRIC	AGREEMENT	DECAPSULATE	DECRYPT	DIGEST	ENCAPSULATE	ENCRYPT	MAC	SIGN	VERIFY
AES	AES (CBC/GCM/CTR)					✓			✓			✓				AES-GCM(tag=128) VoidSpec
BIKE	BIKE	✓			✓		✓	✓			✓					VoidSpec
CHACHA20	ChaCha20 (stream)					✓			✓			✓				ChaCha20(counter=1) VoidSpec
CHACHA20-POLY1305	ChaCha20-Poly1305 (AEAD)					✓			✓			✓				ChaCha20-Poly1305(tag=128) VoidSpec
CMCE	Classic McEliece (CMCE)	✓			✓		✓	✓			✓					VoidSpec
DH	DH	✓					✓									rfc7919_ffdhe2048
DIGEST	SHA-2/SHA-3/SHAKE			✓						✓						SHA-256
ECDH	ECDH	✓					✓									secp256r1
ECDSA	ECDSA		✓											✓	✓	secp256r1
Ed25519	Ed25519		✓											✓	✓	VoidSpec
Ed448	Ed448		✓											✓	✓	VoidSpec
ElGamal	ElGamal		✓						✓			✓				PKCS1Padding
Frodo	FrodoKEM	✓			✓		✓	✓			✓					VoidSpec
HMAC	HMAC (generic)					✓							✓			HmacSHA256
HQC	HQC	✓			✓		✓	✓			✓					VoidSpec
ML-KEM	Kyber (ML-KEM)	✓			✓		✓	✓			✓					VoidSpec
NTRU	NTRU (KEM)	✓			✓		✓	✓			✓					VoidSpec
NTRULPRime	NTRU LPRime	✓			✓		✓	✓			✓					VoidSpec
RSA	RSA		✓						✓			✓		✓	✓	OAEP(SHA256) PSS(SHA256,salt=32)
SABER	SABER	✓			✓		✓	✓			✓					VoidSpec
SNTRUPrime	SNTRU Prime	✓			✓		✓	✓			✓					VoidSpec
SPHINCS+	SPHINCSPLUS		✓											✓	✓	VoidSpec
Xdh	Xdh	✓					✓									X25519

Layering

• Core (zeroecho.core): low-level cryptographic engine. This includes algorithm definitions, stateful contexts, registry and metadata, specification and SPI contracts, and selected helpers required by algorithms (e.g., I/O, marshalling, tagging, auditing, policies).
• SDK (zeroecho.sdk): developer-facing composition layer built on the core. It provides content abstractions, fluent builders (both generic and per-algorithm), utilities for multi-recipient or composed flows, and supporting helpers used by those builders.

Package map (lib)

• zeroecho.core
  • alg: concrete algorithms and small shared helpers used by algorithms.
  • context: stateful operation interfaces (encryption, signatures, digests, MAC, agreement, KEM, and related variants).
  • spec / spi: specification objects and construction/factory contracts.
  • policy / audit / err / annotation: cross-cutting concerns within the core.
  • io / marshal / tag: helpers used by algorithms and contexts at runtime.
  • (root): provider/registry surface and core metadata.
• zeroecho.sdk
  • content: content abstractions, basic implementations, and export facilities.
  • builders: composition APIs, including generic builders and per-algorithm builders.
  • guard: utilities for multi-recipient and other composed workflows.
  • io / logging: supporting helpers used by the SDK layer and applications.

Design principles

• Stratification: the core remains focused on algorithms and correctness; the SDK focuses on developer ergonomics and composition.
• Composability: data flows are constructed through builders and content abstractions with predictable, chainable behavior.
• Extensibility: new algorithms, formats, and flows can be added with minimal impact on existing code.
• Safety: role-based binding and policy checks promote safe defaults and clear intent.

Intended use

Third-party applications depend on the lib module. Most integrations work at the SDK layer to compose data pipelines, while the core layer provides the cryptographic foundation and guarantees. The project’s structure and documentation aim to make entry points, responsibilities, and extension points explicit.

Packages

Package	Description
zeroecho.core	Core cryptography engine and registry for ZeroEcho.
zeroecho.core.alg	Concrete cryptographic algorithms and small helpers used by algorithms.
zeroecho.core.alg.aes	AES algorithm implementation and runtime wiring.
zeroecho.core.alg.bike	BIKE post-quantum key encapsulation and related utilities.
zeroecho.core.alg.chacha	ChaCha algorithm implementation and runtime wiring.
zeroecho.core.alg.cmce	Classic McEliece (CMCE) KEM integration and utilities.
zeroecho.core.alg.common.agreement	Adapters and generic contexts for key agreement built on the core SPI.
zeroecho.core.alg.common.eddsa	EdDSA (Edwards-curve Digital Signature Algorithm) key builders and contexts.
zeroecho.core.alg.common.sig	Streaming signature contexts and helpers that adapt JCA Signature to a pull-based pipeline.
zeroecho.core.alg.dh	Diffie-Hellman (DH) algorithm integration.
zeroecho.core.alg.digest	Digest algorithms (SHA-2, SHA-3, SHAKE) and their streaming contexts.
zeroecho.core.alg.ecdh	Elliptic Curve Diffie-Hellman (ECDH) key agreement integration.
zeroecho.core.alg.ecdsa	Elliptic Curve Digital Signature Algorithm (ECDSA) integration.
zeroecho.core.alg.ed25519	Ed25519 digital signature integration.
zeroecho.core.alg.ed448	Ed448 digital signature integration.
zeroecho.core.alg.elgamal	ElGamal asymmetric encryption integration.
zeroecho.core.alg.frodo	FrodoKEM post-quantum key encapsulation integration.
zeroecho.core.alg.hmac	HMAC algorithms, streaming MAC contexts, and key specifications.
zeroecho.core.alg.hqc	HQC post-quantum key encapsulation integration.
zeroecho.core.alg.kyber	Kyber (ML-KEM) post-quantum key encapsulation integration.
zeroecho.core.alg.ntru	NTRU post-quantum key encapsulation integration.
zeroecho.core.alg.ntruprime	NTRU Prime family key encapsulation mechanisms and related utilities.
zeroecho.core.alg.rsa	RSA encryption and signature integration.
zeroecho.core.alg.saber	SABER post-quantum key encapsulation integration.
zeroecho.core.alg.sphincsplus	SPHINCS+ post-quantum signature integration.
zeroecho.core.alg.xdh	XDH (X25519/X448) Diffie-Hellman key agreement integration.
zeroecho.core.annotation	Provides metadata contracts and annotations for cryptographic algorithms and specifications.
zeroecho.core.audit	Auditing utilities for cryptographic contexts, including event contracts and a JUL-backed listener.
zeroecho.core.context	Abstractions for cryptographic operation contexts.
zeroecho.core.err	Exception types used by the core to signal configuration errors and unexpected provider failures.
zeroecho.core.io	I/O helpers for block-based transforms, passthrough processing, and tail handling.
zeroecho.core.marshal	Marshalling utilities and conventions for compact, human-readable representations.
zeroecho.core.policy	Policy enforcement for algorithms, keys, and specifications.
zeroecho.core.spec	Specifications for keys and per-operation parameters.
zeroecho.core.spi	Service Provider Interfaces (SPI) for extending ZeroEcho with custom cryptographic algorithms and key builders.
zeroecho.core.storage	Human-editable key storage persisted in a compact UTF-8 text format.
zeroecho.core.tag	Streaming tag computation and verification for digests, MACs, and digital signatures.
zeroecho.core.util	General-purpose helper classes and utility routines.
zeroecho.logging	Provides lightweight logging utilities and configuration helpers for Java Util Logging (JUL).
zeroecho.sdk.builders	Builders for composing streaming data-content pipelines across core sources and algorithm-specific stages.
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.content.api	Content abstractions for streaming data in the SDK.
zeroecho.sdk.content.builtin	Built-in plain content sources: bytes, strings, files, and passwords.
zeroecho.sdk.content.export	Export helpers and platform deployers for SDK content.
zeroecho.sdk.guard	Multi-recipient envelope for symmetric payloads with pluggable recipients, stateless openers, and a compact header.
zeroecho.sdk.integrations.covert	Helpers for generating pseudo-random cover text using character frequency tables.
zeroecho.sdk.integrations.covert.jpeg	Covert data embedding and extraction using JPEG EXIF metadata.
zeroecho.sdk.integrations.stegano	Steganographic integrations for ZeroEcho SDK.
zeroecho.sdk.io	Stream utilities for SDK pipelines.
zeroecho.sdk.util	Utility helpers for provider setup, key derivation, randomness, encoding, and X.509 handling.