iaik.cms
Class RecipientInfo

java.lang.Object
  iaik.cms.RecipientInfo

All Implemented Interfaces:

ASN1Type

Direct Known Subclasses:

KEKRecipientInfo, KeyAgreeRecipientInfo, KeyTransRecipientInfo, OtherRecipientInfo, PasswordRecipientInfo

public abstract class RecipientInfo
extends java.lang.Object
implements ASN1Type

The CMS type RecipientInfo.

The Cryptographic Message Syntax (CMS) (RFC 5652) specifies the RecipientInfo type for collecting all recipient-related information about some particular recipient a CMS EnvelopedData or CMS AuthenticatedData shall be sent to:

 RecipientInfo ::= CHOICE {
   ktri  KeyTransRecipientInfo,
   kari  [1] KeyAgreeRecipientInfo,
   kekri [2] KEKRecipientInfo,
   pwri  [3] PasswordRecipientinfo,
   ori   [4] OtherRecipientInfo }
 

The RecipientInfo type depends on the key management algorithm used for the recipient of an EnvelopedData or AuthenticatedData. CMS provides three alternatives:

• key transport: the content-encryption key is encrypted with the public key of the recipient. This technique id compatible to PKCS#7 when creating a RecipientInfo of type KeyTransRecipientInfo for the public key of the recipient certificate, identified by IssuerAndSerialNumber. CMS recommends to use RSA for encrypting the content encryption key.
• key agreement: the recipient public key and the sender private key are used to generate a pairwise symmetric key, then the content encryption key is encrypted with the pairwise symmetric key. Each RecipientInfo of type KeyAgreeRecipientInfo may transfer the encrypted content encryption key to one or more recipient using the same key agreement algorithm and domain parameters for that algorithm. CMS recommends to use ESDH with an ephemeral sender key.
• symmetric key-encryption keys: the content-encryption key is encrypted with a previously distributed symmetric key-encryption key. The RecipientInfo is of type KEKRecipientInfo using a CMS key wrap algorithm like AES key wrap.
• password based encryption: the content-encryption key is encrypted with key-encryption key derived from a password. The RecipientInfo is of type PasswordRecipientInfo using a key derivation algorithm like PBKDF2 as specified by RFC 2898 (PKCS#5) and a key encryption algorithm like PWRI-KEK as specified by RFC 3211.
• any other technique: based on private, user defined key management techniques; The RecipientInfo is of type OtherRecipientInfo

Field Summary

static int	KEK_RECIPIENT_INFO The CMS RecipientInfo type KEKRecipientInfo.
static int	KEY_AGREE_RECIPIENT_INFO The CMS RecipientInfo type KeyAgreeRecipientInfo.
static int	KEY_TRANSPORT_RECIPIENT_INFO The CMS RecipientInfo type KeyTransRecipientInfo.
protected AlgorithmID	keyEncryptionAlgorithm_ The algorithm used for encrypting the content encryption key.
static int	OTHER_RECIPIENT_INFO The CMS RecipientInfo type OtherRecipientInfo.
static int	PASSWORD_RECIPIENT_INFO The CMS RecipientInfo type PasswordRecipientInfo.
protected SecurityProvider	securityProvider_ The SecurityProvider providing the required cryptographic engines.
protected int	version_ The CMS version this RecipientInfo represents.

Constructor Summary

protected

RecipientInfo() Creates an empty RecipientInfo.

Method Summary

static SET	createRecipientInfos(java.util.Vector recipients) Creates a SET of the supplied RecipientInfos.
javax.crypto.SecretKey	decryptKey(java.security.Key kek) Decrypts the encrypted content-encryption key this RecipientInfo holds for the given recipient.
javax.crypto.SecretKey	decryptKey(java.security.Key kek, KeyIdentifier recipientIdentifier) Decrypts the encrypted content-encryption key this RecipientInfo holds for the given recipient.
abstract javax.crypto.SecretKey	decryptKey(java.security.Key kek, KeyIdentifier recipientIdentifier, java.lang.String cekAlgName) Decrypts the encrypted content-encryption key this RecipientInfo holds for the given recipient.
javax.crypto.SecretKey	decryptKey(java.security.Key kek, java.lang.String cekAlgName) Decrypts the encrypted content-encryption key this RecipientInfo holds for the given recipient.
abstract void	encryptKey(javax.crypto.SecretKey cek) Encrypts the given secret content encryption key for the recipient(s) this RecipientInfo represents.
abstract byte[]	getEncryptedKey(KeyIdentifier recipientIdentifier) Returns the encrypted content-encryption key for the recipient with the given keyIdentfier.
AlgorithmID	getKeyEncryptionAlgorithm() Returns the key-encryption algorithm used for encrypting the content-encryption key with the recipient public key.
abstract KeyIdentifier[]	getRecipientIdentifiers() Returns the key identifier(s) belonging to the recipient(s) of this RecipientInfo.
int	getRecipientInfoType() Returns the type of the recipient info.
SecurityProvider	getSecurityProvider() Gets the SecurityProvider installed for this RecipientInfo.
int	getVersion() Returns the CMS version this RecipientInfo represents.
abstract boolean	isRecipientInfoFor(KeyIdentifier recipientIdentifier) Checks if this is a RecipientInfo for the recipient identified by the given key identifier.
abstract CertificateIdentifier	isRecipientInfoFor(X509Certificate recipientCertificate) Checks if this is a RecipientInfo for the given recipient certificate.
static RecipientInfo	parseRecipientInfo(ASN1Object obj) Parses a RecipientInfo from the supplied ASN1Object.
static RecipientInfo	parseRecipientInfo(ASN1Object obj, SecurityProvider securityProvider) Parses a RecipientInfo from the supplied ASN1Object.
static RecipientInfo	parseRecipientInfo(java.io.InputStream is) Parses a DER encoded RecipientInfo from the supplied input stream.
static RecipientInfo	parseRecipientInfo(java.io.InputStream is, SecurityProvider securityProvider) Parses a DER encoded RecipientInfo from the supplied input stream.
static RecipientInfo[]	parseRecipientInfos(java.io.InputStream is) Parses a SET of DER encoded RecipientInfos from the supplied input stream.
static RecipientInfo[]	parseRecipientInfos(java.io.InputStream is, SecurityProvider securityProvider) Parses a SET of DER encoded RecipientInfos from the supplied input stream.
void	setSecurityProvider(SecurityProvider securityProvider) Sets the SecurityProvider for this RecipientInfo.
abstract java.lang.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

Methods inherited from interface iaik.asn1.ASN1Type

decode, toASN1Object

Field Detail

KEY_TRANSPORT_RECIPIENT_INFO

public static final int KEY_TRANSPORT_RECIPIENT_INFO

The CMS RecipientInfo type KeyTransRecipientInfo.

See Also:

Constant Field Values

KEY_AGREE_RECIPIENT_INFO

public static final int KEY_AGREE_RECIPIENT_INFO

The CMS RecipientInfo type KeyAgreeRecipientInfo.

See Also:

Constant Field Values

KEK_RECIPIENT_INFO

public static final int KEK_RECIPIENT_INFO

The CMS RecipientInfo type KEKRecipientInfo.

See Also:

Constant Field Values

PASSWORD_RECIPIENT_INFO

public static final int PASSWORD_RECIPIENT_INFO

The CMS RecipientInfo type PasswordRecipientInfo.

See Also:

Constant Field Values

OTHER_RECIPIENT_INFO

public static final int OTHER_RECIPIENT_INFO

The CMS RecipientInfo type OtherRecipientInfo.

See Also:

Constant Field Values

version_

protected int version_

The CMS version this RecipientInfo represents.

• -1: OTHER_RECIPIENT_INFO
• 0, 2: KEY_TRANSPORT_RECIPIENT_INFO
• 3: KEY_AGREE_RECIPIENT_INFO
• 4: KEK_RECIPIENT_INFO
• 0: PASSWORD_RECIPIENT_INFO

keyEncryptionAlgorithm_

protected AlgorithmID keyEncryptionAlgorithm_

The algorithm used for encrypting the content encryption key.

securityProvider_

protected SecurityProvider securityProvider_

The SecurityProvider providing the required cryptographic engines.

Constructor Detail

RecipientInfo

protected RecipientInfo()

Creates an empty RecipientInfo.

Method Detail

getVersion

public int getVersion()

Returns the CMS version this RecipientInfo represents.

Returns:

the CMS version number ( -1: OTHER_RECIPIENT_INFO 0, 2: KEY_TRANSPORT_RECIPIENT_INFO 3: KEY_AGREE_RECIPIENT_INFO 4: KEK_RECIPIENT_INFO 0: PASSWORD_RECIPIENT_INFO)

encryptKey

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

Encrypts the given secret content encryption key for the recipient(s) this RecipientInfo represents.

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 algortihm used by this RecipientInfo is not implemented, or the recipient key is invalid, ...)

