KeyTransRecipientInfo ("Entrust Authority Security Toolkit for the Java Platform")

java.lang.Object
- iaik.cms.RecipientInfo
- - iaik.cms.KeyTransRecipientInfo

All Implemented Interfaces:: ASN1Type

public class KeyTransRecipientInfo
extends RecipientInfo

This class implements the CMS KeyTransRecipientInfo type.

The CMS Cryptographic Message Syntax specifies the KeyTransRecipientInfo 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 public key to be used for encrypting the secret content-encryption key:

 KeyTransRecipientInfo ::= SEQUENCE {
    version                   CMSVersion, -- always set to 0 or 2
    rid                       RecipientIdentifier,
    keyEncryptionAlgorithm    KeyEncryptionAlgorithmIdentifier,
    encryptedKey              EncryptedKey }
 

 EncryptedKey ::= OCTET STRING
 

 RecipientIdentifier ::= CHOICE {
    issuerAndSerialNumber IssuerAndSerialNumber,
    subjectKeyIdentifier [0] SubjectKeyIdentifier }

The recipientIdentifier field specifies the recipient´s certificate (and thereby public key) by issuer distinguished name and issuer-specific serial number or SubjectKeyIdentifier. The keyEncryptionAlgorithm identifies the public-key algorithm used for encrypting the randomly generated content-encryption key with a recipient-specific public key. The encrypted content-encryption key (used for encrypting the content) is stored in the encryptedKeyfield.

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

When creating a new KeyTransRecipientInfo you immediately may supply the IssuerAndSerialNumber or SubjectKeyIdentifier or you may supply the certificate of the recipient to let this class create a certifcate identifier for it, e.g:

 // the cert of the recipient:
 X509Certificate recipientCert = ...;
 // use RSA for content key encryption:
 AlgorithmID kea = AlgorithmID.rsaEncryption;
 // create a v0 KeyTransRecipientInfo using an IssuerAndSerialNumber to point to the recipient cert:
 KeyTransRecipientInfo recipient = new KeyTransRecipientInfo(recipientCert, kea);

If you want to use a SubjectKeyIdentifier for pointing to the certificate of the recipient, you have to specify the CertificateIdentifier type when creating the KeyTransRecipientInfo:

 KeyTransRecipientInfo recipient = new KeyTransRecipientInfo(recipientCert, 
    CertificateIdentifier.SUBJECT_KEY_IDENTIFIER, kea);

The following example shows the typical usage for including a KEKRecipientInfo 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 cert of the recipient:
 X509Certificate recipientCert = ...;
 // use RSA for content key encryption:
 AlgorithmID kea = AlgorithmID.rsaEncryption;
 // create a v0 KeyTransRecipientInfo using an IssuerAndSerialNumber to point to the recipient cert:
 KeyTransRecipientInfo recipient = new KeyTransRecipientInfo(recipientCert, kea);
 // create an EnvelopedData for the content to be encrypted:
 EnvelopedDataStream envelopedData = new EnvelopedDataStream(is, AlgorithmID.des_EDE3_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());
 // setup the cipher for decryption:
 envelopedData.setupCipher(recipientPrivateKey, recipientCert);
 // 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:: IssuerAndSerialNumber, SubjectKeyID, RecipientInfo

