Class ChaChaDataContentBuilder

java.lang.Object
zeroecho.sdk.builders.alg.ChaChaDataContentBuilder
All Implemented Interfaces:
DataContentBuilder<DataContent>
public final class ChaChaDataContentBuilder extends Object implements DataContentBuilder<DataContent>
ChaChaDataContentBuilder builds streaming ChaCha20 and ChaCha20-Poly1305 pipelines that encrypt or decrypt as an InputStream is consumed.

Variants

The builder selects between two cipher variants: Supplying both AAD and counter options is a configuration error and results in an IllegalStateException.

Key material

A secret key is resolved in the following order:
  1. Explicit key via withKey(javax.crypto.SecretKey).
  2. Key generation via generateKey() with a default 256-bit spec.
  3. Key import via importKeyRaw(byte[]), importKeyHex(String), or importKeyBase64(String).
  4. Fallback to default 256-bit generation if none of the above is provided.

Context and headers

A runtime CtxInterface can be attached via context(conflux.CtxInterface) to exchange parameters such as nonce, AAD, or counter. When a context is present, the builder writes values under algorithm-specific keys from ConfluxKeys. If a header is requested with withHeader() or a custom SymmetricHeaderCodec is supplied via withHeaderCodec(SymmetricHeaderCodec), a context is required; if none was provided, a temporary one is created internally. A default header codec is chosen based on the variant when no custom codec is set. Encryption generates a 12-byte nonce internally after claiming its single-use context. Headerless decryption may receive a nonce through the decryption-only configuration method.

Usage examples

// 1) ChaCha20 stream encryption with generated key and header
DataContent enc = ChaChaDataContentBuilder.builder()
    .generateKey()
    .withHeader()
    .build(true);

// 2) Headerless ChaCha20-Poly1305 decryption with supplied key, nonce, and AAD
DataContent dec = ChaChaDataContentBuilder.builder()
    .withKey(secretKey)
    .withDecryptionNonce(nonce12)        // 12 bytes
    .withAad("meta".getBytes(StandardCharsets.UTF_8))
    .build(false);

// 3) ChaCha20 stream encryption with explicit counter propagated via context
DataContent enc2 = ChaChaDataContentBuilder.builder()
    .withKey(secretKey)
    .context(ctx)
    .withCounter(7)                      // overrides initialCounter in ctx
    .build(true);

// 4) Import a key from hex and decrypt without headers
DataContent dec2 = ChaChaDataContentBuilder.builder()
    .importKeyHex(hexKey)
    .build(false);

Behavior of build(boolean)

Calling build(true) returns a pipeline that encrypts as the stream is read; build(false) returns a pipeline that decrypts. In stream mode, initialCounter(int) sets the spec's initial counter (default is 1), while withCounter(int) stores an override in the context. In AEAD mode, withAad(byte[]) supplies additional authenticated data.

Thread-safety

