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

java.lang.Object
- iaik.cms.EnvelopedDataStream

All Implemented Interfaces:

ContentStream, EOFListener, java.util.EventListener

Direct Known Subclasses:

EnvelopedData, SMimeEncrypted
```
public class EnvelopedDataStream
extends java.lang.Object
implements ContentStream, EOFListener
```
This class represents the stream-supporting implementation of the CMS content type EnvelopedData.
Each CMS content type is associated with a specific object identifier, derived from:
```
 pkcs-7 OBJECT IDENTIFIER ::=
   { iso(1) member-body(2) US(840) rsadsi(113549)
       pkcs(1) 7 }
 
```
The object identifier for the EnvelopedData content type is defined as:
envelopedData OBJECT IDENTIFIER ::= { pkcs-7 3 }
which corresponds to the OID string "1.2.840.1.113549.1.7.3".
The CMS Cryptographic Message Syntax (RFC 2630) specifies the EnvelopedData content type for providing a syntax for building digital envelopes. Content of any type may be enveloped for any number of recipients in parallel. For each recipient, a commonly at random generated content-encryption key is encrypted with the particular recipient´s key and - together with recipient-specific information - collected into a RecipientInfo value. The content is encrypted with the content-encryption key giving a EncryptedContent value, which - in combination with a recipient-specific encrypted content-encryption key - forms the digital envelope for each particular recipient. All RecipientInfo values are collected together with the encrypted content into anEnvelopedData value to be sent to each intended recipient.
This class implements the EnvelopedData structure resulting from the last step described above. The EnvelopedData type is defined as ASN.1 SEQUENCE type containing the following components (see RFC 2630:
```
 EnvelopedData ::= SEQUENCE {
   version                CMSVersion,
   originatorInfo     [0] IMPLICIT OriginatorInfo OPTIONAL,
   recipientInfos         RecipientInfos,
   encryptedContentInfo   EncryptedContentInfo 
   unprotectedAttrs   [1] IMPLICIT UnptotectedAttributes OPTIONAL }
 

 OriginatorInfo ::= SEQUENCE {
   certs [0] IMPLICIT CertificateSet OPTIONAL,
   crls [1] IMPLICIT CertificateRevocationLists OPTIONAL }
 

 RecipientInfos ::= SET OF RecipientInfo
 

 EncryptedContentInfo ::= SEQUENCE {
   contentType                 ContentType,
   contentEncryptionAlgorithm  ContentEncryptionAlgorithmIdentifier,
   encryptedContent        [0] IMPLICIT EncryptedContent OPTIONAL }
 

 EncryptedContent ::= OCTET STRING
 

 UnprotectedAttributes ::= SET SIZE (1..MAX) OF Attribute
 
```
The recipientInfos field is a non-empty collection of per-recipient information. The encryptedContentInfo field specifies the type of the content being enveloped, the content-encryption algorithm (the same for all recipients) used for encrypting the content, and the result of the content encryption. If the encrypted content value is not present in the encryptedContent field, it has to be supplied by other means.
CMS provides three alternatives for encrypting the content depending on the key management algorithm used to protect the content encryption key for a specific recipient:

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.
password
the content-encryption key is encrypted with a symmetric key derived from a password. The RecipientInfo is of type PasswordRecipientInfo using a CMS algorithm like Triple-DES key wrap or RC2 key wrap.
The optional originatorInfo field may be used to include certificate/CRL information about the originator if required by the key management protocol. unprotectedAttrs optionally may provide some attributes that are not encrypted.
A recipient, when receiving the EnvelopedData message, decrypts the corresponding encrypted content-encryption key with his/her key according the right key management protocol for subsequently decrypting the encrypted content using the content-encryption key just recovered. The recipient's key is referenced by proper KeyIdentifier included in the corresponding RecipientInfo object.
See RFC 2630 for more information.

When creating a new EnvelopedDataStream object for the data to be enveloped the symmetric algorithm has to be specified to be used for content-encryption. After setting the recipients, the EnvelopedDataStream object may be encoded and written to an output stream by using a proper writeTo method, e.g.:
1. Create a new EnvelopedDataStream object and specify the content encryption algorithm to be used by means of the EnvelopedDataStream(InputStream is, AlgorithmID contentEA) constructor. Calling this constructor internally will generate the temporary content-encryption key for the specified content-encryption algorithm. If using a content-encryption algorithm allowing keys of different size, you may specify the key length by using the EnvelopedDataStream(InputStream is, AlgorithmID contentEA, int keyLength) constructor.
```
     //the data to be enveloped supplied from an input stream:
     InputStream dataStream = ...;
     //use TripleDES in CBC mode for encrypting the content
     EnvelopedDataStream enveloped_data = new EnvelopedDataStream(dataStream, AlgorithmID.des_EDE3_CBC);
     
```
2. For each intended recipient, create a RecipientInfo object of requested type (KeyTransRecipientInfo, KeyAgreeRecipientInfo, KEKRecipientInfo or PasswordRecipientInfo), and add all RecipientInfos to the EnvelopedDataStream object by calling the setRecipientInfos method, e.g. (assuming to use KeyTransRecipientInfos for two recipients with corresponding certificates cert1 and cert2):
```
     RecipientInfo[] recipients = new RecipientInfo[2];
     recipients[0] = new KeyTransRecipientInfo(cert1, AlgorithmID.rsaEncryption);
     recipients[1] = new KeyTransRecipientInfo(cert2, AlgorithmID.rsaEncryption);
     enveloped_data.setRecipientInfos(recipients);
     
```
3. Use a proper writeTo method for BER encoding the EnvelopedData object and writing it to an output stream. You optionally may specify a particular block size for splitting the encoding of encrypted content. This step also will perform the encryption of the symmetric content-encryption key for each participated recipient.
```
     int blockSize = ...;
     OutputStream encoded_stream = ...;
     enveloped_data.writeTo(encoded_stream, blockSize);
     
```
  respectively
```
     enveloped_data.writeTo(encoded_stream);
     
```
  It is recommended only to use the writeTo method where a particular block size can be specified, because it is the intended purpose of this stream-supporting EnvelopedData implementation to handle large amounts of data. When no block size is specified whole the encrypted content is encoded as primitive definite octet string, which advantageously may be done when using the non-stream supporting EnvelopedData implementation. When a positive block size is specified for encoding the EnvelopedData to a stream, the encrypted content is BER encoded as indefinite constructed octet string being composed of a series of definite primitive encoded octet strings of blockSize length:
```
     0x24 0x80
               0x04 <blocksize> <first encrypted content block>
               0x04 <blocksize> <second encrypted content block>
               0x04 <blocksize> <third encrypted content block>
                   ...
     0x00 0x00
     
```
  instead of:
```
     0x04 <length> <encrypted content>
     
```
  The indefinite constructed encoding scheme also may be preferable when intending to be compatible to the encoding practice of some particular application (for instance some versions of Netscape Navigator).
A recipient, when receiving a EnvelopedDataStream encoding, uses the EnvelopedDataStream(InputStream is) constructor for parsing the internal structure. Before reading the recovered content by means of the getInputStream method, the cipher has to be initialized for decryption with the particular recipient´s key by calling one of the following setupCipher methods:
- setupCipher(Key recipientKey, int recipientInfoIndex): This method can be used for decrypting the encrypted content-encryption key for a RecipientInfo of any type; however, you must know the right index into the recipientInfo field. The recovered content-encryption key is used for setting up the cipher to decrypt the encrypted content.
- setupCipher(Key recipientKey, KeyIdentifier recipientKeyIdentifier): This method can be used for decrypting the encrypted content-encryption key for a RecipientInfo of any type; the recipient is identified by its RecipientKeyIdentifier. The recovered content-encryption key is used for setting up the cipher to decrypt the encrypted content.
- setupCipher(Key recipientKey, X509Certificate recipientCertificate): This method only can be used for decrypting the encrypted content-encryption key for a RecipientInfo of type KeyTransRecipientInfo or KeyAgreeRecipientInfo; the recipient is identified by its public key certificate. The recovered content-encryption key is used for setting up the cipher to decrypt the encrypted content.
- setupCipher(Key): In contrast to the three setupCipher above you have to supply the already decrypted content-encryption key when setting up the cipher for content encryption using this setupCipher method.
Since in our example both recipients use a RecipientInfo of type KeyTransRecipientInfo, we can use any of the setupCipher methods to setup the cipher for decrypting the encrypted content-encryption key and the encrypted content:
1. Create an EnvelopedDataStream structure from the supplied encoding, decode and parse the internal structure:
```
     EnvelopedDataStream enveloped_data = new EnvelopedDataStream(encoded_stream);
     
```
2. 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());
     
