Class ChaCha20Poly1305HeaderCodec

java.lang.Object
zeroecho.core.alg.chacha.ChaCha20Poly1305HeaderCodec
All Implemented Interfaces:
SymmetricHeaderCodec
public final class ChaCha20Poly1305HeaderCodec extends Object implements SymmetricHeaderCodec

ChaCha20-Poly1305 streaming header codec

Implements SymmetricHeaderCodec for the ChaCha20-Poly1305 AEAD mode. Encodes a compact header that precedes the ciphertext stream and conveys:
  • a 12-byte nonce (IV) required by ChaCha20-Poly1305, and
  • an optional SHA-256 hash of AAD to assert integrity of externally supplied AAD.

The nonce and AAD are exchanged via the bound CtxInterface using ConfluxKeys.iv(String) and ConfluxKeys.aad(String) keys, respectively. On encryption, the codec reads these values from the context and writes the header. On decryption, it restores the nonce into the context and, when present, verifies the supplied AAD by comparing its hash to the header.

Header layout

 [0..11]  : 12-byte nonce (IV)
 [12]     : 1-byte AAD flag (0 = none, 1 = present)
 [13..44] : 32-byte SHA-256(AAD) if flag == 1

Failure modes

  • Missing/invalid nonce in context when writing the header.
  • AAD expected by header but not provided in context during read.
  • AAD hash mismatch when verifying during read.
Since:
1.0

  • Constructor Details

    • ChaCha20Poly1305HeaderCodec

      public ChaCha20Poly1305HeaderCodec()
      Creates a stateless ChaCha20-Poly1305 stream-header codec.

  • Method Details

    • writeHeader

      public void writeHeader(OutputStream out, CryptoAlgorithm algorithm, CtxInterface ctx) throws IOException
      Writes the ChaCha20-Poly1305 header to the provided stream.

      Reads the 12-byte nonce and optional AAD from ctx. If AAD is non-empty, its SHA-256 is written after a presence flag. Flushes the output upon completion.

      Specified by:
      writeHeader in interface SymmetricHeaderCodec
      Parameters:
      out - destination stream to receive the header
      algorithm - the algorithm instance (used for context key scoping)
      ctx - operation context carrying nonce and optional AAD
      Throws:
      IOException - if the nonce is missing/invalid or I/O fails

    • readHeader

      public InputStream readHeader(InputStream in, CryptoAlgorithm algorithm, CtxInterface ctx) throws IOException
      Reads and validates the ChaCha20-Poly1305 header from the provided stream.

      Restores the 12-byte nonce into ctx. If the header signals AAD presence, computes SHA-256 over the AAD obtained from ctx and verifies it against the header hash.

      Specified by:
      readHeader in interface SymmetricHeaderCodec
      Parameters:
      in - source stream containing the header and subsequent payload
      algorithm - the algorithm instance (used for context key scoping)
      ctx - operation context to populate (nonce) and validate (AAD)
      Returns:
      the same in stream positioned after the header
      Throws:
      IOException - if the header is malformed, AAD is missing when required, the AAD hash mismatches, or I/O fails