Instances are mutable and not thread-safe. Configure and use each builder instance from a single thread.
See Also:

  • Method Details

    • builder

      public static ChaChaDataContentBuilder builder(ZeroEchoSession session)
      Returns a new builder instance for constructing ChaCha20 or ChaCha20-Poly1305 streaming pipelines.

      Examples

      DataContent enc = ChaChaDataContentBuilder.builder()
    .generateKey()
    .withHeader()
    .build(true);
      Parameters:
      session - active session used to create cryptographic contexts
      Returns:
      a new ChaChaDataContentBuilder

    • withKey

      public ChaChaDataContentBuilder withKey(SecretKey k)
      Sets an explicit secret key to use for encryption or decryption.

      Supplying a key clears any previously configured key generation or import specification.

      Parameters:
      k - the secret key to use; must not be null
      Returns:
      this builder for chaining
      Throws:
      NullPointerException - if k is null

    • generateKey

      public ChaChaDataContentBuilder generateKey()
      Requests generation of a fresh ChaCha key using a default 256-bit specification.

      Enabling key generation clears any previously configured explicit key or import specification.

      Returns:
      this builder for chaining

    • importKeyRaw

      public ChaChaDataContentBuilder importKeyRaw(byte[] raw)
      Imports a secret key from raw key bytes appropriate for the selected ChaCha variant.

      Supplying an import spec clears any previously configured explicit key or key generation request.

      Parameters:
      raw - the raw key bytes; must not be null
      Returns:
      this builder for chaining
      Throws:
      NullPointerException - if raw is null
      IllegalArgumentException - if raw is not a valid key length

    • importKeyHex

      public ChaChaDataContentBuilder importKeyHex(String hex)
      Imports a secret key from a hexadecimal string.

      Supplying an import spec clears any previously configured explicit key or key generation request.

      Parameters:
      hex - the hex-encoded key; must not be null
      Returns:
      this builder for chaining
      Throws:
      NullPointerException - if hex is null
      IllegalArgumentException - if hex is not valid hexadecimal or not a valid key length

    • importKeyBase64

      public ChaChaDataContentBuilder importKeyBase64(String b64)
      Imports a secret key from a Base64 string.

      Supplying an import spec clears any previously configured explicit key or key generation request.

      Parameters:
      b64 - the Base64-encoded key; must not be null
      Returns:
      this builder for chaining
      Throws:
      NullPointerException - if b64 is null
      IllegalArgumentException - if b64 is not valid Base64 or not a valid key length

    • context

      public ChaChaDataContentBuilder context(CtxInterface ctx)
      Sets an optional runtime context used to read or write parameters such as nonce, AAD, or counter.

      When a header is requested and no context is provided, a temporary context is created internally.

      Parameters:
      ctx - the context instance to use; may be null
      Returns:
      this builder for chaining

    • withDecryptionNonce

      public ChaChaDataContentBuilder withDecryptionNonce(byte[] nonce)
      Sets an out-of-band nonce for headerless decryption.

      For ChaCha20 and ChaCha20-Poly1305 this must be 12 bytes. The value is rejected when building an encrypting pipeline because encryption always generates its nonce internally.

      Parameters:
      nonce - the nonce bytes; must not be null
      Returns:
      this builder for chaining
      Throws:
      NullPointerException - if nonce is null

    • initialCounter

      public ChaChaDataContentBuilder initialCounter(int c)
      Sets the initial counter for ChaCha20 stream mode.

      Calling this method selects stream mode unless AEAD is selected via withAad(byte[]). The default initial counter is 1.

      Parameters:
      c - the initial counter value
      Returns:
      this builder for chaining

    • withCounter

      public ChaChaDataContentBuilder withCounter(int c)
      Sets an explicit counter override to be propagated through the context.

      This value is stored under an algorithm-specific key in the provided context and overrides initialCounter(int) if present.

      Parameters:
      c - the counter value to use
      Returns:
      this builder for chaining

    • withAad

      public ChaChaDataContentBuilder withAad(byte[] aad)
      Sets additional authenticated data for ChaCha20-Poly1305.

      Providing AAD selects AEAD mode. Passing null or an empty array leaves the decision to other configuration such as stream counters.

      Parameters:
      aad - the AAD bytes; may be null
      Returns:
      this builder for chaining

    • withHeaderCodec

      public ChaChaDataContentBuilder withHeaderCodec(SymmetricHeaderCodec codec)
      Sets a custom header codec to emit or parse algorithm headers.

      Supplying a codec clears the implicit header request flag. If no codec is supplied but a header is requested via withHeader(), a default is chosen based on the selected variant.

      Parameters:
      codec - the header codec to use; may be null to clear
      Returns:
      this builder for chaining

    • withHeader

      public ChaChaDataContentBuilder withHeader()
      Requests that a header be emitted (on encrypt) or parsed (on decrypt).

      If no custom codec is set, a default codec is chosen depending on whether stream or AEAD mode is inferred.

      Returns:
      this builder for chaining

    • build

      public DataContent build(boolean encrypt)
      Builds a streaming encryption or decryption pipeline according to the current configuration.

      AEAD mode is selected if AAD is provided via withAad(byte[]), using the algorithm id "CHACHA20-POLY1305". Otherwise stream mode is used, with the algorithm id "CHACHA20".

      The key is resolved in this order: explicit key, key generation spec, key import spec, default 256-bit generation.

      If a header is requested and no context is provided, a temporary context is created. Encryption generates its nonce internally; a configured decryption nonce is rejected for encrypting pipelines. 

      DataContent enc = ChaChaDataContentBuilder.builder()
    .generateKey()
    .withHeader()
    .build(true);
      Specified by:
      build in interface DataContentBuilder<DataContent>
      Parameters:
      encrypt - true to build an encrypting pipeline, false for a decrypting pipeline
      Returns:
      a DataContent instance that performs the requested operation when its stream is consumed
      Throws:
      IllegalStateException - if conflicting configuration is detected or key construction fails