```
3. Get information about the included RecipientInfos:
```
     RecipientInfo[] recipients = enveloped_data.getRecipientInfos();
     System.out.println("Included RecipientInfos:");
     for (int i=0; i < recipients.length; i++) {
        System.out.print("Recipient "+(i+1)+":");
        System.out.println(recipients[i]);
     }
     
```
4. Use some recipient´s specific key to decrypt the inherent encrypted secret key to be used for initializing the cipher for encrypted-content decryption:
```
     // the private key of recipient 1:
     Key privateKey = ...;
     //setup cipher for recipient 1:
     int recipientInfoIndex = 0;
     enveloped_data.setupCipher(privateKey, recipientInfoIndex);
     
```
  Unlike the non-stream supporting EnvelopedData class where the encrypted-content decryption already is performed inside the setupCipher method, the cipher will be only initialized for decryption in this class. The encrypted-content decryption actually is done during reading the data obtained by calling the getInputStream method. So don´t call getInputStream before setting up the cipher!
5. Get and read the recovered content:
```
     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:
RecipientInfo, KeyTransRecipientInfo, KeyAgreeRecipientInfo, KEKRecipientInfo, PasswordRecipientInfo, EncryptedContentInfoStream

Field Summary

Fields
Modifier and Type	Field and Description
`protected int`	`blockSize_` The block size for block oriented stream encoding.
`protected EncryptedContentInfoStream`	`encryptedContentInfo_` The EncryptedContentInfo for the encrypted content.
`protected DerInputStream`	`m_envelopedData` An `InputStream` holding the enveloped data.
`protected OriginatorInfo`	`originatorInfo_` The optional OriginatorInfo.
`protected java.util.Vector<RecipientInfo>`	`recipientInfos_` Repository for the RecipientInfos.
`protected javax.crypto.SecretKey`	`symmetricKey_` The secret content encryption key.
`protected Attribute[]`	`unprotectedAttrs_` Optional unprotected attributes.
`protected int`	`version_` The version number; default 0.

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`EnvelopedDataStream()` Default constructor for dynamic object creation in ContentInfoStream.
	`EnvelopedDataStream(java.io.InputStream is)` Creates a new EnvelopedDataStream where the BER encoded data is read from the given InputStream.
	`EnvelopedDataStream(java.io.InputStream is, AlgorithmID contentEA)` Creates a new EnvelopedDataStream object where the content to be enveloped is read from the supplied InputStream.
	`EnvelopedDataStream(java.io.InputStream is, AlgorithmID contentEA, int keyLength)` Creates a new EnvelopedDataStream object where the content to be enveloped is read from the supplied InputStream.
	`EnvelopedDataStream(ObjectID contentType, java.io.InputStream is, AlgorithmID contentEA)` Creates a new EnvelopedDataStream object where the content to be enveloped is read from the supplied InputStream.
	`EnvelopedDataStream(ObjectID contentType, java.io.InputStream is, AlgorithmID contentEA, int keyLength)` Creates a new EnvelopedDataStream object where the content to be enveloped is read from the supplied InputStream.
	`EnvelopedDataStream(RecipientInfo[] recipients, EncryptedContentInfoStream encryptedCI)` Constructs an EnvelopedDataStream object with an already created EncryptedContentInfoStream.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`addRecipientInfo(RecipientInfo recipient)` Adds one recipient to the list of recipient infos.
