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

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

All Implemented Interfaces:: ASN1Type

public class KEKRecipientInfo
extends RecipientInfo

This class implements the CMS KEKRecipientInfo type.

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

 KEKRecipientInfo ::= SEQUENCE {
    version                   CMSVersion, -- always set 4
    kekid                     KEKIdentifier,
    keyEncryptionAlgorithm    KeyEncryptionAlgorithmIdentifier,
    encryptedKey              EncryptedKey }
 

 EncryptedKey ::= OCTET STRING
 

 KEKIdentifier ::= SEQUENCE {   
   keyIdentifier OCTET STRING,
   date GeneralizedTime OPTIONAL,
   other OtherKeyAttribute OPTIONAL }

The kekid field specifies the recipient´s secret key encryption key by keyIdentifier and optional date and OtherKeyAttribute. The use of OtherKeyAttribute should be avoided because of interoperability reasons. The keyEncryptionAlgorithm field identifies the key wrap algorithm used for encrypting the randomly generated content-encryption key with a secret key encryption 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 KEKRecipientInfo object, obtaining the component values, and encrypting (respectively decrypting) the content-encryption key.

When creating a new KEKRecipientInfo you have to supply the KEKIdentifier identifying the secret key encryption key, the key encryption algorithm to be used and the key encryption key itself:

 // the KEK identifier:
 KEKIdentifier kekid = ...;
 // use DESede key wrap for encrypting (wrapping) the content encryption key:
 AlgorithmID kea = AlgorithmID.cms_3DES_wrap;
 // the key encryption key:
 SecretKey kek = ...;
 // create the KEKRecipientInfo:
 KEKRecipientInfo recipient = new KEKRecipientInfo(kekid, kea, kek);

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 key encryption key:
 SecretKey kek = ...;
 byte[] kekid = ...;
 // the KEK identifier:
 KEKIdentifier kekIdentifier = new KEKIdentifier(kekid);
 // use DESede key wrap for encrypting (wrapping) the content encryption key:
 AlgorithmID kea = AlgorithmID.cms_3DES_wrap;
 // create the KEKRecipientInfo:
 KEKRecipientInfo recipient = new KEKRecipientInfo(kekIdentifier, kea, kek);
 // 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(kek, kekIdentifier);
 // 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:: KEKIdentifier, 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
`KEKRecipientInfo()` Default Constructor.
`KEKRecipientInfo(ASN1Object obj)` Creates a `KEKRecipientInfo` from an ASN1Object.
`KEKRecipientInfo(KEKIdentifier kekid, AlgorithmID keyEA, byte[] encryptedKey)` Creates a `KEKRecipientInfo` object for the given kek identifier, key-encryption algorithm, and already encrypted content encryption key.
`KEKRecipientInfo(KEKIdentifier kekid, AlgorithmID keyEA, javax.crypto.SecretKey kek)` Creates a `KEKRecipientInfo` object for the given kek identifier, key-encryption algorithm and secret key encryption key.
`KEKRecipientInfo(KEKIdentifier kekid, AlgorithmID keyEA, javax.crypto.SecretKey kek, java.security.AlgorithmParameters params)` Creates a `KEKRecipientInfo` object for the given kek identifier, key-encryption algorithm and secret key encryption key.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`decode(ASN1Object obj)` Decodes the given ASN.1 `KEKRecipientInfo` object for parsing the internal structure.
`javax.crypto.SecretKey`	`decryptKey(java.security.Key kek, KeyIdentifier recipientIdentifier, java.lang.String cekAlgName)` Uses the given secret key encryption key to decrypt (unwrap) the encrypted (wrapped) content-encryption key.
`void`	`encryptKey(javax.crypto.SecretKey cek)` Encrypts (wraps) 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`	`getRecipientIdentifier()` Gets the key identifier belonging to the recipient of this KEKRecipientInfo.
`KeyIdentifier[]`	`getRecipientIdentifiers()` Gets the key identifier belonging to the recipient of this KEKRecipientInfo.
`boolean`	`isRecipientInfoFor(KeyIdentifier recipientIdentifier)` Checks if this is a RecipientInfo for the recipient identified by the given key identifier.
`CertificateIdentifier`	`isRecipientInfoFor(X509Certificate recipientCertificate)` Always returns `null` indicating that a KEKRecipientInfo does not use certificates.
`RecipientInfo`	`makeClone()`
`ASN1Object`	`toASN1Object()` Returns this `KEKRecipientInfo` as ASN1Object.
`java.lang.String`	`toString()` Returns a string giving some information about this `KEKRecipientInfo` 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
  - KEKRecipientInfo
```
public KEKRecipientInfo()
```
    Default Constructor. Creates an empty KEKRecipientInfo object and sets the version number to 4.
    Only used for dynamic object creation. Shall not be used by an application.
  - KEKRecipientInfo
```
public KEKRecipientInfo(KEKIdentifier kekid,
                        AlgorithmID keyEA,
                        byte[] encryptedKey)
