| 
					
  		
		 	IAIK CMS/SMIME Toolkit API Documentation
			 Version 6.1  | 
||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Objectiaik.cms.EnvelopedDataStream
public class EnvelopedDataStream
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.113549.1.7.3".
 The Cryptographic Message Syntax (CMS) (RFC 5652) 
 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 
 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 an
 EnvelopedData 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 5652):
 
 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 RevocationInfoChoices 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 five alternatives for encrypting the content depending
 on the key management algorithm used to protect the content encryption 
 key for a specific recipient:
 
KeyTransRecipientInfo for the public key of the recipient 
                    certificate, identified by IssuerAndSerialNumber. CMS recommends to use RSA for encrypting
                    the content encryption key.
 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 ESDH with an ephemeral sender key.
 KEKRecipientInfo using a CMS key wrap algorithm like
                   AES key wrap.
 PassowrdRecipientInfo
                   using a CMS key wrap algorithm like PWRI-KEK (RFC 3211).
 OtherRecipientInfo.
 originatorInfo field may be used to include certificate/crl 
 information about the originator if required by the key managemant 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 5652 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.:
 
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 AES in CBC mode for encrypting the content
     EnvelopedDataStream enveloped_data = new EnvelopedDataStream(dataStream, (AlgorithmID)AlgorithmID.aes256_CBC.clone());
     
 RecipientInfo object of requested type (KeyTransRecipientInfo, KeyAgreeRecipientInfo,
     or KEKRecipientInfo), and add all RecipientInfos 
     to the EnvelopedDataStream object by calling method setRecipientInfos, e.g. (assuming to use two recipients, one having an RSA certificate and one
     having a ECDH certificate):
     
     RecipientInfo[] recipients = new RecipientInfo[2];
     // create a KeyTransRecipientInfo for recipient with RSA certificate
     X509Certificate rsaRecipientCert = ...;
     recipients[0] = new KeyTransRecipientInfo(rsaRecipientCert, (AlgorithmID)AlgorithmID.rsaEncryption.clone());
     // create a KeyAgreeRecipientInfo for recipient with ECDH certificate
     X509Certificate ecdhRecipientCert = ...;
     // the key encryption (key agreement) algorithm to use:
     AlgorithmID keyEA = (AlgorithmID)CMSAlgorithmID.dhSinglePass_stdDH_sha256kdf_scheme.clone();
     // the key wrap algorithm to use:
     AlgorithmID keyWrapAlg = (AlgorithmID)AlgorithmID.cms_aes256_wrap.clone();
     // the length of the key encryption key to be generated:
     int kekLength = 256;
     recipients[1] = new KeyAgreeRecipientInfo(keyEA, keyWrapAlg, kekLength);
     ((KeyAgreeRecipientInfo)recipients[1]).addRecipient(ecdhRecipientCert, CertificateIdentifier.ISSUER_AND_SERIALNUMBER);
     enveloped_data.setRecipientInfos(recipients);
     
 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);
     
     When a positive block size (default 2048) 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>
     
 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 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.
 KeyTransRecipientInfo,
 we can use any of the setupCipher methods to setup the cipher for
 decrypting the encrypted content-encryption key and the encrypted content:
 
     EnvelopedDataStream enveloped_data = new EnvelopedDataStream(encoded_stream);
     
 
     EncryptedContentInfoStream eci = (EncryptedContentInfoStream)enveloped_data.getEncryptedContentInfo();
     System.out.println("Content type: "+eci.getContentType().getName());
     System.out.println("Content encryption algorithm: "+eci.getContentEncryptionAlgorithm().getName());
     
 
     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]);
     }
     
 
     // 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 do not call
     getInputStream before setting up the cipher!
     
     InputStream data_is = enveloped_data.getInputStream();
     byte[] buf = new byte[4096];
     int r;
     while ((r = data_is.read(buf)) > 0) {
        // do something useful
     }
     
 
 This class may be also use to create/encrypt or parse/decrypt explicit 
 EnvelopedData messages where the encrypted content is not included in the 
 EnvelopedData/EncryptedContentInfo but transferred by other means outside the
 EnvelopedData/EncryptedContentInfo. 
 
 For creating an EnvelopedDataStream in explicit mode the (to-be-encrypted) 
 content has to be specified as usual when calling the constructor. 
 Subsequently method  has to be called to set
 the mode to setModeEnvelopedDataStream.EXPLICIT. Before finally writing the EnvelopedData encoded to an output stream, method  has to be called to read (and thereby)
 encrypt the content data to be transferred by other means:
 getInputStream()
 //the data to be enveloped supplied from an input stream:
 InputStream dataStream = ...;
 // use, e.g., AES in CBC mode for encrypting the content
 EnvelopedDataStream envelopedData = new EnvelopedDataStream(dataStream, (AlgorithmID)AlgorithmID.aes256_CBC.clone());
 // the encrypted content shall be transmitted outside the EnvelopedData
 envelopedData.setMode(EnvelopedDataStream.EXPLICIT);
 // create and set the recipient infos
 RecipientInfo[] recipients = ...;
 envelopedData.setRecipientInfos(recipients);
 // read and encrypt the content data to be transmitted outside the EnvelopedData
 InputStream encryptedContentIs = envelopedData.getInputStream();
 byte[] buf = ...;
 int r;
 while ((r = data_is.read(buf)) > 0) {
   // do something useful
 }
 // encode the EnvelopedData
 OutputStream os = ...;
 envelopedData.writeTo(os); 
 
 When parsing an explicit EnvelopedData method setInputStream
 has to be called to specify the encrypted content received by other means:
 
 // the input stream from which to read the encoded EnvelopedData:
 InputStream encodedStream = ...;
 // create EnvelopedDataStream
 EnvelopedDataStream envelopedData = new EnvelopedDataStream(encodedStream);
   ...
 // set the encrypted content received by other means
 InputStream encryptedContentStream = ...;
 envelopedData.setInputStream(encryptedContentStream);
 // setup cipher and decrypt the message for the, e.g., first recipient
 PrivateKey privateKey = ...;
 int recipientInfoIndex = 0;
 envelopedData.setupCipher(privateKey, 0);
 InputStream decryptedDataIs = envelopedData.getInputStream();
 byte[] buf = new byte[4096];
 int r;
 while ((r = decryptedDataIs.read(buf)) > 0) {
   // do something useful
 }  
 
