iaik.pkcs.pkcs7
Class RecipientInfo

java.lang.Object
  |
  +--iaik.pkcs.pkcs7.RecipientInfo

All Implemented Interfaces:

ASN1Type

public class RecipientInfo

extends Object

implements ASN1Type

This class implements the PKCS#7 RecipientInfo type.

The PKCS#7 Cryptographic Message Standard specifies the RecipientInfo type for collecting all recipient-related information about some particular recipient a PKCS#7 EnvelopedData or PKCS#7 SignedAndEnvelopedData object shall be sent to:

 RecipientInfo ::= SEQUENCE {
    version                   Version,
    issuerAndSerialNumber     IssuerAndSerialNumber,
    keyEncryptionAlgorithm    KeyEncryptionAlgorithmIdentifier,
    encryptedKey              EncryptedKey }
 

 EncryptedKey ::= OCTET STRING
 

The issuerAndSerialNumber field specifies the recipientīs certificate by issuer distinguished name and issuer-specific serial number. The keyEncryptionAlgorithm identifies the public-key algorithm used for encrypting the randomly generated content-encryption key with a recipient-specific public key. At this time only the PKCS#1 rsaEncryption method is supported. The encrypted content-encryption key (used for encrypting the content) is stored in the encryptedKey field.

For more information consult the RSA PKCS#7 specification.

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

Assuming that cert represents the X509v3 certificate of some intended recipient, a RecipientInfo object may be created by supplying the certificate issuer distinguished name and the issuer-specific serial number (through the certificate), and the recipientīs key-encryption algorithm ID for encrypting the content-encryption key, e.g:

 RecipientInfo recipient = new RecipientInfo(cert, AlgorithmID.rsaEncryption);
 

Note, that currently this class only supports the rsa(Encryption) key-encryption algorithm!

Version:

File Revision 28

See Also:

EnvelopedData, EnvelopedDataStream, SignedAndEnvelopedData, SignedAndEnvelopedDataStream, IssuerAndSerialNumber

Constructor Summary

RecipientInfo()
Default Constructor.

RecipientInfo(ASN1Object obj)
Creates a RecipientInfo from an ASN1Object.

RecipientInfo(IssuerAndSerialNumber issuer, AlgorithmID keyEA, byte[] encryptedKey)
Creates a RecipientInfo object with given IssuerAndSerialNumber, key-encryption algorithm, and already encrypted content encryption key.

RecipientInfo(X509Certificate recipientCertificate, AlgorithmID keyEA)
Creates a RecipientInfo object from a given certificate.

Method Summary

void	decode(ASN1Object obj) Decodes the given ASN.1 RecipientInfo object for parsing the internal structure.
SecretKey	decryptKey(PrivateKey privateKey) Uses a RSAPrivateKey to decrypt the encrypted content-encryption key.
SecretKey	decryptKey(PrivateKey privateKey, String cekAlgorithm) Uses a RSAPrivateKey to decrypt the encrypted content-encryption key.
void	encryptKey(SecretKey key) Finishes the creation of a RecipientInfo object by encrypting the given secret key..
byte[]	getEncryptedKey() Returns the encrypted content-encryption key.
IssuerAndSerialNumber	getIssuerAndSerialNumber() Returns a specification of the recipient's certificate by issuer distinguished name and issuer-specific serial number.
AlgorithmID	getKeyEncryptionAlgorithm() Returns the key-encryption algorithm used for encrypting the content-encryption key with the recipient's public key.
RSACipherProvider	getRSACipherProvider() Gets the RSA cipher provider for this ReceipientInfo.
int	getVersion() Returns the version of this RecipientInfo.
void	setRSACipherProvider(RSACipherProvider provider) Sets the RSA cipher provider for this ReceipientInfo.
ASN1Object	toASN1Object() Returns this RecipientInfo as ASN1Object.
String	toString() Returns a string giving some information about this RecipientInfo object.

Methods inherited from class java.lang.Object

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

Constructor Detail

RecipientInfo

public RecipientInfo()

Default Constructor. Creates an empty RecipientInfo object and sets the version number to 0.

RecipientInfo

public RecipientInfo(IssuerAndSerialNumber issuer,
                     AlgorithmID keyEA,
                     byte[] encryptedKey)

Creates a RecipientInfo object with given IssuerAndSerialNumber, 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.

Parameters:

issuer - the IssuerAndSerialNumber specifying the recipientīs certificate (and thereby the recipientīs distinguished name and issuer-specific serial number)

keyEncAlg - the ID of the key-encryption algorithm that has been used for encrypting the content-encryption key

encryptedKey - the already encrypted secret key

RecipientInfo

public RecipientInfo(X509Certificate recipientCertificate,
                     AlgorithmID keyEA)
              throws NoSuchAlgorithmException

Creates a RecipientInfo object from a given certificate. From the given certificate the requested IssuerAndSerialNumber is obtained. The public key from the given certificate will be used to encrypt the symmetric content-encryption key with the given key-encryption algorithm when calling the encryptKey method.

Parameters:

recipientCertificate - the certificate of the recipient

keyEA - the algorithm for encrypting the symmetric key

Throws:

NoSuchAlgorithmException - if there is no implementation for the specified algorithm

RecipientInfo

public RecipientInfo(ASN1Object obj)
              throws CodingException

Creates a RecipientInfo from an ASN1Object.

The ASN1Object supplied to this constructor represents an already exisiting RecipientInfo object that may have been created by calling toASN1Object.

Parameters:

obj - the RecipientInfo as ASN1Object

Throws:

CodingException - if the object can not be parsed

Method Detail

decode

