iaik.cms

Class PasswordRecipientInfo

java.lang.Object

iaik.cms.RecipientInfo

iaik.cms.PasswordRecipientInfo

All Implemented Interfaces:

ASN1Type

public class PasswordRecipientInfo
extends RecipientInfo

This class implements the CMS PasswordRecipientInfo type.

The CMS Cryptographic Message Syntax specifies the PasswordRecipientInfo type as RecipientInfo choice for collecting all recipient-related information about some particular recipient a CMS EnvelopedData or CMS AuthenticatedData object shall be sent to when the recipient has a secret key to be used for encrypting the secret content-encryption key:

 PasswordRecipientInfo ::= SEQUENCE {
    version                   CMSVersion, -- always set 0
    keyDerivationAlgorithm [0] KeyDerivationAlgorithmIdentifier OPTIONAL,
    keyEncryptionAlgorithm    KeyEncryptionAlgorithmIdentifier,
    encryptedKey              EncryptedKey
  }
 

 EncryptedKey ::= OCTET STRING
 

 KeyDerivationAlgorithmIdentifier ::= AlgorithmIdentifier
 KeyEncryptionAlgorithmIdentifier ::= AlgorithmIdentifier {{ KeyEncryptionAlgorithms }}
 KeyEncryptionAlgorithms ALGORITHM ::= {
  { OID id-alg-PWRI-KEK PARMS
    AlgorithmIdentifier {{ PWRIAlgorithms }} },
  ...
  }
 

The keyDerivationAlgorithm field identifies the key-derivation algorithm, and any associated parameters, used to derive the KEK from the user-supplied password. If this field is absent, the KEK is supplied from an external source, for example a crypto token such as a smart card. The keyEncryptionAlgorithm field identifies the key-encryption algorithm and any associated parameters, used to encrypt the CEK with the KEK

This class provides several constructors and methods for creating a PasswordRecipientInfo object, obtaining the component values, and encrypting (respectively decrypting) the content-encryption key.

The following example shows the typical usage for including a PasswordRecipientInfo into a EnvelopedData object, encoding it, decoding it at the recipient´s side and decrypt the content (we use the stream-based EnvelopedData implementation for this sample):

 // the password (presumably queried from the user):
 SecureStringBuffer password = ...;
 // use PBKDF2 as key derivation function for deriving the KEK from a password:
 AlgorithmID keyDerivationAlgorithm = AlgorithmID.pbkdf2;
 // get parameters for deriving the key
 AlgorithmParameters derivationParameters = new PBEKeyAndParameterSpec(password, salt, nIterations, kekLengthInBytes);
 // use AES-192 for encrypting (wrapping) the content encryption key:
 AlgorithmID kekEncryptionAlgorithm = AlgorithmID.aes_192_CBC;
 // create the PasswordRecipientInfo:
 RecipientInfo recipient = new PasswordRecipientInfo(password, keyDerivationAlgorithm, derivationParameters, cekEncryptionAlgorithm, null);
 // create an EnvelopedData for the content to be encrypted:
 EnvelopedDataStream envelopedData = new EnvelopedDataStream(is, AlgorithmID.aes_128_CBC);
 // add the recipient information:
 envelopedData.addRecipientInfo(recipient);
 // write the EnvelopedData to a stream thereby performing the content encryption:
 int blockSize = ...;
 OutputStream encoded_stream = ...;
 envelopedData.writeTo(encoded_stream, blockSize);
 ...
 // on the recipient side decode the EnvelopedData:
 InputStream encodedStream = ...;
 EnvelopedDataStream envelopedData = new EnvelopedData(encodedStream);
 // Get information about the inherent EncryptedContentInfo:
 EncryptedContentInfoStream eci = (EncryptedContentInfoStream)enveloped_data.getEncryptedContentInfo();
 System.out.println("Content type: "+eci.getContentType().getName());
 System.out.println("Content encryption algorithm: "+eci.getContentEncryptionAlgorithm().getName());
  // get the PasswordRecipientInfo:
 PasswordRecipientInfo recipient = (PasswordRecipientInfo)envelopedData.getRecipientInfos()[0];
 // decrypt the encrypted CEK:
 String cekAlgorithmName = "AES";
 SecureStringBuffer password = ...;
 SecretKey cek = recipient.decryptKey(password, eci.getContentEncryptionAlgorithm().getName()); 
 // setup the cipher for decryption:
 envelopedData.setupCipher(cek, kekIdentifier);
 // read the content thereby performing the content decryption:
 InputStream data_is = enveloped_data.getInputStream();
 byte[] buf = new byte[1024];
 int r;
 while ((r = data_is.read(buf)) > 0) {
   // do something useful
 }
 

