Package zeroecho.sdk.guard

Class PasswordRecipient

java.lang.Object

zeroecho.sdk.guard.PasswordRecipient

All Implemented Interfaces:

Recipient

public final class PasswordRecipient
extends Object
implements Recipient

Password recipient that derives a KEK via PBKDF2(HMAC-SHA-256) and wraps the CEK with AES-GCM.

Constructor Summary

Constructors

Constructor	Description
PasswordRecipient(char[] password, int iterations, int saltLen, int kekBytes)	Creates a password-based recipient.
PasswordRecipient(char[] password, int iterations, int saltLen, int kekBytes, boolean decoy)	Creates a password-based recipient that derives a key-encryption key (KEK) using PBKDF2.

Method Summary

Modifier and Type	Method	Description
byte[]	buildRecipientEntry(byte[] cek)	Builds the recipient entry blob for this password recipient.
boolean	decoy()	Returns whether this recipient entry is marked as a decoy.
String	id()	Returns the recipient entry identifier used in the header.

Methods inherited from class java.lang.Object

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

Constructor Details

PasswordRecipient

public PasswordRecipient(char[] password,
 int iterations,
 int saltLen,
 int kekBytes)

Creates a password-based recipient.

Parameters:

password - the password; the caller should clear the array after use

iterations - PBKDF2 iteration count

saltLen - salt length in bytes

kekBytes - derived KEK length in bytes

Throws:

NullPointerException - if password is null

PasswordRecipient

public PasswordRecipient(char[] password,
 int iterations,
 int saltLen,
 int kekBytes,
 boolean decoy)

Creates a password-based recipient that derives a key-encryption key (KEK) using PBKDF2.

The supplied password is expanded with PBKDF2 using the provided iteration count and a randomly generated salt of the specified length. The result is a KEK of the requested size in bytes, which is then used to wrap the content-encryption key (CEK) for this recipient. A recipient may also be marked as a decoy to obscure the actual number of usable recipients.

Security considerations

• The caller should clear the password array after constructing the recipient to minimize exposure in memory.
• Choose an iteration count appropriate to the target platform to resist brute-force attacks.
• Decoy recipients increase confidentiality by hiding the number of real recipients but cannot successfully unwrap the CEK.

Parameters:

password - the password used as input to PBKDF2; must not be null

iterations - the PBKDF2 iteration count

saltLen - length of the random salt (in bytes)

kekBytes - desired length of the derived KEK (in bytes)

decoy - true if this is a decoy recipient (fake entry that cannot unwrap a CEK); false if it is a real recipient

Throws:

NullPointerException - if password is null

Method Details

id

public String id()

Returns the recipient entry identifier used in the header.

Specified by:

id in interface Recipient

Returns:

"PWD:PBKDF2-SHA256:GCM-WRAP"

buildRecipientEntry

public byte[] buildRecipientEntry(byte[] cek)
                           throws GeneralSecurityException,
IOException

Builds the recipient entry blob for this password recipient.

Specified by:

buildRecipientEntry in interface Recipient

Parameters:

cek - the CEK to wrap

Returns:

a blob containing pack7(iter) || salt || wrapIv || wrappedCEK

Throws:

GeneralSecurityException - if PBKDF2 or AES-GCM fails

IOException - if blob assembly fails

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