public void decode(ASN1Object obj)
            throws CodingException

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

This method internally is called when creating a PKCS#7 RecipientInfo object from an already existing RecipientInfo object, supplied as ASN1Object.

Specified by:

decode in interface ASN1Type

Parameters:

obj - the PKCS#7 RecipientInfo as ASN1Object

Throws:

CodingException - if the object can not be parsed

toASN1Object

public ASN1Object toASN1Object()

Returns this RecipientInfo as ASN1Object.

Creates an ASN1 SEQUENCE object supplied with all the component values as defined in the PKCS#7 Cryptographic Message Standard specification. The ASN1Object returned by this method may be used as parameter value when creating a RecipientInfo object using the RecipientInfo(ASN1Object obj) constructor.

Specified by:

toASN1Object in interface ASN1Type

Returns:

this RecipientInfo as ASN1Object.

decryptKey

public SecretKey decryptKey(PrivateKey privateKey)
                     throws PKCSException,
                            InvalidKeyException

Uses a RSAPrivateKey to decrypt the encrypted content-encryption key. The recovered key is returned as SecretKey. The algorithm name of the secret key is set to "RAW". If you want to specify the right name you may use method decryptKey(PrivateKey privateKey, String cekAlgorithm).

Parameters:

sk - the RSAPrivateKey to decrypt the encrypted content-encryption key.

Returns:

the recovered (decrypted) key as SecretKey in RAW format

Throws:

PKCSException - if the key-decryption process fails for some reason (e.g. the key-encryption algorithm used by this RecipientInfo is not implemented, or the given private key is not a RSAPrivateKey)

InvalidKeyException - if the specified private key is not valid

decryptKey

public SecretKey decryptKey(PrivateKey privateKey,
                            String cekAlgorithm)
                     throws PKCSException,
                            InvalidKeyException

Uses a RSAPrivateKey to decrypt the encrypted content-encryption key. The recovered key is returned as SecretKey.

Parameters:

sk - the RSAPrivateKey to decrypt the encrypted content-encryption key.

cekAlgorithm - the name of the content encryption algorithm (e.g. "DES") to be set for the recovered secret content encryption key. Setting the CEK algorithm name may be required in situations where the JCE framework (e.g. JDK 1.4) does not allow unlimited strength cryptography and so will deny a key with algorithm name "RAW" (set when using decryptKey(PrivateKey), but accept it with the right name, e.g. "DES".

Returns:

the recovered (decrypted) key as SecretKey in RAW format

Throws:

PKCSException - if the key-decryption process fails for some reason (e.g. the key-encryption algorithm used by this RecipientInfo is not implemented, or the given private key is not a RSAPrivateKey)

InvalidKeyException - if the specified private key is not valid

encryptKey

public void encryptKey(SecretKey key)
                throws PKCSException

Finishes the creation of a RecipientInfo object by encrypting the given secret key..

The public key from the recipientīs certificate is used to encrypt the given content-encryption key with the rsaEncryption method. The public key must be a RSAPublicKey.

Parameters:

key - the symmetric key to encrypt

Throws:

PKCSException - if the key encryption process fails for some reason (e.g. the key-encryption algortihm used by this RecipientInfo is not implemented, or the recipientīs public key is not a RSAPublicKey)

getVersion

public int getVersion()

Returns the version of this RecipientInfo. This class implements version 0.

Returns:

the version

getIssuerAndSerialNumber

public IssuerAndSerialNumber getIssuerAndSerialNumber()

Returns a specification of the recipient's certificate by issuer distinguished name and issuer-specific serial number.

Returns:

a specification of the recipient's certificate as IssuerAndSerialNumber

getKeyEncryptionAlgorithm

public AlgorithmID getKeyEncryptionAlgorithm()

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

Returns:

the key-encryption AlgorithmID

getEncryptedKey

public byte[] getEncryptedKey()

Returns the encrypted content-encryption key. The key has been encrypted with the recipientīs public key.

Returns:

the encrypted content-encryption key

setRSACipherProvider

public void setRSACipherProvider(RSACipherProvider provider)

Sets the RSA cipher provider for this ReceipientInfo. The RSACipherProvider allows an application to control the RSA cipher encryption/decryption (content encryption key encryption/decryption) operations. To, for instance, use the IAIK PKCS#11 provider for decryption (RSA cipher private key decryption) only, but the first installed provider for encryption (RSA cipher public encryption) you may set the PKCS#11 provider as RSA decryption provider:

 IAIKPkcs11 pkcs11Provider = new IAIKPkcs11();
 Security.addProvider(pkcs11Provider);
 ...
 RSACipherProvider rsaProv = new RSACipherProvider(null, pkcs11Provider.getName());
 ...
 ReceipientInfo signerInfo = ...;
 ...
 recipientInfo.setRSACipherProvider(rsaProv, null);
 

In overriding method cipher of the RSACipherProvider you even can take more influence on the ciphering process.

If no RSACipherProvider is set for this RecipientInfo the first installed RSA capable crypto provider is used for RSA en/deciphering.

Parameters:

provider - the RSACipherProvider to be used for private/public key RSA cipher operations

getRSACipherProvider

public RSACipherProvider getRSACipherProvider()

Gets the RSA cipher provider for this ReceipientInfo. The RSACipherProvider allows an application to control the RSA cipher encryption/decryption (content encryption key encryption/decryption operations). It may be set by calling method setRSACipherProvider.

Returns:

the RSACipherProvider to be used for private/public key RSA cipher operations

toString

public String toString()

Returns a string giving some information about this RecipientInfo object.

Overrides:

toString in class Object

Returns:

the string representation