See Also:

RecipientInfo

Field Summary

Fields

Modifier and Type	Field and Description
protected AlgorithmID	keyDerivationAlgorithm_ The algorithm used for deriving the content encryption key.

Fields inherited from class iaik.cms.RecipientInfo

KEK_RECIPIENT_INFO, KEY_AGREE_RECIPIENT_INFO, KEY_TRANSPORT_RECIPIENT_INFO, keyEncryptionAlgorithm_, OTHER_RECIPIENT_INFO, PASSWORD_RECIPIENT_INFO, securityProvider_, version_

Constructor Summary

Constructors

Constructor and Description
PasswordRecipientInfo() Default Constructor.
PasswordRecipientInfo(AlgorithmID keyDerivationAlgorithm, AlgorithmID keyEncryptionAlgorithm, byte[] encryptedKey) Creates a PasswordRecipientInfo object for the given key-encryption algorithm, and already encrypted content encryption key.
PasswordRecipientInfo(AlgorithmID keyEncryptionAlgorithm, byte[] encryptedKey) Creates a PasswordRecipientInfo object for the given key-encryption algorithm, and already encrypted content encryption key.
PasswordRecipientInfo(AlgorithmID keyEncryptionAlgorithm, javax.crypto.SecretKey kek) Creates a PasswordRecipientInfo object for the given kek identifier, key-encryption algorithm and secret key encryption key.
PasswordRecipientInfo(AlgorithmID keyEncryptionAlgorithm, javax.crypto.SecretKey kek, java.security.AlgorithmParameters keyEncryptionAlgorithmParams) Creates a PasswordRecipientInfo object for the given KEK identifier, key-encryption algorithm and secret key encryption key.
PasswordRecipientInfo(ASN1Object obj) Creates a PasswordRecipientInfo from an ASN1Object.
PasswordRecipientInfo(SecureStringBuffer password, AlgorithmID keyDerivationAlgorithm, java.security.spec.AlgorithmParameterSpec keyDerivationAlgorithmParams, AlgorithmID kekEncryptionAlgorithm, java.security.AlgorithmParameters kekEncryptionAlgorithmParams) Creates a PasswordRecipientInfo object for deriving key encryption key (KEK) from the supplied password.

Method Summary

Methods