```
    Creates a KEKRecipientInfo object for the given kek 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.
    Note: this constructor internally creates a clone of the supplied key-encryption AlgorithmID.
    
    Parameters:
    
    kekid - the KEKIdentifier identifying the key encryption key
    
    keyEA - the ID of the key-encryption (key-wrap) algorithm that has been used for encrypting the content-encryption key
    
    encryptedKey - the already encrypted secret content-encryption key
  - KEKRecipientInfo
```
public KEKRecipientInfo(KEKIdentifier kekid,
                        AlgorithmID keyEA,
                        javax.crypto.SecretKey kek,
                        java.security.AlgorithmParameters params)
```
    Creates a KEKRecipientInfo object for the given kek identifier, key-encryption algorithm and secret key encryption key.
    Note: this constructor internally creates a clone of the supplied key-encryption AlgorithmID.
    
    Parameters:
    
    kekid - the KEKIdentifier identifying the key encryption key
    
    keyEA - the ID of the key-encryption (key-wrap) algorithm to be used for encrypting the content-encryption key
    
    kek - the secret key encryption key to be used for encrypting the content-encryption key
    
    params - any algorithm parameters to be used for intializing the key wrap cipher
  - KEKRecipientInfo
```
public KEKRecipientInfo(KEKIdentifier kekid,
                        AlgorithmID keyEA,
                        javax.crypto.SecretKey kek)
```
    Creates a KEKRecipientInfo object for the given kek identifier, key-encryption algorithm and secret key encryption key.
    Note: this constructor internally creates a clone of the supplied key-encryption AlgorithmID.
    
    Parameters:
    
    kekid - the KEKIdentifier identifying the key encryption key
    
    keyEA - the ID of the key-encryption (key-wrap) algorithm to be used for encrypting the content-encryption key
    
    kek - the secret key encryption key to be used for encrypting the content-encryption key
  - KEKRecipientInfo
```
public KEKRecipientInfo(ASN1Object obj)
                 throws CodingException
```
    Creates a KEKRecipientInfo from an ASN1Object.
    The ASN1Object supplied to this constructor represents an already exisiting KEKRecipientInfo object that may have been created by calling toASN1Object.
    
    Parameters:
    
    obj - the KEKRecipientInfo 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 KEKRecipientInfo object for parsing the internal structure.
    This method internally is called when creating a CMS KEKRecipientInfoobject from an already existing KEKRecipientInfo object, supplied as ASN1Object.
    
    Parameters:
    
    obj - the CMS KEKRecipientInfo as ASN1Object
    
    Throws:
    
    CodingException - if the object can not be parsed
  - toASN1Object
```
public ASN1Object toASN1Object()
```
    Returns this KEKRecipientInfo as ASN1Object.
    The ASN1Object returned by this method represents the ASN.1 structure of a KEKRecipientInfo:
```
 KEKRecipientInfo ::= SEQUENCE {
    version                   CMSVersion, -- always set to 0 or 4
    kekid                     KEKIdentifier,
    keyEncryptionAlgorithm    KeyEncryptionAlgorithmIdentifier,
    encryptedKey              EncryptedKey }
 

 EncryptedKey ::= OCTET STRING
 

 KEKIdentifier ::= SEQUENCE {   
   keyIdentifier OCTET STRING,
   date GeneralizedTime OPTIONAL,
   other OtherKeyAttribute OPTIONAL }
 