Field Summary
- 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
`KeyTransRecipientInfo()` Default Constructor.
`KeyTransRecipientInfo(ASN1Object obj)` Creates a `KeyTransRecipientInfo` from an ASN1Object.
`KeyTransRecipientInfo(CertificateIdentifier recipientIdentifier, AlgorithmID keyEA, byte[] encryptedKey)` Creates a `KeyTransRecipientInfo` object for the given recipient certficate identifier, key-encryption algorithm, and already encrypted content encryption key.
`KeyTransRecipientInfo(CertificateIdentifier recipientIdentifier, AlgorithmID keyEA, java.security.PublicKey recipientKey)` Creates a `KeyTransRecipientInfo` object for the given recipient certficate identifier, key-encryption algorithm and public key of the recipient.
`KeyTransRecipientInfo(X509Certificate recipientCertificate, AlgorithmID keyEA)` Creates a version 0 KeyTransRecipientInfo object from the given recipient certificate.
`KeyTransRecipientInfo(X509Certificate recipientCertificate, int ridType, AlgorithmID keyEA)` Creates a KeyTransRecipientInfo object from the given recipient certificate.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`decode(ASN1Object obj)` Decodes the given ASN.1 `KeyTransRecipientInfo` object for parsing the internal structure.
`javax.crypto.SecretKey`	`decryptKey(java.security.Key privateKey, KeyIdentifier recipientIdentifier, java.lang.String kea)` Uses the given private key to decrypt the encrypted content-encryption key.
`void`	`encryptKey(javax.crypto.SecretKey cek)` Encrypts the given secret content-encryption key.
`byte[]`	`getEncryptedKey()` Returns the encrypted content-encryption key.
`byte[]`	`getEncryptedKey(KeyIdentifier recipientIdentifier)` Returns the encrypted content-encryption key for the recipient with the given keyIdentfier.
`KeyIdentifier[]`	`getRecipientIdentifiers()` Gets the key identifier belonging to the recipient of this KeyTransRecipientInfo.
`boolean`	`isRecipientInfoFor(KeyIdentifier recipientIdentifier)` Checks if this is a RecipientInfo for the recipient identified by the given key identifier.
`CertificateIdentifier`	`isRecipientInfoFor(X509Certificate recipientCertificate)` Checks if this is a RecipientInfo for the given recipient certficate.
`RecipientInfo`	`makeClone()`
`ASN1Object`	`toASN1Object()` Returns this `KeyTransRecipientInfo` as ASN1Object.
`java.lang.String`	`toString()` Returns a string giving some information about this `KeyTransRecipientInfo` object.

Methods inherited from class iaik.cms.RecipientInfo
decryptKey, decryptKey, encodeSequence, getKeyEncryptionAlgorithm, getRecipientInfoType, getVersion, isPasswordRequired, parseRecipientInfo, parseRecipientInfo, parseRecipientInfos

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - KeyTransRecipientInfo
```
public KeyTransRecipientInfo()
```
    Default Constructor. Creates an empty KeyTransRecipientInfo object and sets the version number to 0.
    Only used for dynamic object creation. Shall not be used by an application.
  - KeyTransRecipientInfo