Modifier and Type	Method and Description
void	decode(ASN1Object asn) Decodes the given ASN.1 PasswordRecipientInfo object for parsing the internal structure.
javax.crypto.SecretKey	decryptKey(java.security.Key kek, KeyIdentifier keyidentifier, java.lang.String algorithmName) Uses the given secret key encryption key to decrypt (unwrap) the encrypted (wrapped) content-encryption key.
javax.crypto.SecretKey	decryptKey(java.security.Key kek, java.lang.String cekAlgorithmName) Uses the given secret key encryption key to decrypt (unwrap) the encrypted (wrapped) content-encryption key.
javax.crypto.SecretKey	decryptKey(SecureStringBuffer password) Uses the given password to derive the KEK to be used to unwrap the CEK.
javax.crypto.SecretKey	decryptKey(SecureStringBuffer password, java.lang.String cekAlgorithmName) Uses the given password to derive the key to decrypt the encrypted content-encryption key.
javax.crypto.SecretKey	decryptKey(SecureStringBuffer password, java.lang.String cekAlgorithmName, AlgorithmID keyDerivationAlgorithm) Uses the given password to derive the KEK to be used to unwrap the CEK.
void	encryptKey(javax.crypto.SecretKey cek) Encrypts (wraps) the given secret content-encryption key.
byte[]	getEncryptedKey() Returns the encrypted, formatted, content-encryption key.
byte[]	getEncryptedKey(KeyIdentifier recipientIdentifier) Returns the encrypted content-encryption key.
javax.crypto.SecretKey	getKEK()
AlgorithmID	getKeyDerivationAlgorithm() Returns the key-derivation algorithm used for encrypting the content-encryption key with the recipient's public key.
KeyIdentifier[]	getRecipientIdentifiers() Gets the key identifier belonging to the recipient of this PasswordRecipientInfo.
boolean	isPasswordRequired()
boolean	isRecipientInfoFor(KeyIdentifier recipientIdentifier) Since a PasswordRecipientInfo generally does not contain recipient identification information this method always return false indicating that this PasswordRecipientInfo may not belong to the recipient with the given recipient identifier.
CertificateIdentifier	isRecipientInfoFor(X509Certificate recipientCertificate) Always returns null indicating that a PasswordRecipientInfo does not use certificates as it uses a secret key (KEK to decrypt the CEK.
RecipientInfo	makeClone() Clone ourself.
ASN1Object	toASN1Object() Returns this PasswordRecipientInfo as an ASN1Object.
java.lang.String	toString() Returns a string giving some information about this object.

Methods inherited from class iaik.cms.RecipientInfo

decryptKey, decryptKey, encodeSequence, getKeyEncryptionAlgorithm, getRecipientInfoType, getVersion, parseRecipientInfo, parseRecipientInfo, parseRecipientInfos

Methods inherited from class java.lang.Object

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

Field Detail

keyDerivationAlgorithm_

protected AlgorithmID keyDerivationAlgorithm_

The algorithm used for deriving the content encryption key.

Constructor Detail

PasswordRecipientInfo

public PasswordRecipientInfo()

Default Constructor. Creates an empty PasswordRecipientInfo object and sets the version number to 0. Only used for dynamic object creation. Shall not be used by an application.

PasswordRecipientInfo

public PasswordRecipientInfo(AlgorithmID keyEncryptionAlgorithm,
                     byte[] encryptedKey)
                      throws java.security.NoSuchAlgorithmException,
                             java.security.spec.InvalidParameterSpecException

Creates a PasswordRecipientInfo object for the given key-encryption algorithm, and already encrypted content encryption key. The already encrypted secret key is supplied in a byte array and has been encrypted using the given key-encryption algorithm.
Note: this constructor internally creates a clone of the supplied key-encryption AlgorithmID. This is used to decrypt the encrypted key

Parameters:

keyEncryptionAlgorithm - the ID of the key-encryption (key-wrap) algorithm that has been used for encrypting the content-encryption key. It should have any needed algorithm parameters attached.

encryptedKey - the already encrypted secret content-encryption key

Throws:

java.security.spec.InvalidParameterSpecException

java.security.NoSuchAlgorithmException

PasswordRecipientInfo

public PasswordRecipientInfo(AlgorithmID keyDerivationAlgorithm,
                     AlgorithmID keyEncryptionAlgorithm,
                     byte[] encryptedKey)
                      throws java.security.NoSuchAlgorithmException,
                             java.security.spec.InvalidParameterSpecException

Creates a PasswordRecipientInfo object for the given key-encryption algorithm, and already encrypted content encryption key. The already encrypted secret key is supplied in a byte array and has been encrypted using the given key-encryption algorithm.
Note: this constructor internally creates a clone of the supplied key-encryption AlgorithmID.

Parameters:

keyDerivationAlgorithm - the ID of the key derivation algorithm. It will be cloned

keyEncryptionAlgorithm - the ID of the key-encryption (key-wrap) algorithm that has been used for encrypting the content-encryption key

encryptedKey - the already encrypted secret content-encryption key

Throws:

java.security.spec.InvalidParameterSpecException

java.security.NoSuchAlgorithmException

PasswordRecipientInfo

public PasswordRecipientInfo(AlgorithmID keyEncryptionAlgorithm,
                     javax.crypto.SecretKey kek,
                     java.security.AlgorithmParameters keyEncryptionAlgorithmParams)
                      throws java.security.NoSuchAlgorithmException,
                             java.security.spec.InvalidParameterSpecException

Creates a PasswordRecipientInfo object for the given KEK identifier, key-encryption algorithm and secret key encryption key.

Note: this constructor internally creates a clone of the supplied key-encryption AlgorithmID.

Parameters:

kek - the KEKIdentifier identifying the key encryption key

keyEncryptionAlgorithm - the ID of the key-encryption (key-wrap) algorithm to be used for encrypting the content-encryption key

kek - the secret key encryption key to be used for encrypting the content-encryption key

params - any algorithm parameters to be used for initializing the key wrap cipher

Throws:

java.security.spec.InvalidParameterSpecException

java.security.NoSuchAlgorithmException

PasswordRecipientInfo

public PasswordRecipientInfo(AlgorithmID keyEncryptionAlgorithm,
                     javax.crypto.SecretKey kek)
                      throws java.security.NoSuchAlgorithmException,
                             java.security.spec.InvalidParameterSpecException

Creates a PasswordRecipientInfo object for the given kek identifier, key-encryption algorithm and secret key encryption key.

Note: this constructor internally creates a clone of the supplied key-encryption AlgorithmID.

Parameters:

keyEncryptionAlgorithm - the ID of the key-encryption (key-wrap) algorithm to be used for encrypting the content-encryption key

kek - the secret key encryption key to be used for encrypting the content-encryption key

Throws:

java.security.spec.InvalidParameterSpecException

java.security.NoSuchAlgorithmException

PasswordRecipientInfo

public PasswordRecipientInfo(ASN1Object obj)
                      throws CodingException

Creates a PasswordRecipientInfo from an ASN1Object. This is typically done in preparation for decrypting the CEK. The typical sequence is: SecretKey cek = new PasswordRecipientInfo(asnObject).decryptKey(password, cekAlgorithm);

Parameters:

obj - the PasswordRecipientInfo as ASN1Object

Throws:

CodingException - if the object can not be parsed

PasswordRecipientInfo

public PasswordRecipientInfo(SecureStringBuffer password,
                     AlgorithmID keyDerivationAlgorithm,
                     java.security.spec.AlgorithmParameterSpec keyDerivationAlgorithmParams,
                     AlgorithmID kekEncryptionAlgorithm,
                     java.security.AlgorithmParameters kekEncryptionAlgorithmParams)
                      throws java.security.NoSuchAlgorithmException,
                             java.security.spec.InvalidKeySpecException,
                             CodingException,
                             java.security.InvalidAlgorithmParameterException,
                             java.security.spec.InvalidParameterSpecException,
                             CMSException

Creates a PasswordRecipientInfo object for deriving key encryption key (KEK) from the supplied password. When later calling encryptKey the derived KEK is used to encrypt the content encryption key (CEK).

Parameters:

password - password used to derive the key used to encrypt the CEK. It will be cleared.

keyDerivationAlgorithm - key derivation algorithm. It will be cloned.

keyDerivationAlgorithmParams - key derivation algorithm parameters, such as salt and number of iterations

kekEncryptionAlgorithm - algorithm to use to encrypt the CEK

kekEncryptionAlgorithmParams - parameters to kekEncryptionAlgorithm

Throws:

java.security.NoSuchAlgorithmException

java.security.spec.InvalidKeySpecException

CodingException

java.security.InvalidAlgorithmParameterException

java.security.spec.InvalidParameterSpecException

CMSException

Method Detail

decode

public void decode(ASN1Object asn)
            throws CodingException

Decodes the given ASN.1 PasswordRecipientInfo object for parsing the internal structure.

This method internally is called when creating a CMS PasswordRecipientInfoobject from an ASN.1 encoded PasswordRecipientInfo

Parameters:

asn - the CMS PasswordRecipientInfo as ASN1Object

Throws:

CodingException - if the object can not be parsed or is syntactically invalid

toASN1Object

public ASN1Object toASN1Object()

Returns this PasswordRecipientInfo as an ASN1Object.

The ASN1Object returned by this method represents the ASN.1 structure of a PasswordRecipientInfo:

 PasswordRecipientInfo ::= SEQUENCE {
    version                   CMSVersion, -- always set to 0
    keyDerivationAlgorithm   [0]  KeyDerivationAlgorithmIdentifier,
    keyEncryptionAlgorithm    KeyEncryptionAlgorithmIdentifier,
    encryptedKey              EncryptedKey
 }
 

 EncryptedKey ::= OCTET STRING
 KeyEncryptionAlgorithmIdentifier ::= AlgorithmIdentifier {{ KeyEncryptionAlgorithms }}
 KeyEncryptionAlgorithms ALGORITHM ::= {
  { OID id-alg-PWRI-KEK PARMS
    AlgorithmIdentifier {{ PWRIAlgorithms }} },
  ...
  }
 

Returns:

this PasswordRecipientInfo as ASN1Object.

decryptKey

public javax.crypto.SecretKey decryptKey(SecureStringBuffer password)
                                  throws java.lang.Exception

Uses the given password to derive the KEK to be used to unwrap the CEK.

Parameters:

password - the password used to derive the KEK (used to wrap the CEK)

Returns:

the CEK

Throws:

java.lang.Exception

decryptKey

public javax.crypto.SecretKey decryptKey(SecureStringBuffer password,
                                java.lang.String cekAlgorithmName,
                                AlgorithmID keyDerivationAlgorithm)
                                  throws java.lang.Exception

Uses the given password to derive the KEK to be used to unwrap the CEK.

Parameters:

password - the password used to derive the KEK (used to wrap the CEK)

Returns:

the CEK

Throws:

java.lang.Exception

decryptKey

public javax.crypto.SecretKey decryptKey(SecureStringBuffer password,
                                java.lang.String cekAlgorithmName)
                                  throws java.security.NoSuchAlgorithmException,
                                         java.security.spec.InvalidParameterSpecException,
                                         java.security.InvalidAlgorithmParameterException,
                                         java.security.InvalidKeyException,
                                         java.lang.IllegalStateException,
                                         javax.crypto.IllegalBlockSizeException,
                                         javax.crypto.BadPaddingException,
                                         javax.crypto.ShortBufferException,
                                         javax.crypto.NoSuchPaddingException,
                                         CMSException

Uses the given password to derive the key to decrypt the encrypted content-encryption key. Uses the given private key to decrypt the encrypted content-encryption key. The recovered key is returned as SecretKey.

This method implements the same named method of the abstract parent RecipientInfo class. Since a KeyTransRecipientInfo only represents one single recipient the supplied recipientIdentifier may be null.

Parameters:

password - password to derive the key (KEK) used to decrypt the double-wrapped CEK

cekAlgorithmName - Content Encryption Key's algorithm

Returns:

the recovered (decrypted) CEK as SecretKey in RAW format

Throws:

java.security.NoSuchAlgorithmException

java.security.spec.InvalidParameterSpecException - if we don't have the CMS-PWRI-KEK or PBE parameter specs

java.security.InvalidAlgorithmParameterException - PBE parameter (salt, iteration count or KEK length) is invalid

javax.crypto.ShortBufferException - Should be impossible

javax.crypto.BadPaddingException - Should be impossible

javax.crypto.IllegalBlockSizeException

java.lang.IllegalStateException

java.security.InvalidKeyException

CMSException

javax.crypto.NoSuchPaddingException

decryptKey

public javax.crypto.SecretKey decryptKey(java.security.Key kek,
                                java.lang.String cekAlgorithmName)
                                  throws CMSException,
                                         java.security.InvalidKeyException

Uses the given secret key encryption key to decrypt (unwrap) the encrypted (wrapped) content-encryption key. The recovered key is returned as SecretKey.

Parameters:

kek - the secret key encryption key to be used to decrypt (unwrap) the encrypted (wrapped) content-encryption key.

Returns:

the recovered (decrypted) key as SecretKey

Throws:

CMSException - if the key-decryption process fails for some reason (e.g. the key-encryption algorithm used is not implemented, a padding error occurs,...)

java.security.InvalidKeyException - if the specified key encryption key (KEK) is not a SecretKey

decryptKey

public javax.crypto.SecretKey decryptKey(java.security.Key kek,
                                KeyIdentifier keyidentifier,
                                java.lang.String algorithmName)
                                  throws java.security.InvalidKeyException,
                                         CMSException

Uses the given secret key encryption key to decrypt (unwrap) the encrypted (wrapped) content-encryption key. The recovered key is returned as SecretKey.

This method implements the same named method of the abstract parent RecipientInfo class. Since a PasswordRecipientInfo only represents one single recipient the supplied recipientIdentifier may be null.

Specified by:

decryptKey in class RecipientInfo

Parameters:

kek - the secret key encryption key to be used for decrypting (unwrapping) the encrypted (wrapped) content-encryption key.

keyidentifier - not used

The - algorithm represented by the kek. For example "DES" or "AES".

Returns:

the recovered (decrypted) key as SecretKey

Throws:

CMSException - if the key-decryption process fails for some reason (e.g. the key-encryption algorithm used by this PasswordRecipientInfo is not implemented, a padding error occurs,...)

java.security.InvalidKeyException - if the specified private key is not valid

encryptKey

public void encryptKey(javax.crypto.SecretKey cek)
                throws CMSException

Encrypts (wraps) the given secret content-encryption key.

All information (key encryption algorithm, key encryption key) required has been supplied when creating this KEKRecipientInfo object.

Specified by:

encryptKey in class RecipientInfo

Parameters:

cek - the symmetric content-encryption key to encrypt

Throws:

CMSException - if the key encryption process fails for some reason (e.g. the key-encryption algorithm used is not implemented, the key encryption key is invalid, a padding error occurs,...)

getRecipientIdentifiers

public KeyIdentifier[] getRecipientIdentifiers()

Gets the key identifier belonging to the recipient of this PasswordRecipientInfo.

This method implements the same named method of the abstract parent RecipientInfo class for returning an identifier for the recipient´s key encryption (decryption) key.Since a PasswordRecipientInfo generally does not contain recipient identification information this method always return an empty KeyIdentifier array indicating that there are no KeyIdentifiers used

Specified by:

getRecipientIdentifiers in class RecipientInfo

Returns:

an empty KeyIdentifier array

isRecipientInfoFor

public boolean isRecipientInfoFor(KeyIdentifier recipientIdentifier)

Since a PasswordRecipientInfo generally does not contain recipient identification information this method always return false indicating that this PasswordRecipientInfo may not belong to the recipient with the given recipient identifier.

Specified by:

isRecipientInfoFor in class RecipientInfo

Parameters:

recipientIdentifier - unused

Returns:

false as PasswordRecipientInfo does not use certificates.

isRecipientInfoFor

public CertificateIdentifier isRecipientInfoFor(X509Certificate recipientCertificate)

Always returns null indicating that a PasswordRecipientInfo does not use certificates as it uses a secret key (KEK to decrypt the CEK.

Specified by:

isRecipientInfoFor in class RecipientInfo

Parameters:

recipientCertificate - the certificate of the recipient in mind

Returns:

null indicating that this PasswordRecipientInfo cannot belong to the recipient with the given certificate

getEncryptedKey

public byte[] getEncryptedKey()

Returns the encrypted, formatted, content-encryption key.

Returns:

the encrypted content-encryption key

getEncryptedKey

public byte[] getEncryptedKey(KeyIdentifier recipientIdentifier)
                       throws CMSException

Returns the encrypted content-encryption key. Since a PasswordRecipientInfo only represents one single recipient the supplied recipientIdentifier is ignored.

Specified by:

getEncryptedKey in class RecipientInfo

Parameters:

recipientIdentifier - not used

Returns:

the encrypted content-encryption key for the recipient with the given key identifier

Throws:

CMSException - not thrown

getKeyDerivationAlgorithm

public AlgorithmID getKeyDerivationAlgorithm()

Returns the key-derivation algorithm used for encrypting the content-encryption key with the recipient's public key.

Returns:

the key-encryption AlgorithmID

toString

public java.lang.String toString()

Returns a string giving some information about this object.

Overrides:

toString in class java.lang.Object

Returns:

a string representation of ourself

makeClone

public RecipientInfo makeClone()

Clone ourself.

Specified by:

makeClone in class RecipientInfo

getKEK

public javax.crypto.SecretKey getKEK()

Returns:

the derived Key Encryption Key (KEK)

isPasswordRequired

public boolean isPasswordRequired()

Overrides:

isPasswordRequired in class RecipientInfo

Returns:

Does this recipient info require a password, as opposed to a key?