Package zeroecho.core.alg.chacha

package zeroecho.core.alg.chacha
ChaCha algorithm implementation and runtime wiring.

This package provides the ChaCha capability set for the core layer, including the stream cipher ChaCha20 and the AEAD construction ChaCha20-Poly1305. The module contains algorithm descriptors, streaming cipher contexts, configuration specifications, optional header codecs for runtime parameters, and symmetric key import/generation specifications. Key import specifications are destroyable. The design favors safe defaults (12-byte nonces, 128-bit AEAD tag), explicit role-to-context binding, and a clear separation between static configuration and per-operation parameters.

Components

  • Algorithm descriptors: ChaChaAlgorithm registers ENCRYPT and DECRYPT roles for the ChaCha20 stream cipher; ChaCha20Poly1305Algorithm registers the AEAD counterpart. Both share a common base that wires symmetric key builders for generation and import.
  • Streaming contexts: ChaChaCipherContext and ChaCha20Poly1305CipherContext implement InputStream-to- InputStream transforms. The abstract parent AbstractChaChaCipherContext handles nonce lifecycle, optional header injection/parsing, and construction of a pull-based cipher stream.
  • Static configuration (specs): ChaChaSpec captures the initial counter and optional header codec for ChaCha20; ChaCha20Poly1305Spec binds the optional header codec for AEAD. The sealed marker ChaChaBaseSpec unifies both.
  • Header codecs (optional): ChaChaHeaderCodec writes/reads a compact header carrying the 12-byte nonce and a packed stream counter; ChaCha20Poly1305HeaderCodec writes/reads the 12-byte nonce and an optional SHA-256 of AAD to assert out-of-band AAD integrity.
  • Key specifications: ChaChaKeyGenSpec defines parameters for generating 256-bit ChaCha keys; ChaChaKeyImportSpec wraps externally supplied raw keys. Generation and import are registered by the algorithm base.

Runtime parameters and context exchange

Streaming contexts exchange ephemeral parameters through a Conflux session context using namespaced keys. Each ChaCha20 and ChaCha20-Poly1305 encryption context is single-use: after an atomic claim it generates a fresh 12-byte nonce and stores it back into the session. On decryption the nonce must already be present and have the correct length. ChaCha20 also uses an initial counter sourced from ChaChaSpec and optionally overridden by the session context. When a header codec is configured and a session context is set, encryption prepends a minimal header and decryption reads it first to hydrate the session before initializing the cipher.

Safety and validation

  • Nonce lifecycle: Each encryption context is single-use and generates its nonce internally after an atomic operation claim. Decryption consumes the encoded or out-of-band nonce and fails if it is missing or has an unexpected size.
  • Counter policy (ChaCha20): The default initial counter is 1. A context may override the spec value through the session key dedicated to counter exchange; consistency is enforced at attach time.
  • AEAD tag and AAD (ChaCha20-Poly1305): The effective tag length is 128 bits. If AAD is supplied, it is included in authentication; when enabled, the header codec can store SHA-256(AAD) to verify that decrypt-time AAD matches encrypt-time AAD.

Thread-safety

  • Algorithm descriptors are immutable and safe to share.
  • Streaming contexts are stateful and not thread-safe.
Since:
1.0