RecipientInfo, 
KeyTransRecipientInfo, 
KeyAgreeRecipientInfo, 
KEKRecipientInfo, 
PasswordRecipientInfo, 
OtherRecipientInfo, 
EncryptedContentInfoStream| Field Summary | |
|---|---|
protected  int | 
blockSize_
The block size for block oriented stream encoding.  | 
protected  EncryptedContentInfoStream | 
encryptedContentInfo_
The EncryptedContentInfo for the encrypted content.  | 
static int | 
EXPLICIT
Denotes a mode where the encrypted message is not transported within the EnvelopedData (EncryptedContentInfo).  | 
static int | 
IMPLICIT
Denotes a mode where the encrypted message is included in the EnvelopedData (EncryptedContentInfo).  | 
protected  boolean | 
keyChanged_
Whether the content encryption key has changed.  | 
protected  OriginatorInfo | 
originatorInfo_
The optional OriginatorInfo.  | 
protected  java.util.Vector | 
recipientInfos_
Repository for the RecipientInfos.  | 
protected  SecurityProvider | 
securityProvider_
The SecurityProvider providing the required cryptographic engines.  | 
protected  javax.crypto.SecretKey | 
symmetricKey_
The secret content encryption key.  | 
protected  iaik.asn1.structures.Attribute[] | 
unprotectedAttrs_
Optional unprotected attributes.  | 
protected  int | 
version_
The version number; default 0.  | 
| Constructor Summary | |
|---|---|
protected  | 
EnvelopedDataStream()
Default constructor for dynamic object creation in ContentInfoStream.  | 
  | 
EnvelopedDataStream(java.io.InputStream is)
Creates a new EnvelopedDataStream from a BER encoded EnvelopedData object which is read from the given InputStream.  | 
  | 
EnvelopedDataStream(java.io.InputStream is,
                    iaik.asn1.structures.AlgorithmID contentEA)
Creates a new EnvelopedDataStream object where the content to be enveloped is read from the supplied InputStream.  | 
  | 
EnvelopedDataStream(java.io.InputStream is,
                    iaik.asn1.structures.AlgorithmID contentEA,
                    int keyLength)
Creates a new EnvelopedDataStream object where the content to be enveloped is read from the supplied InputStream.  | 
  | 
EnvelopedDataStream(java.io.InputStream is,
                    SecurityProvider securityProvider)
Creates a new EnvelopedDataStream from a BER encoded EnvelopedData object which is read from the given InputStream.  | 
  | 
EnvelopedDataStream(iaik.asn1.ObjectID contentType,
                    java.io.InputStream is,
                    iaik.asn1.structures.AlgorithmID contentEA)