`void`	`decode(java.io.InputStream is)` Reads and decodes an BER encoded EnvelopedData from a the given input stream.
`int`	`getBlockSize()` Gets the block size defining the length of each definite primitive encoded octet string component.
`ObjectID`	`getContentType()` Returns the content type this class implements.
`EncryptedContentInfoStream`	`getEncryptedContentInfo()` Returns the EncryptedContentInfo included in this `EnvelopedDataStream` object.
`java.io.InputStream`	`getInputStream()` Returns an InputStream from where the decrypted data can be read.
`OriginatorInfo`	`getOriginatorInfo()` Gets the OriginatorInfo, if included.
`RecipientInfo`	`getRecipientInfo(KeyIdentifier recipientIdentifier)` Returns the RecipientInfo belonging to the recipient identified by the given recipient identifier.
`RecipientInfo`	`getRecipientInfo(X509Certificate recipientCertificate)` Returns the recipient info matching to the supplied recipient certificate.
`RecipientInfo[]`	`getRecipientInfos()` Returns all the recipient infos included in this `EnvelopedData` object.
`Attribute`	`getUnprotectedAttribute(ObjectID oid)` Returns the first unprotected attribute matching to the given ObjectID, if included in this EnvelopedData object.
`Attribute[]`	`getUnprotectedAttributes()` Gets the unprotected attributes included in this EnvelopedData.
`int`	`getVersion()` Returns the syntax version number.
`void`	`notifyEOF()` This method implements the EOFListener interface to preform the final stage of decoding, once the 'encryptedContentInfo' has been completely decoded.
`void`	`setBlockSize(int blockSize)` Sets the block size for defining the length of each definite primitive encoded octet string component.
`void`	`setOriginatorInfo(OriginatorInfo originatorInfo)` Sets the optional OriginatorInfo.
`void`	`setRecipientInfos(RecipientInfo[] recipients)` Sets the recipient infos.
`void`	`setUnprotectedAttributes(Attribute[] attributes)` Sets a set of (unprotected) attributes.
`void`	`setupCipher(java.security.Key key)` Uses the given symmetric key to setup the cipher for decrypting the content.
`void`	`setupCipher(java.security.Key recipientKey, int recipientInfoIndex)` Uses the specified key for decrypting the content-encryption key to setup the cipher for decrypting the encrypted content of this `EnvelopedDataStream` object for the requesting recipient, specified by its `recipientInfoIndex`.
`void`	`setupCipher(java.security.Key recipientKey, KeyIdentifier recipientIdentifier)` Uses the specified key for decrypting the content-encryption key to setup the cipher for decrypting the encrypted content of this `EnvelopedDataStream` object for the requesting recipient, specified by the given recipient identifier.
`void`	`setupCipher(java.security.Key recipientKey, X509Certificate recipientCertificate)` Uses the specified key for decrypting the content-encryption key to setup the cipher for decrypting the encrypted content of this `EnvelopedDataStream` object for the requesting recipient, specified by the given recipient certificate.
`void`	`setupCipher(SecureStringBuffer password, int recipientInfoIndex)` Uses the specified password to derive a key for decrypting the content-encryption key to setup the cipher for decrypting the encrypted content of this `EnvelopedDataStream` object for the requesting recipient, specified by its `recipientInfoIndex`.
`void`	`setupCipher(SecureStringBuffer password, RecipientInfo recipient)` Uses the specified password to derive a key for decrypting the content-encryption key to setup the cipher for decrypting the encrypted content of this `EnvelopedDataStream` object for the requesting recipient, specified by its `recipientInfoIndex`.
`ASN1Object`	`toASN1Object()` Returns this EnvelopedDataStream as ASN1Object.
`protected ASN1Object`	`toASN1Object(int blockSize)` Returns this EnvelopedData as ASN1Object.
`java.lang.String`	`toString()` Returns a string giving some information about this `EnvelopedData` object.
`java.lang.String`	`toString(boolean detailed)` Returns a string giving some - if requested - detailed information about this `EnvelopedData` object.
`void`	`writeTo(java.io.OutputStream os)` BER encoded this EnvelopedData and writes the encoding to the supplied output stream.
`void`	`writeTo(java.io.OutputStream os, int blockSize)` Writes the BER encoding of this EnvelopedData to the supplied output stream where a constructed OCTET STRING may be used for encoding the content.

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

