Class AesSpec

java.lang.Object
zeroecho.core.alg.aes.AesSpec
All Implemented Interfaces:
Describable, ContextSpec
public final class AesSpec extends Object implements ContextSpec, Describable
Static configuration for AES encryption and decryption.

An AesSpec captures compile‑time choices for the AES transform: the block mode, padding scheme (CBC only), and—when using GCM—the authentication tag length in bits. It may optionally embed a SymmetricHeaderCodec that governs how runtime parameters (IV/nonce, tag bits, AAD hash) are written to and read from the data stream. No IV/nonce or AAD bytes are stored in this type; those are runtime values exchanged via a Conflux session context.

Design

  • Immutability: instances are immutable and thread‑safe.
  • Validation: GCM requires NOPADDING and a tag length between 96 and 128 bits (inclusive) in 8‑bit increments; non‑GCM modes must not specify a tag length.
  • Header codec: when present, the codec persists IV and GCM parameters in‑band, and can bind AAD via a hash. The cipher context hydrates the runtime context from this header during decryption, and writes it during encryption.
  • Runtime parameters: IV sizes are dictated by mode (12 bytes for GCM; 16 for CBC/CTR) and are generated or required at runtime by the cipher context, not by this spec.
Since:
1.0

  • Method Details

    • builder

      public static AesSpec.Builder builder()
      Returns a new builder with safe defaults (AesSpec.Mode.GCM, AesSpec.Padding.NOPADDING, 128‑bit tag, no header).
      Returns:
      a fresh builder for AesSpec

    • gcm128

      public static AesSpec gcm128(SymmetricHeaderCodec header)
      Creates a GCM specification with a 128‑bit authentication tag and the provided header codec.
      Parameters:
      header - the header codec to embed, or null for none
      Returns:
      a specification for AES/GCM/NOPADDING with a 128‑bit tag

    • cbcPkcs7

      public static AesSpec cbcPkcs7(SymmetricHeaderCodec header)
      Creates a CBC specification using PKCS#7 padding and the provided header.
      Parameters:
      header - the header codec to embed, or null for none
      Returns:
      a specification for AES/CBC/PKCS7Padding

    • ctr

      public static AesSpec ctr(SymmetricHeaderCodec header)
      Creates a CTR specification with no padding and the provided header.
      Parameters:
      header - the header codec to embed, or null for none
      Returns:
      a specification for AES/CTR/NOPADDING

    • mode

      public AesSpec.Mode mode()
      Returns the selected AES mode.

      This value determines IV length expectations and whether AAD and tag length apply (GCM only).

      Returns:
      the block mode used by this specification

    • padding

      public AesSpec.Padding padding()
      Returns the selected padding scheme.

      Relevant only for CBC; GCM and CTR always operate with no padding.

      Returns:
      the padding scheme (never null)

    • tagLenBits

      public int tagLenBits()
      Returns the authentication tag length in bits.

      For GCM, this is one of 96, 104, 112, 120, or 128. For non‑GCM modes, this method returns 0.

      Returns:
      the GCM tag length in bits, or 0 if not applicable

    • header

      public SymmetricHeaderCodec header()
      Returns the embedded header codec, if any.

      When non‑null, the cipher context writes the header during encryption (after the IV is chosen) and reads it during decryption to hydrate the runtime context.

      Returns:
      the header codec, or null if no header is used

    • description

      public String description()
      Produces a compact human‑readable description of this specification, such as "AES-GCM(tag=128)" or "AES-CBC/PKCS7Padding".
      Specified by:
      description in interface Describable
      Returns:
      a descriptive string for diagnostics and logs