decryptKey

public abstract javax.crypto.SecretKey decryptKey(java.security.Key kek,
                                                  KeyIdentifier recipientIdentifier,
                                                  java.lang.String cekAlgName)
                                           throws CMSException,
                                                  java.security.InvalidKeyException

Decrypts the encrypted content-encryption key this RecipientInfo holds for the given recipient.

The recovered key is returned as SecretKey.

Parameters:

kek - the recipient key used to decrypt the encrypted content-encryption key.

recipientIdentifier - information to be used for getting the right encrypted content encryption key for the right recipient; may be required if this RecipientInfo holds content encryption keys for more than one recipient (see KeyAgreeRecipientInfo)

cekAlgName - the name of the content encryption key (e.g. "AES") to be set for the SecretKey object created by this method

Returns:

the recovered (decrypted) content encryption key as SecretKey in RAW format

Throws:

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

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

decryptKey

public javax.crypto.SecretKey decryptKey(java.security.Key kek,
                                         KeyIdentifier recipientIdentifier)
                                  throws CMSException,
                                         java.security.InvalidKeyException

Decrypts the encrypted content-encryption key this RecipientInfo holds for the given recipient.

The recovered key is returned as SecretKey.

Parameters:

kek - the recipient key used to decrypt the encrypted content-encryption key.