- Field Detail
  - version_
```
protected int version_
```
    The version number; default 0.
  - originatorInfo_
```
protected OriginatorInfo originatorInfo_
```
    The optional OriginatorInfo.
  - recipientInfos_
```
protected java.util.Vector<RecipientInfo> recipientInfos_
```
    Repository for the RecipientInfos.
  - encryptedContentInfo_
```
protected EncryptedContentInfoStream encryptedContentInfo_
```
    The EncryptedContentInfo for the encrypted content.
  - symmetricKey_
```
protected javax.crypto.SecretKey symmetricKey_
```
    The secret content encryption key.
  - blockSize_
```
protected int blockSize_
```
    The block size for block oriented stream encoding.
  - unprotectedAttrs_
```
protected Attribute[] unprotectedAttrs_
```
    Optional unprotected attributes.
  - m_envelopedData
```
protected DerInputStream m_envelopedData
```
    An InputStream holding the enveloped data.
- Constructor Detail
  - EnvelopedDataStream
```
protected EnvelopedDataStream()
```
    Default constructor for dynamic object creation in ContentInfoStream.
  - EnvelopedDataStream
```
public EnvelopedDataStream(java.io.InputStream is,
                   AlgorithmID contentEA)
                    throws java.security.NoSuchAlgorithmException
```
    Creates a new EnvelopedDataStream object where the content to be enveloped is read from the supplied InputStream.
    The content type is set to CMS Data.
    When using this constructor, automatically a temporary symmetric key for content encryption is generated. If using a content-encryption algorithm allowing keys of different size, you may specify the key length by using the EnvelopedDataStream(InputStream is, AlgorithmID contentEA, int keyLength) constructor.
    Note that the supplied contentEA AlgorithmID internally is cloned.
    
    Parameters:
    is - the InputStream supplying the data to be enveloped
    contentEA - the content encryption algorithm for encrypting the content
    
    Throws:
    
    java.security.NoSuchAlgorithmException - if there is no implementation for the specified algorithm
  - EnvelopedDataStream
```
public EnvelopedDataStream(ObjectID contentType,
                   java.io.InputStream is,
                   AlgorithmID contentEA)
                    throws java.security.NoSuchAlgorithmException
```
    Creates a new EnvelopedDataStream object where the content to be enveloped is read from the supplied InputStream.
    When using this constructor, automatically a temporary symmetric key for content encryption is generated. If using a content-encryption algorithm allowing keys of different size, you may specify the key length by using the EnvelopedDataStream(ObjectID contentType, InputStream is, AlgorithmID contentEA, int keyLength) constructor.
    Note that the supplied contentEA AlgorithmID internally is cloned.
    
    Parameters:
    contentType - the content type of the content to be enveloped
    is - the InputStream containing the data to envelope
    contentEA - the content encryption algorithm for encrypting the content
    
    Throws:
    
    java.security.NoSuchAlgorithmException - if there is no implementation for the specified algorithm
  - EnvelopedDataStream
```
public EnvelopedDataStream(java.io.InputStream is,
                   AlgorithmID contentEA,
                   int keyLength)
                    throws java.security.NoSuchAlgorithmException
```
    Creates a new EnvelopedDataStream object where the content to be enveloped is read from the supplied InputStream.
    The content type is set to CMS Data.
    When using this constructor, automatically a symmetric key for content encryption is generated. If the specified content encryption algorithm supports variable key lengths, a particular key length may be set by means of the keyLength parameter. If no length is specified, the defined default key length will be used. If the algorithm only works with keys of fixed-size length, the keyLength parameter may be set to -1 or the EnvelopedDataStream(InputStream is, AlgorithmID contentEA) constructor may be used.
    Note that the supplied contentEA AlgorithmID internally is cloned.
    
    Parameters:
    is - the InputStream containing the data to envelope
    contentEA - the content encryption algorithm for encrypting the content
    keyLength - the key length that may be set when using a content encryption algorithm that supports variable key lengths
    
    Throws:
    
    java.security.NoSuchAlgorithmException - if there is no implementation for the specified algorithm
  - EnvelopedDataStream
```
public EnvelopedDataStream(ObjectID contentType,
                   java.io.InputStream is,
                   AlgorithmID contentEA,
                   int keyLength)
                    throws java.security.NoSuchAlgorithmException
```
    Creates a new EnvelopedDataStream object where the content to be enveloped is read from the supplied InputStream.
    When using this constructor, automatically a symmetric key for content encryption is generated. If the specified content encryption algorithm supports variable key lengths, a particular key length may be set by means of the keyLength parameter. If no length is specified, the defined default key length will be used. If the algorithm only works with keys of fixed-size length, the keyLength parameter may be set to -1 or the EnvelopedDataStream(ObjectID contentType, InputStream is, AlgorithmID contentEA) constructor may be used.
    Note that the supplied contentEA AlgorithmID internally is cloned.
    
    Parameters:
    contentType - the content type of the content to be enveloped
    is - the InputStream containing the data to envelope
    contentEA - the content encryption algorithm for encrypting the content
    keyLength - the key length that may be set when using a content encryption algorithm that supports variable key lengths
    
    Throws:
    
    java.security.NoSuchAlgorithmException - if there is no implementation for the specified algorithm
  - EnvelopedDataStream
