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 CMS Cryptographic Message Syntax specifies the RecipientInfo type for collecting all recipient-related information about some particular recipient a CMS EnvelopedData or CMS AuthenticatedData shall be sent to.

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´s certificate, identified by IssuerAndSerialNumber. CMS recommends to use RSA for encrypting the content encryption key.
• key agreement: the recipient´s public key and the sender´s 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 ephemeral-static DH or ECDH 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 Triple-DES key wrap or RC2 key wrap.

Field Summary

Fields

Modifier and Type	Field and Description
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

Constructors

Modifier	Constructor and Description
protected	RecipientInfo() Creates an empty RecipientInfo.

Method Summary

Modifier and Type	Method and Description
javax.crypto.SecretKey	decryptKey(java.security.Key key) Decrypts the encrypted content-encryption key this RecipientInfo holds for the given recipient.
javax.crypto.SecretKey	decryptKey(java.security.Key key, KeyIdentifier recipientIdentifier) Decrypts the encrypted content-encryption key this RecipientInfo holds for the given recipient.
abstract javax.crypto.SecretKey	decryptKey(java.security.Key key, KeyIdentifier keyidentifier, java.lang.String algorithmName) Decrypts the encrypted content-encryption key this RecipientInfo holds for the given recipient.
static ASN1Object	encodeSequence(java.util.List<RecipientInfo> ris) Encode the list of RecipientInfos into an ASN1 SET.
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's 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.
int	getVersion() Returns the CMS version this RecipientInfo represents.
boolean	isPasswordRequired()
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.
abstract RecipientInfo	makeClone()
static RecipientInfo	parseRecipientInfo(ASN1Object obj) 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[]	parseRecipientInfos(java.io.InputStream is) Parses a SET of DER encoded RecipientInfos from the supplied input stream.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, 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.

Since:

Entrust 7.0

See Also:

Constant Field Values

version_

protected int version_

The CMS version this RecipientInfo represents.

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

keyEncryptionAlgorithm_

protected AlgorithmID keyEncryptionAlgorithm_

The algorithm used for encrypting the content encryption key. This is always PWRI-KEK with a parameter specifying the true encryption algorithm.

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 (0, 2: KEY_TRANSPORT_RECIPIENT_INFO 0: PASSWORD_RECIPIENT_INFO 3: KEY_AGREE_RECIPIENT_INFO 4: KEK_RECIPIENT_INFO 4: OTHER_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 algorithm used by this RecipientInfo is not implemented, or the recipient´s key is invalid, ...)

decryptKey

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

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

The recovered key is returned as SecretKey.

Parameters:

key - the recipient´s 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

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 abstract javax.crypto.SecretKey decryptKey(java.security.Key key,
                                                  KeyIdentifier keyidentifier,
                                                  java.lang.String algorithmName)
                                           throws java.security.InvalidKeyException,
                                                  CMSException

Decrypts the encrypted content-encryption key this RecipientInfo holds for the given recipient. The recovered key is returned as SecretKey.

Parameters:

Parameters:

key - - the recipient´s key used to decrypt the encrypted content-encryption key.

keyidentifier - - 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)

algorithmName - - the name of the content encryption key (e.g. "DES") 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... InvalidKeyException - if the specified private key is not valid

java.security.InvalidKeyException

decryptKey

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

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:

key - the recipient´s key used to decrypt the encrypted content-encryption key.

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

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) PASSWORD_RECIPIENT_INFO (4) OTHER_RECIPIENT_INFO (4)

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

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, containing any number of as KeyTransRecipientInfos, KeyAgreeRecipientInfos, KEKRecipientInfos, PasswordRecipientInfos, or OtherRecipientInfo, depending on the versions 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, KEKRecipientInfos, PasswordRecipientInfos, or OtherRecipientInfo depending on the CMS version field

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 ASN1 tag

Throws:

CMSParsingException - if an error occurs while parsing the RecipientInfo

encodeSequence

public static ASN1Object encodeSequence(java.util.List<RecipientInfo> ris)
                                 throws CodingException

Encode the list of RecipientInfos into an ASN1 SET. The various RecipientInfos will be tagged appropriately based on their type.

Parameters:

ris - the list of RecipientInfos to be encoded

Returns:

the ASN1Object representing the encoded SET.

Throws:

CodingException

Since:

Entrust 7.0

makeClone

public abstract RecipientInfo makeClone()

isPasswordRequired

public boolean isPasswordRequired()

Returns:

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