Class HmacDataContentBuilder

java.lang.Object
zeroecho.sdk.builders.alg.HmacDataContentBuilder
All Implemented Interfaces:
DataContentBuilder<PlainContent>
public final class HmacDataContentBuilder extends Object implements DataContentBuilder<PlainContent>
HmacDataContentBuilder constructs streaming pipelines that compute or verify HMAC tags while an InputStream is consumed.

Overview

The builder produces PlainContent that either passes the original bytes through while computing or verifying an HMAC trailer, or emits only the tag or a boolean verification result. The HMAC variant is selected via spec(HmacSpec) or convenience methods such as sha256().

Modes and outputs

  • MAC mode: compute an HMAC over the incoming stream and either pass the body through with the trailer stripped or emit the finalized tag in raw, hex, or Base64 form.
  • VERIFY mode: verify an expected HMAC. The expected tag can be provided directly or taken from the input trailer. The output can be pass-through of the body or a textual boolean.

Key handling

Keys may be supplied directly, generated for the configured MAC name, or imported from raw, hex, or Base64 text. If no key material is provided, a default key suitable for the selected MAC is generated.

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 HmacDataContentBuilder builder(ZeroEchoSession session)
      Creates a new builder for constructing HMAC computing or verifying pipelines.

      Example

      PlainContent pc = HmacDataContentBuilder.builder()
    .sha256()
    .emitHexTag()
    .build(true);
      Parameters:
      session - active session used to create cryptographic contexts
      Returns:
      a new HmacDataContentBuilder instance

    • spec

      public HmacSpec spec()
      Returns the currently configured HMAC specification.

      This accessor is intentionally read-only and exists to support safe integrations (for example hybrid-derived key injection) without duplicating the HMAC variant configuration outside of this builder.

      Returns:
      current HMAC spec (never null)
      Since:
      1.0

    • recommendedKeyBits

      public int recommendedKeyBits()
      Returns a recommended HMAC key size (in bits) for the currently configured spec().

      This is a convenience forwarding method to HmacSpec.recommendedKeyBits() and is intended as the default choice for derived-key integrations. Callers that intentionally need a non-default size may override it explicitly.

      Returns:
      recommended key size in bits (positive, multiple of 8)
      Since:
      1.0

    • mac

      public HmacDataContentBuilder mac()
      Switches the builder to MAC mode.
      Returns:
      this builder for chaining

    • verify

      public HmacDataContentBuilder verify()
      Switches the builder to VERIFY mode.
      Returns:
      this builder for chaining

    • spec

      public HmacDataContentBuilder spec(HmacSpec s)
      Sets the HMAC specification to use for this pipeline.
      Parameters:
      s - the HMAC spec; must not be null
      Returns:
      this builder for chaining
      Throws:
      NullPointerException - if s is null

    • sha256

      public HmacDataContentBuilder sha256()
      Selects HmacSHA256.
      Returns:
      this builder for chaining

    • sha384

      public HmacDataContentBuilder sha384()
      Selects HmacSHA384.
      Returns:
      this builder for chaining

    • sha512

      public HmacDataContentBuilder sha512()
      Selects HmacSHA512.
      Returns:
      this builder for chaining

    • withKey

      public HmacDataContentBuilder withKey(SecretKey k)
      Supplies an explicit secret key for the HMAC operation.

      Calling this clears any prior key generation or import configuration.

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

    • generateKey

      public HmacDataContentBuilder generateKey(int bits)
      Requests generation of a new secret key sized for the configured MAC.

      The key is generated for the MAC name returned by HmacSpec.macName().

      Parameters:
      bits - desired key length in bits
      Returns:
      this builder for chaining

    • importKeyRaw

      public HmacDataContentBuilder importKeyRaw(byte[] raw)
      Imports a secret key from raw bytes.

      Calling this clears any prior explicit key or generation request.

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

    • importKeyHex

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

      Calling this clears any prior explicit key or generation request.

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

    • importKeyBase64

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

      Calling this clears any prior explicit key or generation request.

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

    • passThrough

      public HmacDataContentBuilder passThrough()
      Configures the pipeline to pass the input body through unchanged and strip the engine's trailer.
      Returns:
      this builder for chaining

    • emitRawTag

      public HmacDataContentBuilder emitRawTag()
      Configures the pipeline to emit the finalized HMAC tag as raw bytes.

      Switches the mode to HmacDataContentBuilder.Mode.MAC.

      Returns:
      this builder for chaining

    • emitHexTag

      public HmacDataContentBuilder emitHexTag()
      Configures the pipeline to emit the finalized HMAC tag as lowercase hexadecimal text.

      Switches the mode to HmacDataContentBuilder.Mode.MAC.

      Returns:
      this builder for chaining

    • emitBase64Tag

      public HmacDataContentBuilder emitBase64Tag()
      Configures the pipeline to emit the finalized HMAC tag as Base64 text.

      Switches the mode to HmacDataContentBuilder.Mode.MAC.

      Returns:
      this builder for chaining

    • emitVerificationBoolean

      public HmacDataContentBuilder emitVerificationBoolean()
      Configures the pipeline to verify and emit a textual boolean result.

      Switches the mode to HmacDataContentBuilder.Mode.VERIFY.

      Returns:
      this builder for chaining

    • expectedTag

      public HmacDataContentBuilder expectedTag(byte[] raw)
      Supplies the expected HMAC tag as raw bytes for verification.

      Providing a value here clears any prior hex or Base64 expected tag.

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

    • expectedTagHex

      public HmacDataContentBuilder expectedTagHex(String hex)
      Supplies the expected HMAC tag as a hexadecimal string for verification.

      Providing a value here clears any prior raw or Base64 expected tag.

      Parameters:
      hex - the expected tag in hexadecimal; must not be null
      Returns:
      this builder for chaining
      Throws:
      NullPointerException - if hex is null
      IllegalArgumentException - if hex is not valid hexadecimal

    • expectedTagBase64

      public HmacDataContentBuilder expectedTagBase64(String b64)
      Supplies the expected HMAC tag as a Base64 string for verification.

      Providing a value here clears any prior raw or hex expected tag.

      Parameters:
      b64 - the expected tag in Base64; must not be null
      Returns:
      this builder for chaining
      Throws:
      NullPointerException - if b64 is null
      IllegalArgumentException - if b64 is not valid Base64

    • build

      public PlainContent build(boolean ignoredEncryptFlag)
      Builds a digesting or verifying PlainContent pipeline according to the current configuration.

      The boolean parameter is ignored and exists only to satisfy the DataContentBuilder interface. The actual behavior is controlled by mac() or verify() and the selected output.

      Result

      Specified by:
      build in interface DataContentBuilder<PlainContent>
      Parameters:
      ignoredEncryptFlag - unused parameter from the interface
      Returns:
      a PlainContent pipeline performing the configured HMAC operation
      Throws:
      IllegalStateException - if an invalid mode/output combination is selected or key construction fails