```
public EnvelopedDataStream(RecipientInfo[] recipients,
                   EncryptedContentInfoStream encryptedCI)
```
    Constructs an EnvelopedDataStream object with an already created EncryptedContentInfoStream.
    The given array of RecipientInfo specifies a collection of per-recipient information, and the given EncryptedContentInfoStream supplies the already encrypted content.
    
    Parameters:
    recipients - information about the recipients
    encryptedCI - the encrypted content info
  - EnvelopedDataStream
```
public EnvelopedDataStream(java.io.InputStream is)
                    throws CMSParsingException,
                           java.io.IOException
```
    Creates a new EnvelopedDataStream where the BER encoded data is read from the given InputStream.
    
    Parameters:
    is - the InputStream supplying a BER encoded CMS EnvelopedData object
    
    Throws:
    
    java.io.IOException - if an I/O error occurs during reading from the InputStream
    
    CMSParsingException - if an error occurs while parsing the object
- Method Detail
  - decode
```
public void decode(java.io.InputStream is)
            throws java.io.IOException,
                   CMSParsingException
```
    Reads and decodes an BER encoded EnvelopedData from a the given input stream.
    
    Specified by:
    
    decode in interface ContentStream
    
    Parameters:
    is - the InputStream holding a BER encoded EnvelopedData object
    
    Throws:
    
    java.io.IOException - if an I/O error occurs during reading from the InputStream
    
    CMSParsingException - if an error occurs while parsing the object
  - getContentType
```
public ObjectID getContentType()
```
    Returns the content type this class implements.
    Use getEncryptedContentInfo().getContentType() for getting the type the encrypted content represents.
    
    Specified by:
    
    getContentType in interface ContentStream
    
    Returns:
    ObjectID.cms_envelopedData
  - setOriginatorInfo
```
public void setOriginatorInfo(OriginatorInfo originatorInfo)
```
    Sets the optional OriginatorInfo.
    The originatorInfo may be set for including certificates and/or certificate revocation lists for the originator if required by the key management algorithm used.
    
    Parameters:
    originatorInfo - the OriginatorInfo to be set
  - setRecipientInfos
```
public void setRecipientInfos(RecipientInfo[] recipients)
```
    Sets the recipient infos.
    Any RecipientInfo added supplies recipient-specific information used for identifying the key of the recipient to be used for en/decrypting the content.
    
    Parameters:
    recipients - a collection of per-recipient information
    See Also:
    RecipientInfo, KeyTransRecipientInfo, KeyAgreeRecipientInfo, KEKRecipientInfo
  - addRecipientInfo
```
public void addRecipientInfo(RecipientInfo recipient)
```
    Adds one recipient to the list of recipient infos.
    Any RecipientInfo added supplies recipient-specific information used for identifying the key of the recipient to be used for en/decrypting the content.
    
    Parameters:
    recipient - the RecipientInfo to be added
    See Also:
    RecipientInfo, KeyTransRecipientInfo, KeyAgreeRecipientInfo, KEKRecipientInfo, PasswordRecipientInfo
  - setUnprotectedAttributes
```
public void setUnprotectedAttributes(Attribute[] attributes)
```
    Sets a set of (unprotected) attributes.
    
    Parameters:
    attributes - the unprotected attributes to be set
  - setBlockSize
```
public void setBlockSize(int blockSize)
```
    Sets the block size for defining the length of each definite primitive encoded octet string component. If the value of blockSize is smaller or equal to zero the whole encrypted data is encoded as definite primitive octet string.
    
    Specified by:
    
    setBlockSize in interface ContentStream
    
    Parameters:
    blockSize - for defining the encoding scheme and setting the octet string component length, if positive
  - getBlockSize
```
public int getBlockSize()
```
    Gets the block size defining the length of each definite primitive encoded octet string component. If the value of blockSize is smaller or equal to zero the whole data is encoded as definite primitive octet string.
    
    Specified by:
    
    getBlockSize in interface ContentStream
    
    Returns:
    the block size defining the encoding scheme and setting the octet string component length, if positive
  - setupCipher
