Interface Recipient

All Known Implementing Classes:
EncCtxRecipient, KemCtxRecipient, PasswordRecipient
public interface Recipient
Recipient describes how to encode a single recipient entry that can recover a content-encryption key (CEK) during decryption.

Responsibilities

Implementations provide a stable identifier and produce an opaque binary blob that contains everything the matching RecipientOpener needs to recover the CEK (for example, KEM ciphertext, salts, nonces, or wrapped CEK bytes). The multi-recipient envelope writes the identifier and a length-prefixed copy of the blob into its header.

Typical usage

// RSA-OAEP recipient; the header will contain the id and the RSA-wrapped CEK
Recipient r = new MultiRecipientDataSourceBuilder.RsaOaepRecipient(rsaPublicKey);
byte[] entryBlob = r.buildRecipientEntry(cek);

  • Method Summary

    Modifier and Type
    Method
    Description
    byte[]
    buildRecipientEntry(byte[] cek)
    Builds the binary recipient entry for this recipient and the provided CEK.
    boolean
    decoy()
    Indicates whether this recipient entry is a decoy (fake recipient).
    String
    id()
    Returns a stable, self-describing identifier for this recipient entry.

  • Method Details

    • decoy

      boolean decoy()
      Indicates whether this recipient entry is a decoy (fake recipient).

      A decoy recipient is included in the envelope to obscure the actual number and identity of real recipients. Its entry is syntactically valid but intentionally unusable for recovering the content-encryption key (CEK).

      Security considerations

      • Decoys prevent traffic analysis from revealing how many legitimate recipients are present.
      • They are indistinguishable from real recipients to outsiders until a matching RecipientOpener attempts decryption and fails.
      • Applications should balance the number of decoys against performance and bandwidth overhead.
      Returns:
      true if this entry is a decoy and cannot be used to recover the CEK; false if it is a real recipient entry

    • id

      String id()
      Returns a stable, self-describing identifier for this recipient entry.

      The identifier is written as UTF-8 into the envelope header and allows fast routing to a suitable RecipientOpener (for example, "RSA:OAEP-SHA256", "KEM:ML-KEM:GCM-WRAP"). When the envelope is configured to suppress labels for hardening, it may write an empty string in place of this value; implementations should still return their normal identifier here.

      Returns:
      non-null identifier string used in the envelope header; may be empty only when the caller chooses to suppress labels

    • buildRecipientEntry

      byte[] buildRecipientEntry(byte[] cek) throws GeneralSecurityException, IOException
      Builds the binary recipient entry for this recipient and the provided CEK.

      The returned blob is an opaque byte array that the matching RecipientOpener can parse and use to recover the CEK. Implementations must not modify or retain the cek array; copy it if needed. The multi-recipient envelope is responsible for framing and length-prefixing, so the blob itself must not include additional length headers.

      Parameters:
      cek - the content-encryption key to protect for this recipient; never null
      Returns:
      an opaque blob encoding the data required to recover cek for this recipient
      Throws:
      GeneralSecurityException - if a cryptographic operation fails (for example, KEM, RSA-OAEP, or AEAD wrap)
      IOException - if serialization of the entry blob fails