recipientIdentifier - information to be used for getting the right encrypted content encryption key for the right recipient; may be required if this RecipientInfo holds content encryption keys for more than one recipient (see KeyAgreeRecipientInfo)

Returns:

the recovered (decrypted) content encryption key as SecretKey in RAW format; the algorithm name will be set to "RAW"

Throws:

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

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

decryptKey

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

Decrypts the encrypted content-encryption key this RecipientInfo holds for the given recipient.

The recovered key is returned as SecretKey.

Note that a KeyAgreeRecipientInfo may hold recipient encrypted keys for more than only one recipient; so it may be appropriate to specify a recipient identifier when decrypting the encrypted content-encryption key. Otherwise all included recipient encrypted keys may be tried to be decrypted with the given key encryption key, which might give some overhead.

Parameters:

kek - the recipient key used to decrypt the encrypted content-encryption key.

Returns:

the recovered (decrypted) content encryption key as SecretKey in RAW format; the algorithm name will be set to "RAW"

Throws:

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

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

decryptKey

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

Decrypts the encrypted content-encryption key this RecipientInfo holds for the given recipient.

The recovered key is returned as SecretKey.

Note that a KeyAgreeRecipientInfo may hold recipient encrypted keys for more than only one recipient; so it may be appropriate to specify a recipient identifier when decrypting the encrypted content-encryption key. Otherwise all included recipient encrypted keys may be tried to be decrypted with the given key encryption key, which might give some overhead.

Parameters:

kek - the recipient key used to decrypt the encrypted content-encryption key.

cekAlgName - the name of the content encryption key (e.g. "AES") to be set for the SecretKey object created by this method

Returns:

the recovered (decrypted) content encryption key as SecretKey in RAW format; the algorithm name will be set to "RAW"

Throws:

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

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

getEncryptedKey

public abstract byte[] getEncryptedKey(KeyIdentifier recipientIdentifier)
                                throws CMSException

Returns the encrypted content-encryption key for the recipient with the given keyIdentfier.

A RecipientInfo only may hold one single encrypted content-encryption key (e.g. KeyTransRecipientInfo), but may hold encrypted content-encryption keys for more than one recipients (e.g. KeyAgreeRecipientInfo), each of them identified by its corresponding key identifier.

Parameters:

recipientIdentifier - information to be used for getting the right encrypted content encryption key for the right recipient; may be required if this RecipientInfo holds content encryption keys for more than one recipient (see KeyAgreeRecipientInfo)