```
public void setupCipher(java.security.Key recipientKey,
               int recipientInfoIndex)
                 throws CMSException,
                        java.security.NoSuchAlgorithmException,
                        java.security.InvalidKeyException
```
    Uses the specified key for decrypting the content-encryption key to setup the cipher for decrypting the encrypted content of this EnvelopedDataStream object for the requesting recipient, specified by its recipientInfoIndex.
    This method first uses the given key for decrypting the encrypted temporary symmetric key obtained from the corresponding RecipientInfo structure, and subsequently uses this key to initialize a CipherInputStream for decrypting the inherent encrypted content.
    Unlike the non-stream supporting EnvelopedData class where the encrypted-content decryption already is performed inside the setupCipher method, the cipher will be only initialized for decrypting in this class. The encrypted-content decryption actually is done during reading the data obtained by calling the getInputStream method. So don´t call getInputStream before setting up the cipher!
    Note that you have to know the right index into the recipientInfos field when using this method for setting up the cipher for decryption. You may search for the index by using one of the getRecipientInfo methods thereby identifying the recipient by its keyIdentifier or -- if suitable for the key management algorithm used -- certificate.
    However, when having some recipient using a key agreement protocol the corresponding RecipientInfo is of type KeyAgreeRecipientInfo which may hold encrypted content-encryption keys for more than only one recipients using the same key agreement algorithm with same domain parameters. Since this setupCipher method only can get the KeyAgreeRecipientInfo with the given index (but not search for the right recipient in the KeyAgreeRecipientInfo), it will step through any recipient included in the KeyAgreeRecipientInfo trying to decrypt the encrypted content-encryption key with the supplied key. This may give some overhead so it might be appropriate to use another setupCipher method allowing to immediately identify the particular recipient in mind by its #setupCipher(Key, KeyIdentifier) keyIdentifier} or certificate.
    
    Parameters:
    recipientKey - the key of the recipient to be used for decrypting the encrypted content-encryption key.
    recipientInfoIndex - the index into the recipientInfos field
    
    Throws:
    
    CMSException - if there occurs an error while decrypting the content-encryption key or setting up the cipher for decrypting the content
    
    java.security.NoSuchAlgorithmException - if there is no implementation of the content-encryption algorithm
    
    java.security.InvalidKeyException - if the specified private key is not valid
  - setupCipher
```
public void setupCipher(SecureStringBuffer password,
               int recipientInfoIndex)
                 throws java.lang.Exception
```
    Uses the specified password to derive a key for decrypting the content-encryption key to setup the cipher for decrypting the encrypted content of this EnvelopedDataStream object for the requesting recipient, specified by its recipientInfoIndex.
    This method first uses the given password to derive a key for decrypting the encrypted temporary symmetric key obtained from the corresponding RecipientInfo structure, and subsequently uses this key to initialize a CipherInputStream for decrypting the inherent encrypted content.
    Unlike the non-stream supporting EnvelopedData class where the encrypted-content decryption already is performed inside the setupCipher method, the cipher will be only initialized for decrypting in this class. The encrypted-content decryption actually is done during reading the data obtained by calling the getInputStream method. So don´t call getInputStream before setting up the cipher!
    Note that you have to know the right index into the recipientInfos field when using this method for setting up the cipher for decryption. You may search for the index by using one of the getRecipientInfo methods thereby identifying the recipient by its isPasswordRequired. You can also invoke setupCipher
    
    Parameters:
    password - the password to use to derive the key to be used for decrypting the encrypted content-encryption key.
    recipientInfoIndex - the index into the recipientInfos field
    
    Throws:
    
    java.lang.Exception
  - setupCipher
```
public void setupCipher(SecureStringBuffer password,
               RecipientInfo recipient)
                 throws java.lang.Exception
```
    Uses the specified password to derive a key for decrypting the content-encryption key to setup the cipher for decrypting the encrypted content of this EnvelopedDataStream object for the requesting recipient, specified by its recipientInfoIndex.
    This method first uses the given password to derive a key for decrypting the encrypted temporary symmetric key obtained from the corresponding RecipientInfo structure, and subsequently uses this key to initialize a CipherInputStream for decrypting the inherent encrypted content.
    Unlike the non-stream supporting EnvelopedData class where the encrypted-content decryption already is performed inside the setupCipher method, the cipher will be only initialized for decrypting in this class. The encrypted-content decryption actually is done during reading the data obtained by calling the getInputStream method. So don´t call getInputStream before setting up the cipher!
    
    Parameters:
    password - the password to use to derive the key to be used for decrypting the encrypted content-encryption key.
    recipient - the Password Recipient info
    
    Throws:
    
    java.lang.Exception
  - setupCipher
```
public void setupCipher(java.security.Key recipientKey,
               KeyIdentifier recipientIdentifier)
                 throws CMSException,
                        java.security.NoSuchAlgorithmException,
                        java.security.InvalidKeyException
```
    Uses the specified key for decrypting the content-encryption key to setup the cipher for decrypting the encrypted content of this EnvelopedDataStream object for the requesting recipient, specified by the given recipient identifier.
    This method first uses the given key for decrypting the encrypted temporary symmetric key obtained from the corresponding RecipientInfo structure, and subsequently uses this key to initialize a CipherInputStream for decrypting the inherent encrypted content.
    Unlike the non-stream supporting EnvelopedData class where the encrypted-content decryption already is performed inside the setupCipher method, the cipher will be only initialized for decrypting in this class. The encrypted-content decryption actually is done during reading the data obtained by calling the getInputStream method. So don´t call getInputStream before setting up the cipher!
    This setupCipher can be used to setup the cipher for decryption for any type of RecipientInfo. The supplied recipient identifier will be used for searching for the right RecipientInfo in the recipientInfos field.
    
    Parameters:
    recipientKey - the key of the recipient to be used for decrypting the encrypted content-encryption key.
    recipientIdentifier - specifies which RecipientInfo the given key belongs to
    
    Throws:
    
    CMSException - if there occurs an error while decrypting the content-encryption key or setting up the cipher for decrypting the content, or no RecipientInfo for the requested recipient is included
    
    java.security.NoSuchAlgorithmException - if there is no implementation of the content-encryption algorithm
    
    java.security.InvalidKeyException - if the specified private key is not valid
  - setupCipher
