Package zeroecho.core

package zeroecho.core
Core cryptography engine and registry for ZeroEcho.

This package defines the low-level algorithm model, discovery and registry surface, capability descriptors, key usage taxonomy, and a small set of helpers required by concrete cryptographic algorithms. It is intentionally minimal and policy-agnostic so that higher layers can compose flows without duplicating concerns defined here.

Relationship to the overall library

The core provides the foundation on which the higher-level SDK composes developer-facing workflows. The intent is clear separation of responsibilities: the core focuses on algorithms and correctness, while the SDK focuses on composition and ergonomics.

Algorithm model

Algorithms are declared by implementing CryptoAlgorithm and exposing canonical identifiers, human-readable names, provider names, priorities, role bindings, capabilities, and key builders. Roles are enumerated by KeyUsage and may be grouped by AlgorithmFamily. Each role binding specifies the context to be created for that role, the accepted key type, an optional specification object, and a factory used to create the context instance. Capabilities are advertised through CryptoAlgorithm.listCapabilities() and described by immutable Capability descriptors.

Discovery and registry

Algorithms are discovered through standard Java provider mechanisms and indexed by canonical identifier. The facade CryptoAlgorithms offers:

  • Lookup of algorithms by identifier and family.
  • Creation of role-specific contexts using supplied keys and optional specifications.
  • Enumeration utilities for tooling and documentation.

Selection and catalogs

Utility types such as CatalogSelector assist with filtering available algorithms by family and required roles. For documentation, validation, or export, CryptoCatalog can build a snapshot of the registry and serialize metadata for external consumers.

Transient parameters and sentinels

Algorithms that exchange ephemeral parameters at runtime can use typed keys from ConfluxKeys. When an API requires a key reference but no secret exists, NullKey.INSTANCE can be supplied as a sentinel. Symmetric algorithms that need to prepend or parse a compact header for IVs, tag sizes, or other runtime fields may implement the optional SPI SymmetricHeaderCodec.

Design principles

  • Stratification: the core concentrates on algorithms and correctness; higher layers provide composition.
  • Composability: predictable, chainable behavior across contexts and builders.
  • Extensibility: new algorithms, formats, and flows can be added with minimal impact.
  • Safety: explicit roles and clear intent around key usage and algorithm capabilities.
Since:
1.0