Returns:

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

Throws:

CMSException - if no recipient with this key identifier is included

getRecipientIdentifiers

public abstract KeyIdentifier[] getRecipientIdentifiers()

Returns the key identifier(s) belonging to the recipient(s) of this RecipientInfo.

A RecipientInfo only may represent only one single recipient (e.g. KeyTransRecipientInfo), but may represent more than one recipients (e.g. KeyAgreeRecipientInfo), each of them identified by its corresponding key identifier.

Returns:

the key identifier(s) belonging to the recipient(s) of this RecipientInfo

isRecipientInfoFor

public abstract boolean isRecipientInfoFor(KeyIdentifier recipientIdentifier)

Checks if this is a RecipientInfo for the recipient identified by the given key identifier.

Parameters:

recipientIdentifier - the key identifier belonging to the recipient we are searching for

Returns:

true if this RecipientInfo belongs to the particular recipient in mind, false if not

isRecipientInfoFor

public abstract CertificateIdentifier isRecipientInfoFor(X509Certificate recipientCertificate)

Checks if this is a RecipientInfo for the given recipient certificate.

This method only may be used for asking if a KeyTransRecipientInfo or KeyAgreeRecipientInfo belongs to the recipient with the given certificate. Class KEKRecipientInfo has to implement this method, too, but always will return null since the KEKRecipientInfo does not use certificates.

Parameters:

recipientCertificate - the certificate of the recipient

Returns:

the CertificateIdentifier indicating that the recipient with the given certificate is the owner of this RecipientInfo, null if not

getRecipientInfoType

public int getRecipientInfoType()

Returns the type of the recipient info.

Returns:

KEY_TRANSPORT_RECIPIENT_INFO (0) or KEY_AGREE_RECIPIENT_INFO (1) or KEK_RECIPIENT_INFO (2) or PASSWORD_RECIPIENT_INFO (3) or OTHER_RECIPIENT_INFO (4)

getKeyEncryptionAlgorithm

public AlgorithmID getKeyEncryptionAlgorithm()

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

Returns:

the key-encryption AlgorithmID

setSecurityProvider

public void setSecurityProvider(SecurityProvider securityProvider)

Sets the SecurityProvider for this RecipientInfo.

This method allows to explicitly set a SecurityProvider for this RecipientInfo. If no explicit SecurityProvider is set, the default system wide installed SecurityProvider will be used for the required cryptographic operations.

When parsing a KeyAgreeRecipientInfo or a KEKRecipientInfo, it might be preferable to supply the SecurityProvider immediately when creating the RecipientInfo.

Parameters:

securityProvider - the SecurityProvider to be set

getSecurityProvider

public SecurityProvider getSecurityProvider()

Gets the SecurityProvider installed for this RecipientInfo.

If no explicit SecurityProvider has been set for this object, the default system wide installed SecurityProvider will be used for the required cryptographic operations. However, this method will return null if it does not have its own SecurityProvider.

Returns:

the SecurityProvider explicitly installed for this object, or null if this object does not have its own SecurityProvider

parseRecipientInfos

public static RecipientInfo[] parseRecipientInfos(java.io.InputStream is)
                                           throws java.io.IOException,
                                                  CMSParsingException

Parses a SET of DER encoded RecipientInfos from the supplied input stream.

Parameters:

is - the input stream supplying the SET of DER encoded RecipientInfo

Returns:

the RecipientInfo SET as array, containg any number of as KeyTransRecipientInfos, KeyAgreeRecipientInfos KEKRecipientInfos, PasswordRecipientInfos, or OtherRecipientInfos, depending on the types of RecipientInfos contained in the SET

Throws:

java.io.IOException - if an I/O error occurs while reading from the stream

CMSParsingException - if an error occurs while parsing the RecipientInfo

parseRecipientInfos

public static RecipientInfo[] parseRecipientInfos(java.io.InputStream is,
                                                  SecurityProvider securityProvider)
                                           throws java.io.IOException,
                                                  CMSParsingException

Parses a SET of DER encoded RecipientInfos from the supplied input stream.

Parameters:

is - the input stream supplying the SET of DER encoded RecipientInfo

securityProvider - the securityProvider to be used, if null use the default system-wide installed SecurityProvider

