Interface RecipientOpener

All Superinterfaces:
AutoCloseable
All Known Implementing Classes:
EncCtxOpener, KemCtxOpener, PasswordOpener
public interface RecipientOpener extends AutoCloseable
RecipientOpener attempts to recover a content-encryption key (CEK) from a single recipient entry during decryption.

Behavior

Implementations examine the envelope header fields for one recipient, optionally use the entryId as a hint, and try to derive or unwrap the CEK from the opaque entryBlob using the provided UnlockMaterial. In hardened configurations the entryId may be an empty string; openers should still attempt a best-effort decode based on the blob format and the supplied material.

Return and failure semantics:

  • Return a non-null byte array containing the CEK on success.
  • Return null if this opener is clearly not applicable to the entry (for example, mismatched id or unsupported blob format).
  • Throw GeneralSecurityException when the opener considers the entry applicable but the cryptographic attempt fails (for example, authentication failure, padding error, malformed ciphertext, or key mismatch).
  • Throw IOException for structural or I/O errors while parsing the blob (for example, truncated data).

Implementation notes:

  • Openers are reusable across every recipient entry in one envelope. Implementations that need cryptographic contexts must create a fresh context for each applicable attempt.
  • Openers must not retain references to UnlockMaterial or the returned CEK.
  • Do not log sensitive values, and avoid timing-sensitive distinctions beyond what the caller needs to continue scanning other entries.

Typical scan loop: 

for (RecipientOpener opener : openers) {
    try {
        byte[] cek = opener.tryOpen(entryId, entryBlob, material);
        if (cek != null) {
            // success; use CEK and stop scanning
            break;
        }
    } catch (javax.crypto.AEADBadTagException wrongKeyOrPassword) {
        // applicable but authentication failed; continue scanning others
    } catch (GeneralSecurityException ignore) {
        // not applicable or other crypto failure; continue scanning
    }
}

  • Method Summary

    Modifier and Type
    Method
    Description
    default void
    close()
    Releases opener-owned resources that were not consumed.
    byte[]
    tryOpen(String entryId, byte[] entryBlob, UnlockMaterial material)
    Tries to recover the content-encryption key from the supplied recipient entry.

  • Method Details

    • tryOpen

      byte[] tryOpen(String entryId, byte[] entryBlob, UnlockMaterial material) throws GeneralSecurityException, IOException
      Tries to recover the content-encryption key from the supplied recipient entry.
      Parameters:
      entryId - identifier string written by the sender; may be empty when labels are suppressed; used only as a routing hint
      entryBlob - opaque bytes of the recipient entry produced by the matching Recipient; never null
      material - unlocking material to use (for example, a private key or a password); never null
      Returns:
      a newly allocated byte array containing the recovered CEK, or null if this opener is not applicable
      Throws:
      GeneralSecurityException - if the entry appears applicable but cryptographic verification or unwrapping fails
      IOException - if parsing the entry blob fails due to structural errors or truncated data

    • close

      default void close() throws IOException
      Releases opener-owned resources that were not consumed.
      Specified by:
      close in interface AutoCloseable
      Throws:
      IOException - if cleanup fails