```
    Returns:
    
    this KEKRecipientInfo as ASN1Object.
  - decryptKey
```
public javax.crypto.SecretKey decryptKey(java.security.Key kek,
                                         KeyIdentifier recipientIdentifier,
                                         java.lang.String cekAlgName)
                                  throws CMSException,
                                         java.security.InvalidKeyException
```
    Uses the given secret key encryption key to decrypt (unwrap) the encrypted (wrapped) 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 KEKRecipientInfo only represents one single recipient the supplied recipientIdentifier may be null.
    
    Specified by:
    
    decryptKey in class RecipientInfo
    
    Parameters:
    
    kek - the secret key encryption key to be used for decrypting (unwrapping) the encrypted (wrapped) content-encryption key.
    
    recipientIdentifier - an KEKIdentifier identifying the recipient of this KEKRecipientInfo
    
    cekAlgName - the Name of the content encryption key
    
    Returns:
    
    the recovered (decrypted) key as SecretKey
    
    Throws:
    
    CMSException - if the key-decryption process fails for some reason (e.g. the key-encryption algorithm used by this KEKRecipientInfo 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 (wraps) the given secret content-encryption key.
    All information (key encryption algorithm, key encryption key) required has been supplied when creating this KEKRecipientInfo 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 KEKRecipientInfo is not implemented, the key encryption key is invalid, a padding error occurs,...)
  - getRecipientIdentifier
```
public KeyIdentifier getRecipientIdentifier()
```
    Gets the key identifier belonging to the recipient of this KEKRecipientInfo.
    
    Returns:
    
    an the recipient identifier identifying the key of the recipient
  - getRecipientIdentifiers
```
public KeyIdentifier[] getRecipientIdentifiers()
```
    Gets the key identifier belonging to the recipient of this KEKRecipientInfo.
    This method implements the same named method of the abstract parent RecipientInfo class for returning an identifier for the recipient´s key encryption (decryption) key. Since only one recipient is represented by a KEKRecipientInfo the KeyIdentifier array returned by this method only will contain one single KEKIdentifier object.
    
    Specified by:
    
    getRecipientIdentifiers in class RecipientInfo
    
    Returns:
    
    an KeyIdentifier array holding an identifier for the recipient's key encryption (decryption) key
  - 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)
```
    Always returns null indicating that a KEKRecipientInfo does not use certificates.
    This method only implements the same-name abstract method of the parent abstract class RecipientInfo. Since a KEKRecipientInfo uses a secret key for en/decrypting the content-ecncryption key this method always return null indicating that this KEKRecipientInfo cannot belong to the recipient with the given recipient certificate.
    
    Specified by:
    
    isRecipientInfoFor in class RecipientInfo
    
    Parameters:
    
    recipientCertificate - the certificate of the recipient in mind
    
    Returns:
    
    null indicating that this KEKRecipientInfo cannot belong to the recipient with the given certificate
  - getEncryptedKey
```
public byte[] getEncryptedKey()
```
    Returns the encrypted content-encryption 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 KEKRecipientInfo holds an encrypted key for the recipient identified by the given key identifier. Since a KEKRecipientInfo 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 KEKRecipientInfo, 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 KEKRecipientInfo 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 KEKRecipientInfo object.
    
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    
    the string representation
  - makeClone
```
public RecipientInfo makeClone()
```
    Specified by:
    
    makeClone in class RecipientInfo

Class KEKRecipientInfo

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

KEKRecipientInfo

KEKRecipientInfo

KEKRecipientInfo

KEKRecipientInfo

KEKRecipientInfo

Method Detail

decode

toASN1Object

decryptKey

encryptKey

getRecipientIdentifier

getRecipientIdentifiers

isRecipientInfoFor

isRecipientInfoFor

getEncryptedKey

getEncryptedKey

toString

makeClone