iaik.cms
Class RecipientInfo

java.lang.Object
  extended by 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:


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.


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. "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...
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. "DES") 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

This Javadoc may contain text parts from text parts from IETF Internet Standard specifications (see copyright note).

IAIK-CMS 5.1, (c) 2002 IAIK, (c) 2003 - 2010 SIC