Creates a new EnvelopedDataStream object where the content to be enveloped is read from the supplied InputStream.  | 
  | 
EnvelopedDataStream(iaik.asn1.ObjectID contentType,
                    java.io.InputStream is,
                    iaik.asn1.structures.AlgorithmID contentEA,
                    int keyLength)
Creates a new EnvelopedDataStream object where the content to be enveloped is read from the supplied InputStream.  | 
  | 
EnvelopedDataStream(iaik.asn1.ObjectID contentType,
                    java.io.InputStream is,
                    iaik.asn1.structures.AlgorithmID contentEA,
                    int keyLength,
                    SecurityProvider securityProvider)
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 | |
|---|---|
 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.  | 
 iaik.asn1.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.  | 
 int | 
getMode()
Gets the mode of this EnvelopedDataStream.  | 
 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(iaik.x509.X509Certificate recipientCertificate)
Returns the recipient info matching to the supplied recipient certificate.  | 
 RecipientInfo[] | 
getRecipientInfos()
Returns all the recipient infos included in this EnvelopedData object. | 
 RecipientInfo[] | 
getRecipientInfos(int type)
Returns all the recipient infos included in this EnvelopedData object that have the specified type. | 
 SecurityProvider | 
getSecurityProvider()
Gets the SecurityProvider installed for this EncryptedDataStream.  | 
 iaik.asn1.structures.Attribute | 
getUnprotectedAttribute(iaik.asn1.ObjectID oid)
Returns the first unprotected attribute matching to the given ObjectID, if included in this EnvelopedData object.  | 
 iaik.asn1.structures.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 for performing the final decoding.  | 
 void | 
setBlockSize(int blockSize)
Sets the block size for defining the length of each definite primitive encoded octet string component.  | 
 void | 
setInputStream(java.io.InputStream is)
Sets the input stream that supplies the content data to be encrypted.  | 
 void | 
setMode(int mode)
Sets the mode for this EnvelopedDataStream.  | 
 void | 
setOriginatorInfo(OriginatorInfo originatorInfo)
Sets the optional OriginatorInfo.  | 
 void | 
setRecipientInfos(RecipientInfo[] recipients)
Sets the recipient infos.  | 
 void | 
setSecurityProvider(SecurityProvider securityProvider)
Sets the SecurityProvider for this EnvelopedDataStream.  | 
 void | 