```
public void setupCipher(java.security.Key recipientKey,
               X509Certificate recipientCertificate)
                 throws CMSException,
                        java.security.NoSuchAlgorithmException,
                        java.security.InvalidKeyException
```
    Uses the specified key for decrypting the content-encryption key to setup the cipher for decrypting the encrypted content of this EnvelopedDataStream object for the requesting recipient, specified by the given recipient certificate.
    This method first uses the given key for decrypting the encrypted temporary symmetric key obtained from the corresponding RecipientInfo structure, and subsequently uses this key to initialize a CipherInputStream for decrypting the inherent encrypted content.
    Unlike the non-stream supporting EnvelopedData class where the encrypted-content decryption already is performed inside the setupCipher method, the cipher will be only initialized for decrypting in this class. The encrypted-content decryption actually is done during reading the data obtained by calling the getInputStream method. So don´t call getInputStream before setting up the cipher!
    Note that this method only can be used for decrypting the encrypted content if the recipient in mind has a RecipientInfo of type KeyTransRecipientInfo or KeyAgreeRecipientInfo using a public key from a certificate for its key management protocol.
    
    Parameters:
    recipientKey - the private key of the recipient to be used for decrypting the encrypted content-encryption key.
    recipientCertificate - the certificate of the recipient specifying which RecipientInfo the recipient´s private key belongs to
    
    Throws:
    
    CMSException - if there occurs an error while decrypting the content-encryption key or setting up the cipher for decrypting the content, or no RecipientInfo for the requested recipient is included
    
    java.security.NoSuchAlgorithmException - if there is no implementation of the content-encryption algorithm
    
    java.security.InvalidKeyException - if the specified private key is not valid
  - setupCipher
```
public void setupCipher(java.security.Key key)
                 throws CMSException,
                        java.security.NoSuchAlgorithmException,
                        java.security.InvalidKeyException
```
    Uses the given symmetric key to setup the cipher for decrypting the content.
    The secret key supplied to this method has to be the already decrypted content encryption key.
    Unlike the non-stream supporting EnvelopedData class where the encrypted-content decryption already is performed inside the setupCipher method, the cipher will be only initialized for decrypting in this class. The encrypted-content decryption actually is done during reading the data obtained by calling the getInputStream method. So don´t call getInputStream before setting up the cipher!
    
    Parameters:
    key - the temporary symmetric key that has been used to encrypt the content, and now is used for decrypting it again
    
    Throws:
    
    CMSException - if there occurs an error while setting up the cipher for decrypting the content
    
    java.security.NoSuchAlgorithmException - if there is no implementation for the content-encryption algorithm
    
    java.security.InvalidKeyException - if the specified private key is not valid
  - getInputStream
```
public java.io.InputStream getInputStream()
```
    Returns an InputStream from where the decrypted data can be read.
    Attention! The stream only may be read once.
    When having created a new EnvelopedDataStream object to be encoded to a stream, this method should not be called at all, since the stream automatically will be read during performing the encoding (which is done when calling a writeTo method).
    When having decoded and parsed a received EnvelopedDataStream object comimg from some stream, this method may be used for obtaining the raw (decrypted) data after having setup the cipher for decrypting the content.
    
    Returns:
    an InputStream for reading the decrypted data
  - getVersion
```
public int getVersion()
```
    Returns the syntax version number.
    
    Returns:
    the syntax version number
  - getOriginatorInfo
```
public OriginatorInfo getOriginatorInfo()
```
    Gets the OriginatorInfo, if included.
    The originatorInfo may be set for including certificates and/or certificate revocation lists if required by the key management algorithm used.
    
    Returns:
    the originatorInfo, if included; otherwise null
  - getRecipientInfos
```
public RecipientInfo[] getRecipientInfos()
```
    Returns all the recipient infos included in this EnvelopedData object.
    
    Returns:
    an array containing all the RecipientInfo objects included into this EnvelopedData
  - getRecipientInfo
