Class AesDataContentBuilder

java.lang.Object
zeroecho.sdk.builders.alg.AesDataContentBuilder
All Implemented Interfaces:
DataContentBuilder<DataContent>
public final class AesDataContentBuilder extends Object implements DataContentBuilder<DataContent>
Fluent builder that exposes AES as a DataContent in pull‑mode.

This is the simplest way to integrate AES into pipelines. Supply the key with withKey(javax.crypto.SecretKey), choose a mode (e.g., modeGcm(int)), optionally install a header codec via withHeader(), and call build(boolean) for encryption (true) or decryption (false). Connect your upstream source with DataContent.setInput(zeroecho.sdk.content.api.DataContent) and consume the resulting InputStream.

Examples

// Encrypt (pull-mode)
DataContent enc = AesDataContentBuilder.builder()
    .withKey(secret)
    .modeGcm(128)
    .withHeader()
    .build(true);
enc.setInput(PlainFileBuilder.ofPath(inPath).build());
try (InputStream s = enc.getStream()) { s.transferTo(Files.newOutputStream(ctPath)); }

// Decrypt (pull-mode)
DataContent dec = AesDataContentBuilder.builder()
    .withKey(secret)
    .modeGcm(128)
    .withHeader()
    .build(false);
dec.setInput(PlainFileBuilder.ofPath(ctPath).build());
try (InputStream s = dec.getStream()) { s.transferTo(Files.newOutputStream(ptPath)); }

Runtime parameters

Optional AAD can be provided via withAad(byte[]). Encryption always generates its IV internally. Headerless decryption may receive an out-of-band IV through withDecryptionIv(byte[]); that configuration is rejected when building an encrypting pipeline. For GCM, AAD defaults to empty.

Thread‑safety

The builder is not thread‑safe. Built DataContent instances are independent.
Since:
1.0

  • Method Details

    • builder

      public static AesDataContentBuilder builder(ZeroEchoSession session)
      Creates a new AES builder with default spec (GCM/128, no header) and no key selected. Use withKey(SecretKey) (recommended), or import/generate a key, then select a mode.
      Parameters:
      session - active session used to create cryptographic contexts
      Returns:
      a new builder instance

    • withKey

      public AesDataContentBuilder withKey(SecretKey k)
      Sets the key to use. Overrides any previous generate/import choice.
      Parameters:
      k - the AES SecretKey; must be 128/192/256-bit
      Returns:
      this builder
      Throws:
      NullPointerException - if k is null

    • generateKey

      public AesDataContentBuilder generateKey(int bits)
      Requests generation of a fresh AES key of the given size.

      Note: prefer withKey(SecretKey) for pipelines that need predictable key reuse across encrypt/decrypt runs.

      Parameters:
      bits - 128, 192, or 256
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if size is invalid

    • importKeyRaw

      public AesDataContentBuilder importKeyRaw(byte[] raw)
      Imports a raw AES key (16/24/32 bytes).
      Parameters:
      raw - key material; copied defensively
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if length is not 16/24/32

    • importKeyHex

      public AesDataContentBuilder importKeyHex(String hex)
      Imports a hex‑encoded AES key (32/48/64 hex chars).
      Parameters:
      hex - hex string; not null
      Returns:
      this builder
      Throws:
      NullPointerException - if hex is null
      IllegalArgumentException - if the decoded length is not 16/24/32

    • importKeyBase64

      public AesDataContentBuilder importKeyBase64(String b64)
      Imports a Base64‑encoded AES key (no padding required).
      Parameters:
      b64 - Base64 text; not null
      Returns:
      this builder
      Throws:
      NullPointerException - if b64 is null
      IllegalArgumentException - if the decoded length is not 16/24/32

    • spec

      public AesDataContentBuilder spec(AesSpec s)
      Copies mode/padding/tagBits/header from a fully built AesSpec.
      Parameters:
      s - the spec to apply
      Returns:
      this builder
      Throws:
      NullPointerException - if s is null

    • modeGcm

      public AesDataContentBuilder modeGcm(int tagBits)
      Selects GCM and sets the authentication tag length in bits.
      Parameters:
      tagBits - 96..128 (step 8)
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if tagBits is out of range

    • modeCtr

      public AesDataContentBuilder modeCtr()
      Selects CTR with NOPADDING. Pair with a MAC if integrity is required.
      Returns:
      this builder

    • modeCbcPkcs5

      public AesDataContentBuilder modeCbcPkcs5()
      Selects CBC/PKCS5PADDING.
      Returns:
      this builder

    • modeCbcNoPadding

      public AesDataContentBuilder modeCbcNoPadding()
      Selects CBC/NOPADDING. The plaintext length must be a multiple of the block size.
      Returns:
      this builder

    • withDecryptionIv

      public AesDataContentBuilder withDecryptionIv(byte[] iv)
      Supplies an out-of-band IV for decryption without an encoded header.
      Parameters:
      iv - the IV (12 bytes for GCM, 16 bytes for CBC/CTR)
      Returns:
      this builder
      Throws:
      NullPointerException - if iv is null

    • withAad

      public AesDataContentBuilder withAad(byte[] aad)
      Supplies Additional Authenticated Data (GCM). AAD is not encrypted; it is bound to the ciphertext. If a header is used, only a SHA‑256 hash of AAD is written.
      Parameters:
      aad - AAD bytes (may be empty)
      Returns:
      this builder

    • withHeaderCodec

      public AesDataContentBuilder withHeaderCodec(SymmetricHeaderCodec codec)
      Installs a specific header codec into the spec so IV/tagBits/AAD hash can be persisted in‑band.
      Parameters:
      codec - the codec to use (e.g., AesHeaderCodec)
      Returns:
      this builder

    • withHeader

      public AesDataContentBuilder withHeader()
      Convenience for withHeaderCodec(SymmetricHeaderCodec) using AesHeaderCodec.
      Returns:
      this builder

    • context

      public AesDataContentBuilder context(CtxInterface ctx)
      Provides a Conflux session context for exchanging IV/AAD/tagBits and enabling header I/O. When null, no context features are used and no header is written/read.
      Parameters:
      ctx - the context, or null
      Returns:
      this builder

    • build

      public DataContent build(boolean encrypt)
      Builds an encrypting or decrypting DataContent.
      • Resolves the key from withKey(SecretKey) or the selected generate/import spec.
      • Finalizes AesSpec (injecting the header if configured).
      • Propagates a decryption IV and AAD into the context when supplied.
      Specified by:
      build in interface DataContentBuilder<DataContent>
      Parameters:
      encrypt - true for encryption; false for decryption
      Returns:
      a DataContent that transforms its upstream stream
      Throws:
      IllegalStateException - on key construction errors or provider misconfiguration

    • generatedKey

      public SecretKey generatedKey()
      Returns the generated secret key associated with this instance.

      The value is typically produced during a key generation process and stored internally for later retrieval. The returned reference is the actual SecretKey object; callers should avoid modifying or exposing it unnecessarily to preserve security.

      Returns:
      the generated SecretKey, or null if no key has been generated