```
public KeyTransRecipientInfo(CertificateIdentifier recipientIdentifier,
                             AlgorithmID keyEA,
                             byte[] encryptedKey)
```
    Creates a KeyTransRecipientInfo object for the given recipient certficate identifier, 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:
    
    recipientIdentifier - the CertificateIdentifier identifying the recipient´s certificate (by IssuerAndSerialNumber or SubjectKeyIdentifier
    
    keyEA - the ID of the key-encryption algorithm that has been used for encrypting the content-encryption key
    
    encryptedKey - the already encrypted secret key
  - KeyTransRecipientInfo
```
public KeyTransRecipientInfo(CertificateIdentifier recipientIdentifier,
                             AlgorithmID keyEA,
                             java.security.PublicKey recipientKey)
```
    Creates a KeyTransRecipientInfo object for the given recipient certficate identifier, key-encryption algorithm and public key of the recipient.
    
    Parameters:
    
    recipientIdentifier - the CertificateIdentifier identifying the recipient´s certificate (by IssuerAndSerialNumber or SubjectKeyIdentifier
    
    keyEA - the ID of the key-encryption algorithm to be used for encrypting the content-encryption key
    
    recipientKey - the public key of the recipient to be used for encrypting the content-encryption key
    
    Throws:
    
    java.lang.IllegalArgumentException - if the supplied recipientIdentifier is not a SubjectKeyID or IssuerAndSerialNumber
  - KeyTransRecipientInfo
```
public KeyTransRecipientInfo(X509Certificate recipientCertificate,
                             AlgorithmID keyEA)
```
    Creates a version 0 KeyTransRecipientInfo object from the given recipient certificate.
    From the given certificate an IssuerAndSerialNumber is created to be used as recipient identifier for pointing to the certificate of the recipient. 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 content-encryption key
  - KeyTransRecipientInfo
```
public KeyTransRecipientInfo(X509Certificate recipientCertificate,
                             int ridType,
                             AlgorithmID keyEA)
                      throws X509ExtensionException
```
    Creates a KeyTransRecipientInfo object from the given recipient certificate.
    From the given certificate an IssuerAndSerialNumber or SubjectKeyIdentifier (depending on the requested recipient identifier type) is created to be used as recipient identifier for pointing to the certificate of the recipient. 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
    
    ridType - the type of the recipientIdentifier, either CertificateIdentifier.ISSUER_AND_SERIALNUMBER or CertificateIdentifier.SUBJECT_KEY_IDENTIFIER
    
    keyEA - the algorithm for encrypting the symmetric key
    
    Throws:
    
    X509ExtensionException - if a SubjectKeyIdentifier shall be used as recipientIdentifier, but the given cert does contain the SubjectKeyIdentifier extension or the SubjectKeyIdentifier extension cannot be parsed
    
    java.lang.IllegalArgumentException - if the request recipientIdentifier type is not ISSUER_AND_SERIALNUMBER or SUBJECT_KEY_IDENTIFIER
  - KeyTransRecipientInfo
```
public KeyTransRecipientInfo(ASN1Object obj)
                      throws CodingException
```
    Creates a KeyTransRecipientInfo from an ASN1Object.
    The ASN1Object supplied to this constructor represents an already exisiting KeyTransRecipientInfo object that may have been created by calling toASN1Object.
    
    Parameters:
    
    obj - the KeyTransRecipientInfo 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 KeyTransRecipientInfo object for parsing the internal structure.
    This method internally is called when creating a CMS KeyTransRecipientInfoobject from an already existing KeyTransRecipientInfo object, supplied as ASN1Object.
    
    Parameters:
    
    obj - the CMS KeyTransRecipientInfo as ASN1Object
    
    Throws:
    
    CodingException - if the object can not be parsed
  - toASN1Object
```
public ASN1Object toASN1Object()
```
    Returns this KeyTransRecipientInfo as ASN1Object.
    The ASN1Object returned by this method represents the ASN.1 structure of a KeyTransRecipientInfo:
```
 KeyTransRecipientInfo ::= SEQUENCE {
    version                   CMSVersion, -- always set to 0 or 2
    rid                       RecipientIdentifier,
    keyEncryptionAlgorithm    KeyEncryptionAlgorithmIdentifier,
    encryptedKey              EncryptedKey }
 

 EncryptedKey ::= OCTET STRING
 

 RecipientIdentifier ::= CHOICE {
  issuerAndSerialNumber IssuerAndSerialNumber,
 subjectKeyIdentifier [0] SubjectKeyIdentifier }
 
```
    Returns:
    
    this KeyTransRecipientInfo as ASN1Object.
  - decryptKey
```
public javax.crypto.SecretKey decryptKey(java.security.Key privateKey,
                                         KeyIdentifier recipientIdentifier,
                                         java.lang.String kea)
                                  throws CMSException,
                                         java.security.InvalidKeyException
```
    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.
    
    Specified by:
    
    decryptKey in class RecipientInfo
    
    Parameters:
    
    privateKey - the private key of the recipient to be used for decrypting the encrypted content-encryption key.
    
    recipientIdentifier - an IssuerAndSerialNumber or SubjectKeyIdentifier identifying the recipient of this KeyTransRecipientInfo
    
    kea - The Key Encryption Algorithm as a String. Not Used.
    
    Returns:
    
    the recovered (decrypted) 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 KeyTransRecipientInfo 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 the given secret content-encryption key.
    All information (key encryption algorithm, public key of the recipient) has been supplied when creating this KeyTransRecipientInfo 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 algortihm used by this KeyTransRecipientInfo is not implemented, the public key of the recipient is Invalid, a padding error occurs,...)
  - getRecipientIdentifiers
```
public KeyIdentifier[] getRecipientIdentifiers()
```
    Gets the key identifier belonging to the recipient of this KeyTransRecipientInfo.
    This method implements the same named method of the abstract parent RecipientInfo class for returning an identifier of the recipient's certificate (and thereby public key) by issuer distinguished name and issuer-specific serial number, or SubjectKeyIdentifier. Since only one recipient is represented by a KeyTransRecipientInfo the KeyIdentifier array returned by this method only will contain one single KeyIdentifier object.
    
    Specified by:
    
    getRecipientIdentifiers in class RecipientInfo
    
    Returns:
    
    an KeyIdentifier array holding an identifier of the recipient's certificate (and thereby public key) by IssuerAndSerialNumber or SubjectKeyID
  - isRecipientInfoFor
```
public boolean isRecipientInfoFor(KeyIdentifier recipientIdentifier)
```
    Checks if this is a RecipientInfo for the recipient identified by the given key identifier.
    
    Specified by:
    
    isRecipientInfoFor in class RecipientInfo
    
    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 CertificateIdentifier isRecipientInfoFor(X509Certificate recipientCertificate)
```
    Checks if this is a RecipientInfo for the given recipient certficate.
    
    Specified by:
    
    isRecipientInfoFor in class RecipientInfo
    
    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
  - 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
  - getEncryptedKey
```
public byte[] getEncryptedKey(KeyIdentifier recipientIdentifier)
                       throws CMSException
```
    Returns the encrypted content-encryption key for the recipient with the given keyIdentfier.
    This method implements the same named method of the abstract parent RecipientInfo class for asking if this KeyTransRecipientInfo holds an encrypted key for the recipient identified by the given key identifier (IssuerAndSerialNumber or SubjectKeyIdentifier). Since a KeyTransRecipientInfo only represents one single recipient the supplied recipientIdentifier may be null.
    
    Specified by:
    
    getEncryptedKey in class RecipientInfo
    
    Parameters:
    
    recipientIdentifier - information to be used for getting the right encrypted content encryption key for the right recipient; may be not required for a KeyTransRecipientInfo, but for KeyAgreeRecipientInfo) which may hold encrypted content encryption keys for more than one recipient; may be null for only getting the encrypted content-encryption key included
    
    Returns:
    
    the encrypted content-encryption key for the recipient with the given key identifier
    
    Throws:
    
    CMSException - if this KeyTransRecipientInfo does not belong to the recipient with the given key identifier is included
  - toString
```
public java.lang.String toString()
```
    Returns a string giving some information about this KeyTransRecipientInfo object.
    
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    
    the string representation
  - makeClone
```
public RecipientInfo makeClone()
```
    Specified by:
    
    makeClone in class RecipientInfo

Class KeyTransRecipientInfo

Field Summary

Fields inherited from class iaik.cms.RecipientInfo

Constructor Summary

Method Summary

Methods inherited from class iaik.cms.RecipientInfo

Methods inherited from class java.lang.Object

Constructor Detail

KeyTransRecipientInfo

KeyTransRecipientInfo

KeyTransRecipientInfo

KeyTransRecipientInfo

KeyTransRecipientInfo

KeyTransRecipientInfo

Method Detail

decode

toASN1Object

decryptKey

encryptKey

getRecipientIdentifiers

isRecipientInfoFor

isRecipientInfoFor

getEncryptedKey

getEncryptedKey

toString

makeClone