setUnprotectedAttributes(iaik.asn1.structures.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.  | 
 javax.crypto.SecretKey | 
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. | 
 javax.crypto.SecretKey | 
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. | 
 javax.crypto.SecretKey | 
setupCipher(java.security.Key recipientKey,
            iaik.x509.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. | 
 iaik.asn1.ASN1Object | 
toASN1Object()
Returns this EnvelopedDataStream as ASN1Object.  | 
protected  iaik.asn1.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)
Writes this EnvelopedData BER encoded to the given output stream.  | 
 void | 
writeTo(java.io.OutputStream os,
        int blockSize)
Writes this EnvelopedData BER encoded to the given 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 | 
|---|
public static final int IMPLICIT
public static final int EXPLICIT
protected int version_
protected OriginatorInfo originatorInfo_
protected java.util.Vector recipientInfos_
protected EncryptedContentInfoStream encryptedContentInfo_
protected javax.crypto.SecretKey symmetricKey_
protected int blockSize_
protected iaik.asn1.structures.Attribute[] unprotectedAttrs_
protected SecurityProvider securityProvider_
protected boolean keyChanged_
| Constructor Detail | 
|---|
protected EnvelopedDataStream()
public EnvelopedDataStream(java.io.InputStream is,
                           iaik.asn1.structures.AlgorithmID contentEA)
                    throws java.security.NoSuchAlgorithmException
 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.
is - the InputStream supplying the data to be envelopedcontentEA - the content encryption algorithm for encrypting the content
java.security.NoSuchAlgorithmException - if there is no implementation for the specified algorithm
public EnvelopedDataStream(iaik.asn1.ObjectID contentType,
                           java.io.InputStream is,
                           iaik.asn1.structures.AlgorithmID contentEA)
                    throws java.security.NoSuchAlgorithmException
 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.
contentType - the content type of the content to be envelopedis - the InputStream containing the data to envelopecontentEA - the content encryption algorithm for encrypting the content
java.security.NoSuchAlgorithmException - if there is no implementation for the specified algorithm
public EnvelopedDataStream(java.io.InputStream is,
                           iaik.asn1.structures.AlgorithmID contentEA,
                           int keyLength)
                    throws java.security.NoSuchAlgorithmException
 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.
is - the InputStream containing the data to envelopecontentEA - the content encryption algorithm for encrypting the contentkeyLength - the key length that may be set when using a content
                  encryption algorithm that supports variable key lengths
java.security.NoSuchAlgorithmException - if there is no implementation for the specified algorithm
public EnvelopedDataStream(iaik.asn1.ObjectID contentType,
                           java.io.InputStream is,
                           iaik.asn1.structures.AlgorithmID contentEA,
                           int keyLength)
                    throws java.security.NoSuchAlgorithmException
 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.
contentType - the content type of the content to be envelopedis - the InputStream containing the data to envelopecontentEA - the content encryption algorithm for encrypting the contentkeyLength - the key length that may be set when using a content
                  encryption algorithm that supports variable key lengths
java.security.NoSuchAlgorithmException - if there is no implementation for the specified algorithm
public EnvelopedDataStream(iaik.asn1.ObjectID contentType,
                           java.io.InputStream is,
                           iaik.asn1.structures.AlgorithmID contentEA,
                           int keyLength,
                           SecurityProvider securityProvider)
                    throws java.security.NoSuchAlgorithmException
 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.
contentType - the content type of the content to be envelopedis - the InputStream containing the data to envelopecontentEA - the content encryption algorithm for encrypting the contentkeyLength - the key length that may be set when using a content
                  encryption algorithm that supports variable key lengthssecurityProvider - the security provider to be used; if null the 
                         default system-wide SecurityProvider is used
java.security.NoSuchAlgorithmException - if there is no implementation for the specified algorithm
public EnvelopedDataStream(RecipientInfo[] recipients,
                           EncryptedContentInfoStream encryptedCI)
 The given array of RecipientInfo specifies a collection of
 per-recipient information, and the given EncryptedContentInfoStream
 supplies the already encrypted content.
recipients - information about the recipientsencryptedCI - the encrypted content info
public EnvelopedDataStream(java.io.InputStream is)
                    throws CMSParsingException,
                           java.io.IOException
is - the InputStream supplying a BER encoded CMS EnvelopedData object
java.io.IOException - if an I/O error occurs during reading from the InputStream
CMSParsingException - if an error occurs while parsing the object
public EnvelopedDataStream(java.io.InputStream is,
                           SecurityProvider securityProvider)
                    throws CMSParsingException,
                           java.io.IOException
is - the InputStream supplying a BER encoded CMS EnvelopedData objectsecurityProvider - the security provider to be used; if null the 
                         default system-wide SecurityProvider is used
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 | 
|---|
public void setSecurityProvider(SecurityProvider securityProvider)
This method allows to explicitly set a SecurityProvider for this EnvelopedDataStream. If no explicit SecurityProvider is set, the default system wide installed SecurityProvider will be used for the required cryptographic operations.
 This class uses the following method(s) of the SecurityProvider, which may be overriden by an application, if required:
 
getInputStreamCipherEngine
     methods to get an InputStreamCipherEngine
     for stream based content en/decryption as used by the inherent EncryptedContentInfoStream
 getByteArrayCipherEngine
     methods to get a ByteArrayCipherEngine
     for content en/decryption for non-stream EnvelopedData objects
 generateKey
     to generate the symmetric content encryption key as used by the inherent EncryptedContentInfo
 getAlgorithmParameters
     to parse algorithm parameters from an AlgorithmID as used by the inherent EncryptedContentInfo
 created by this class.
securityProvider - the SecurityProvider to be setpublic SecurityProvider getSecurityProvider()
 This class uses the following method(s) of the SecurityProvider, which may be overriden by an application, if required:
 
getInputStreamCipherEngine
     methods to get an InputStreamCipherEngine for
     stream based content en/decryption as used by the inherent EncryptedContentInfoStream
 getByteArrayCipherEngine
     methods to get a ByteArrayCipherEngine
     for content en/decryption for non-stream EnvelopedData objects
 generateKey
     to generate the symmetric content encryption key as used by the inherent EncryptedContentInfo
 getAlgorithmParameters
     to parse algorithm parameters from an AlgorithmID as used by the inherent EncryptedContentInfo
 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.
null if
         this object does not have its own SecurityProviderpublic void setMode(int mode)
 This method may be only called to set the mode to EXPLICIT
 for creating a new EnvelopedDataStream in EXPLICIT mode where the 
 encrypted content shall not be included in the EnvelopedData. In this case 
 the encrypted content has to be transmitted by other means. This method may not
 be called in IMPLICIT mode (default) where
 the encrypted content is included in the EnvelopedData. This method MUST
 not be called when parsing an EnvelopedData where the mode is automatically
 detected and cannot be changed.
mode - the mode, either IMPLICIT (to include
                       the encrypted content (default) or EXPLICIT
                       to not include it)
java.lang.IllegalArgumentException - if the mode is not IMPLICIT
                                    or EXPLICIT; or if this
                                    method is called when parsing an EnvelopedDatapublic int getMode()
IMPLICIT (to include
                   the encrypted content (default) or 
                   EXPLICIT
                   to not include it)
public void decode(java.io.InputStream is)
            throws java.io.IOException,
                   CMSParsingException
decode in interface ContentStreamis - the InputStream holding a BER encoded EnvelopedData object
java.io.IOException - if an I/O error occurs during reading from the InputStream
CMSParsingException - if an error occurs while parsing the objectpublic iaik.asn1.ObjectID getContentType()
 Use getEncryptedContentInfo().getContentType() for getting the
 type the encrypted content represents.
getContentType in interface ContentStreamObjectID.cms_envelopedDatapublic void setOriginatorInfo(OriginatorInfo 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.
originatorInfo - the OriginatorInfo to be setpublic void setRecipientInfos(RecipientInfo[] recipients)
 Any RecipientInfo added supplies 
 recipient-specific information used for identifying the key of
 the recipient to be used for en/decrypting the content.
recipients - a collection of per-recipient informationRecipientInfo, 
KeyTransRecipientInfo, 
KeyAgreeRecipientInfo, 
KEKRecipientInfo, 
PasswordRecipientInfo, 
OtherRecipientInfopublic void addRecipientInfo(RecipientInfo recipient)
 Any RecipientInfo added supplies 
 recipient-specific information used for identifying the key of
 the recipient to be used for en/decrypting the content.
recipient - the RecipientInfo to be addedRecipientInfo, 
KeyTransRecipientInfo, 
KeyAgreeRecipientInfo, 
KEKRecipientInfo, 
PasswordRecipientInfo, 
OtherRecipientInfopublic void setUnprotectedAttributes(iaik.asn1.structures.Attribute[] attributes)
attributes - the unprotected attributes to be setpublic void setBlockSize(int blockSize)
blockSize is smaller or equal to zero the
 whole encrypted data is encoded as definite primitive octet string.
setBlockSize in interface ContentStreamblockSize - for defining the encoding scheme and setting the octet
        string component length, if positivepublic int getBlockSize()
blockSize is smaller or equal to zero the
 whole data is encoded as definite primitive octet string.
getBlockSize in interface ContentStream
public javax.crypto.SecretKey setupCipher(java.security.Key recipientKey,
                                          int recipientInfoIndex)
                                   throws CMSException,
                                          java.security.NoSuchAlgorithmException,
                                          java.security.InvalidKeyException
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 do not 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.
recipientKey - the key of the recipient to be used for decrypting
                     the encrypted content-encryption key.recipientInfoIndex - the index into the recipientInfos field
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 key is not valid
public javax.crypto.SecretKey setupCipher(java.security.Key recipientKey,
                                          KeyIdentifier recipientIdentifier)
                                   throws CMSException,
                                          java.security.NoSuchAlgorithmException,
                                          java.security.InvalidKeyException
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 do not 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.
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
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 key is not valid
public javax.crypto.SecretKey setupCipher(java.security.Key recipientKey,
                                          iaik.x509.X509Certificate recipientCertificate)
                                   throws CMSException,
                                          java.security.NoSuchAlgorithmException,
                                          java.security.InvalidKeyException
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 do not 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.
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 private key belongs to
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
public void setupCipher(java.security.Key key)
                 throws CMSException,
                        java.security.NoSuchAlgorithmException,
                        java.security.InvalidKeyException
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 do not call
 getInputStream before setting up the cipher!
 
key - the temporary symmetric key that has been used to encrypt the content,
            and now is used for decrypting it again
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 key is not validpublic java.io.InputStream getInputStream()
Attention! The stream only may be read once.
 When having created a new (implcit) 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). However, when
 not using the EnvelopedDataStream in explicit
 mode, this getInputStream method may be called to get and read
 the encrypted content to be transferred by other means:
 
 //the data to be enveloped supplied from an input stream:
 InputStream dataStream = ...;
 // use, e.g., AES in CBC mode for encrypting the content
 EnvelopedDataStream envelopedData = new EnvelopedDataStream(dataStream, (AlgorithmID)AlgorithmID.aes256_CBC.clone());
 
 // if we want to transmit the encrypted content by other means we use the explicit mode
 envelopedData.setMode(EnvelopedDataStream.EXPLICIT);
 
 // create and set the recipient infos
 RecipientInfo[] recipients = ...;
 envelopedData.setRecipientInfos(recipients);
 
 // if we use explicit mode we read and encrypt the content data to be transmitted 
 // outside the EnvelopedData
 InputStream encryptedContentIs = envelopedData.getInputStream();
 byte[] buf = ...;
 int r;
 while ((r = data_is.read(buf)) > 0) {
   // do something useful
 }
 
 // encode the EnvelopedData
 OutputStream os = ...;
 envelopedData.writeTo(os); 
   
 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.
public void setInputStream(java.io.InputStream is)
is - the input stream holding the content data to encryptpublic int getVersion()
public OriginatorInfo getOriginatorInfo()
The originatorInfo may be set for including certificates and/or certificate revocation lists if required by the key management algorithm used.
nullpublic RecipientInfo[] getRecipientInfos()
EnvelopedData object.
RecipientInfo objects
         included into this EnvelopedDatapublic RecipientInfo[] getRecipientInfos(int type)
EnvelopedData object that have the specified type.
type - the recipient info type
RecipientInfo objects
         included into this EnvelopedData that have the 
         specified type (e.g. all KeyTransRecipientInfos); the array may
         be empty if no RecipientInfo with the requested type is includedpublic RecipientInfo getRecipientInfo(iaik.x509.X509Certificate recipientCertificate)
 This method may be used by a recipient for quering 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
 KeyAgreeRecipientInfo, but NOT
 for a RecipientInfo of type KEKRecipientInfo
 which does use a certificate.
recipientCertificate - the certificate of the recipient
null if no recipient info belonging to the given
         certificate can be foundpublic RecipientInfo getRecipientInfo(KeyIdentifier recipientIdentifier)
recipientIdentifier - the recipient identifier identifying the
                            recipient in mind
null if no recipient info belonging to the given
         recipient identifier can be foundpublic EncryptedContentInfoStream getEncryptedContentInfo()
EnvelopedDataStream object.
public iaik.asn1.structures.Attribute[] getUnprotectedAttributes()
public iaik.asn1.structures.Attribute getUnprotectedAttribute(iaik.asn1.ObjectID oid)
oid - the attribute object identifier
null if there is no attribute for the given OID.
public iaik.asn1.ASN1Object toASN1Object()
                                  throws CMSException
toASN1Object in interface ContentStreamEnvelopedDataStream as ASN1Object.
CMSException - if the ASN1Object could not be created
protected iaik.asn1.ASN1Object toASN1Object(int blockSize)
                                     throws CMSException
If <blockSize> 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.
blockSize - the block size defining the encoding scheme - and specifying the
                  length of each primitive encoded octet string component, if positive
CMSException - if the ASN1Object could not be created
public void writeTo(java.io.OutputStream os)
             throws java.io.IOException
os - the output stream to which this EnvelopedData shall be written
java.io.IOException - if an I/O error occurs
public void writeTo(java.io.OutputStream os,
                    int blockSize)
             throws java.io.IOException
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>
os - the output stream to which this SignedData shall be writtenblockSize - the block size defining the encoding scheme - and specifying the
                  length of each primitive encoded octet string component, if positive
java.io.IOException - if an error occurs during writing the object
public void notifyEOF()
               throws java.io.IOException
iaik.utils.NotifyEOFInputStream
 is wrapped around this content data stream
 for indicating that the parsing procedure is to be notified when the stream actually
 has been read. At that point, the programm exceuting automatically jumps to the
 notifyEOF method for finishing the decoding by parsing the
 remaining unprotected attributes, if present.
 
notifyEOF in interface iaik.utils.EOFListenerjava.io.IOException - if an error occurs while parsing the streampublic java.lang.String toString()
EnvelopedData object.
toString in class java.lang.Objectpublic java.lang.String toString(boolean detailed)
EnvelopedData object.
toString in interface ContentStreamdetailed - - whether or not to give detailed information
  | 
					
  		
		 	IAIK CMS/SMIME Toolkit API Documentation
			 Version 6.1  | 
||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
					 
				 | 
				
					v6.1 (c) 2002 IAIK, (c) 2003 - 2025 SIC  | 
				
					 
				 |