Class KemCtxRecipient

java.lang.Object
zeroecho.sdk.guard.KemCtxRecipient
All Implemented Interfaces:
AutoCloseable, Recipient
public final class KemCtxRecipient extends Object implements Recipient, AutoCloseable
Recipient implementation that derives a key-encryption key (KEK) via a KemContext encapsulation and uses it to wrap a content-encryption key (CEK).

The workflow performed by this class is:

  1. Encapsulate with the given KemContext to obtain a ciphertext and a shared secret.
  2. Derive a KEK from the shared secret using HKDF-SHA256 with a random salt and an info string bound to the algorithm identifier.
  3. Generate a fresh IV and wrap the CEK under AES-GCM with the derived KEK.
  4. Serialize the components (KEM ciphertext, salt, IV, wrapped CEK) into a single byte array suitable for inclusion in a recipient entry.

Thread-safety

This class is not thread-safe. Each instance binds to a single KemContext and must not be reused concurrently.
Since:
1.0

  • Constructor Summary

    Constructors
    Constructor
    Description
    KemCtxRecipient(KemContext ctx, int kekBytes, int saltLen)
    Constructs a recipient that uses the given KEM context and parameters.
    KemCtxRecipient(KemContext ctx, int kekBytes, int saltLen, boolean decoy)
    Constructs a recipient that wraps content-encryption keys (CEKs) using the given KEM context and HKDF-based key derivation parameters.

  • Method Summary

    Modifier and Type
    Method
    Description
    byte[]
    buildRecipientEntry(byte[] cek)
    Builds a recipient entry for the given content-encryption key (CEK).
    void
    close()
    Closes the owned KEM context.
    boolean
    decoy()
    Returns whether this recipient entry is marked as a decoy.
    String
    id()
    Returns the identifier string for this recipient mechanism.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • KemCtxRecipient

      public KemCtxRecipient(KemContext ctx, int kekBytes, int saltLen)
      Constructs a recipient that uses the given KEM context and parameters.
      Parameters:
      ctx - the KEM context providing encapsulation
      kekBytes - KEK length; exactly 16 or 32 bytes
      saltLen - length of the random salt to apply during HKDF
      Throws:
      NullPointerException - if ctx is null
      IllegalArgumentException - if kekBytes is not exactly 16 or 32

    • KemCtxRecipient

      public KemCtxRecipient(KemContext ctx, int kekBytes, int saltLen, boolean decoy)
      Constructs a recipient that wraps content-encryption keys (CEKs) using the given KEM context and HKDF-based key derivation parameters.

      The KEM context performs encapsulation to derive a shared secret, which is expanded with HKDF into key-encryption key (KEK) material. The KEK is then used to wrap the CEK for this recipient. A recipient may also be flagged as a decoy to obscure the actual number of usable recipients.

      Parameters:
      ctx - the KEM context responsible for performing encapsulation; must not be null
      kekBytes - KEK length; exactly 16 or 32 bytes
      saltLen - length in bytes of the random salt applied during HKDF
      decoy - true if this recipient is a decoy (fake entry that cannot unwrap a CEK); false if it is a real recipient
      Throws:
      NullPointerException - if ctx is null
      IllegalArgumentException - if kekBytes is not exactly 16 or 32

  • Method Details

    • id

      public String id()
      Returns the identifier string for this recipient mechanism.

      The format is "KEM:<algoId>:GCM-WRAP" where <algoId> is taken from the underlying KemContext algorithm.

      Specified by:
      id in interface Recipient
      Returns:
      identifier string for this recipient type

    • buildRecipientEntry

      public byte[] buildRecipientEntry(byte[] cek) throws GeneralSecurityException, IOException
      Builds a recipient entry for the given content-encryption key (CEK).

      Encapsulates with the KEM context, derives a KEK, wraps the CEK, and serializes the structure into a binary entry. The returned value contains all material required for the recipient to later decapsulate and unwrap.

      Specified by:
      buildRecipientEntry in interface Recipient
      Parameters:
      cek - the content-encryption key to be wrapped
      Returns:
      encoded recipient entry containing encapsulation, salt, IV, and wrapped CEK
      Throws:
      GeneralSecurityException - if encapsulation, KDF, or wrapping fails
      IOException - if an I/O error occurs during encoding

    • decoy

      public boolean decoy()
      Returns whether this recipient entry is marked as a decoy.

      A decoy recipient is syntactically valid but intentionally unusable for recovering the content-encryption key (CEK). Such entries are included to conceal the number and identity of real recipients within a multi-recipient envelope.

      Specified by:
      decoy in interface Recipient
      Returns:
      true if this recipient is a decoy (fake recipient that cannot unwrap a CEK); false if it is a real recipient

    • close

      public void close() throws IOException
      Closes the owned KEM context.
      Specified by:
      close in interface AutoCloseable
      Throws:
      IOException - if context cleanup fails