Returns:

the RecipientInfo SET as array, containg any number of as KeyTransRecipientInfos, KeyAgreeRecipientInfos KEKRecipientInfos, PasswordRecipientInfos, or OtherRecipientInfos, depending on the types of RecipientInfos contained in the SET

Throws:

java.io.IOException - if an I/O error occurs while reading from the stream

CMSParsingException - if an error occurs while parsing the RecipientInfo

parseRecipientInfo

public static RecipientInfo parseRecipientInfo(java.io.InputStream is)
                                        throws java.io.IOException,
                                               CMSParsingException

Parses a DER encoded RecipientInfo from the supplied input stream.

Parameters:

is - the input stream supplying the DER encoded RecipientInfo

Returns:

the RecipientInfo the RecipientInfo parsed from the stream; as KeyTransRecipientInfo, KeyAgreeRecipientInfo KEKRecipientInfo, PasswordRecipientInfo, or OtherRecipientInfo, depending on the type of RecipientInfo

Throws:

java.io.IOException - if an I/O error occurs while reading from the stream

CMSParsingException - if an error occurs while parsing the RecipientInfo

parseRecipientInfo

public static RecipientInfo parseRecipientInfo(java.io.InputStream is,
                                               SecurityProvider securityProvider)
                                        throws java.io.IOException,
                                               CMSParsingException

Parses a DER encoded RecipientInfo from the supplied input stream.

Parameters:

is - the input stream supplying the DER encoded RecipientInfo

securityProvider - the securityProvider to be used, if null use the default system-wide installed SecurityProvider

Returns:

the RecipientInfo the RecipientInfo parsed from the stream; as KeyTransRecipientInfo, KeyAgreeRecipientInfo KEKRecipientInfo, PasswordRecipientInfo, or OtherRecipientInfo, depending on the type of RecipientInfo

Throws:

java.io.IOException - if an I/O error occurs while reading from the stream

CMSParsingException - if an error occurs while parsing the RecipientInfo

parseRecipientInfo

public static RecipientInfo parseRecipientInfo(ASN1Object obj)
                                        throws CMSParsingException

Parses a RecipientInfo from the supplied ASN1Object.

Parameters:

obj - the RecipientInfo as ASN1Object

Returns:

the RecipientInfo the RecipientInfo parsed from the ASN1Object; as KeyTransRecipientInfo, KeyAgreeRecipientInfo KEKRecipientInfo, PasswordRecipientInfo, or OtherRecipientInfo, depending on the type of RecipientInfo

Throws:

CMSParsingException - if an error occurs while parsing the RecipientInfo

parseRecipientInfo

public static RecipientInfo parseRecipientInfo(ASN1Object obj,
                                               SecurityProvider securityProvider)
                                        throws CMSParsingException

Parses a RecipientInfo from the supplied ASN1Object.

Parameters:

obj - the RecipientInfo as ASN1Object

securityProvider - the securityProvider to be used, if null use the default system-wide installed SecurityProvider

Returns:

the RecipientInfo the RecipientInfo parsed from the ASN1Object; as KeyTransRecipientInfo, KeyAgreeRecipientInfo KEKRecipientInfo, PasswordRecipientInfo, or OtherRecipientInfo, depending on the type of RecipientInfo

Throws:

CMSParsingException - if an error occurs while parsing the RecipientInfo

createRecipientInfos

public static SET createRecipientInfos(java.util.Vector recipients)
                                throws CMSException

Creates a SET of the supplied RecipientInfos.

This method creates a SET OF the supplied RecipientInfos thereby using the right tags depending on the RecipientInfo version number:

 RecipientInfo ::= CHOICE {
   ktri KeyTransRecipientInfo,
   kari [1] KeyAgreeRecipientInfo,
   kekri [2] KEKRecipientInfo,
   pwri [3] PasswordRecipientInfo,
   ori [4] OtherRecipientInfo }
 

Parameters:

recipients - the recipientInfos to be processed

Returns:

the SET OF RecipientInfos

Throws:

CMSException - if an error occurs while creating the ASN.1 SET

toString

public abstract java.lang.String toString()

Returns a string giving some information about this RecipientInfo object.

Overrides:

toString in class java.lang.Object

Returns:

the string representation