```
public RecipientInfo getRecipientInfo(X509Certificate recipientCertificate)
```
    Returns the recipient info matching to the supplied recipient certificate.
    This method may be used by a recipient for querying for the recipient info that holds the content encryption key encrypted with the public key of the given certificate.
    Note that this method only can be used for searching for RecipientInfos of type KeyTransRecipientInfo or , but NOT
    for a RecipientInfo of type KEKRecipientInfo which does use a certificate.
    
    Returns:
    the RecipientInfo matching to the supplied recipient certificate, or null if no recipient info belonging to the given certificate can be found
  getRecipientInfo
  
  public RecipientInfo getRecipientInfo(KeyIdentifier recipientIdentifier)
  
  Returns the RecipientInfo belonging to the recipient identified by the given recipient identifier.
  
  Parameters:
  recipientIdentifier - the recipient identifier identifying the recipient in mind
  
  Returns:
  the RecipientInfo matching to the supplied recipient identifier, or null if no recipient info belonging to the given recipient identifier can be found
  
  getEncryptedContentInfo
  
  public EncryptedContentInfoStream getEncryptedContentInfo()
  
  Returns the EncryptedContentInfo included in this EnvelopedDataStream object.
  
  Returns:
  the inherent EncryptedContentInfo
  
  getUnprotectedAttributes
  
  public Attribute[] getUnprotectedAttributes()
  
  Gets the unprotected attributes included in this EnvelopedData.
  
  Returns:
  the unprotected attributes; if included
  
  getUnprotectedAttribute
  
  public Attribute getUnprotectedAttribute(ObjectID oid)
  
  Returns the first unprotected attribute matching to the given ObjectID, if included in this EnvelopedData object.
  
  Returns:
  the first unprotected attribute belonging to the given ObjectID or null if there is no attribute for the given OID.
  
  toASN1Object
  
  public ASN1Object toASN1Object() throws CMSException
  
  Returns this EnvelopedDataStream as ASN1Object.
  
  Specified by:
  
  toASN1Object in interface ContentStream
  
  Returns:
  this EnvelopedDataStream as ASN1Object.
  
  Throws:
  
  CMSException - if the ASN1Object could not be created
  
  toASN1Object
  
  protected ASN1Object toASN1Object(int blockSize) throws CMSException
  
  Returns this EnvelopedData as ASN1Object.
  If is positive a constructed OCTET STRING is used for encoding the encrypted content. This method actually will perform the encryption of the symmetric content-encryption key for each participated recipient.
  
  Parameters:
  blockSize - the block size defining the encoding scheme - and specifying the length of each primitive encoded octet string component, if positive
  
  Returns:
  this EnvelopedData as ASN1Object
  
  Throws:
  
  CMSException - if the ASN1Object could not be created
  
  writeTo
  
  public void writeTo(java.io.OutputStream os) throws java.io.IOException
  
  BER encoded this EnvelopedData and writes the encoding to the supplied output stream.
  
  Parameters:
  os - the output stream to which this EnvelopedData shall be written
  
  Throws:
  
  java.io.IOException
  
  writeTo
  
  public void writeTo(java.io.OutputStream os, int blockSize) throws java.io.IOException
  
  Writes the BER encoding of this EnvelopedData to the supplied output stream where a constructed OCTET STRING may be used for encoding the content.
  When encoding the content data to the given stream it is piped through a cipher stream thereby performing the content encryption.
  If the a positive blockSize value is specified, the encrypted content is encoded as indefinite constructed octet string being composed of a certain number of definite primitive encoded octet strings of blockSize length:
  0x24 0x80 0x04 <blocksize> <first encrypted content block> 0x04 <blocksize> <second encrypted content block> 0x04 <blocksize> <third encrypted content block> ... 0x00 0x00
  Otherwise, whole the encrypted content is encoded as definite primitive octet string:
  0x04 <length> <encrypted content>
  
  Parameters:
  os - the output stream to which this SignedData shall be written
  blockSize - the block size defining the encoding scheme - and specifying the length of each primitive encoded octet string component, if positive
  
  Throws:
  
  java.io.IOException - if an error occurs during writing the object
  
  toString
  
  public java.lang.String toString()
  
  Returns a string giving some information about this EnvelopedData object.
  
  Overrides:
  
  toString in class java.lang.Object
  
  Returns:
  the string representation
  
  toString
  
  public java.lang.String toString(boolean detailed)
  
  Returns a string giving some - if requested - detailed information about this EnvelopedData object.
  
  Specified by:
  
  toString in interface ContentStream
  
  Parameters:
  detailed - - whether or not to give detailed information
  
  Returns:
  the string representation
  
  notifyEOF
  
  public void notifyEOF() throws java.io.IOException
  
  This method implements the EOFListener interface to preform the final stage of decoding, once the 'encryptedContentInfo' has been completely decoded.
  Since the unprotected attributes are located at the end of the EnvelopedData structure, they can only be accessed after the data stream (encrypted content) has been completely read. For that reason, after beginning the decode operation (after calling decode(InputStream)), but before reading the data stream (reading input stream getInputStream), only the version, originator information, and recipient information can be parsed. Since the decrypted data is supplied from an input stream, an iaik.utils.NotifyEOFInputStream is wrapped around this input stream that will automatically notify the this method when the stream has been completely read. At that point, this method is automatically executed, which finishes the decoding operation by decoding the unprotected attributes.
  
  For any application it is strongly recommended recommended not to explicitly call this method. This method only is qualified as public method since it implements the iaik.utils.EOFListener interface.
  
  Specified by:
  
  notifyEOF in interface EOFListener
  
  Throws:
  
  java.io.IOException - if an error occurs while decoding the unprotected attributed
  See Also:
  EOFListener, NotifyEOFInputStream

Class EnvelopedDataStream

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

version_

originatorInfo_

recipientInfos_

encryptedContentInfo_

symmetricKey_

blockSize_

unprotectedAttrs_

m_envelopedData

Constructor Detail

EnvelopedDataStream

EnvelopedDataStream

EnvelopedDataStream

EnvelopedDataStream

EnvelopedDataStream

EnvelopedDataStream

EnvelopedDataStream

Method Detail

decode

getContentType

setOriginatorInfo

setRecipientInfos

addRecipientInfo

setUnprotectedAttributes

setBlockSize

getBlockSize

setupCipher

setupCipher

setupCipher

setupCipher

setupCipher

setupCipher

getInputStream

getVersion

getOriginatorInfo

getRecipientInfos

getRecipientInfo

getRecipientInfo

getEncryptedContentInfo

getUnprotectedAttributes

getUnprotectedAttribute

toASN1Object

toASN1Object

writeTo

writeTo

toString

toString

notifyEOF