Package zeroecho.core.alg.aes

package zeroecho.core.alg.aes
AES algorithm implementation and runtime wiring.

This package provides the AES capability set for the core layer, including the algorithm descriptor, a streaming cipher context for GCM / CBC / CTR, static configuration, a minimal header codec for runtime parameters, and key import/generation specifications. The design favors safe defaults (GCM with a 128-bit tag), explicit role-to-context binding, and clear separation between static configuration and per-operation parameters.

Components

  • Algorithm descriptor: AesAlgorithm registers ENCRYPT and DECRYPT roles, installs default specifications, and exposes symmetric key builders for generation and import. Capabilities are published for discovery by higher layers.
  • Streaming context: AesCipherContext implements the runtime transform over InputStream, handling IV creation and validation, optional AAD, tag length (GCM), and mode-specific initialization.
  • Static configuration: AesSpec captures compile-time choices (mode, padding, tag length for GCM) and may embed a header codec used by the context to persist runtime parameters in-band.
  • Header codec: AesHeaderCodec writes/reads a compact header containing IV, a tag-length hint for GCM, and an optional AAD hash used to verify that decrypt-time AAD matches encrypt-time AAD.
  • Key specifications: AesKeyGenSpec defines key-size parameters for generation, and AesKeyImportSpec wraps existing AES keys supplied as raw bytes, hex, or Base64.

Runtime parameters and context exchange

The streaming context exchanges ephemeral parameters (IV/nonce, GCM tag bits, and optional AAD) via a Conflux session context. When a header codec is present and a session context is set, encryption prepends a minimal header and decryption reads it first to hydrate the session context before initializing the cipher.

Safety and validation

  • GCM requires no padding and a tag length between 96 and 128 bits in 8-bit steps; non-GCM modes must not specify a tag length.
  • IV length is enforced by mode (12 bytes for GCM; 16 bytes for CBC/CTR), and decryption fails if IV is missing or has an unexpected size.
  • When an AAD hash is present in the header, decryption enforces consistency with the caller-supplied AAD.

Thread-safety

  • Algorithm descriptors are immutable and safe to share.
  • Streaming contexts are stateful and not thread-safe.
Since:
1.0
  • Class
    Description
    AesAlgorithm
    AES algorithm registration and capability wiring.
    AesCipherContext
    Streaming AES cipher context for GCM / CBC / CTR.
    AesHeaderCodec
    Minimal AES header codec that persists runtime parameters only:
    AesKeyGenSpec
    Key generation parameters for AES.
    AesKeyImportSpec
    Specification for importing an existing AES key.
    AesSpec
    Static configuration for AES encryption and decryption.
    AesSpec.Builder
    Builder for AesSpec.
    AesSpec.Mode
    AES block modes supported by this implementation.
    AesSpec.Padding
    Padding schemes for CBC mode.