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

java.lang.Object
- iaik.pkcs.pkcs7.SignedDataStream
- - iaik.pkcs.pkcs7.SignedAndEnvelopedDataStream

All Implemented Interfaces:

ContentStream, EOFListener, java.util.EventListener
```
public class SignedAndEnvelopedDataStream
extends SignedDataStream
implements ContentStream, EOFListener
```
This class represents the stream-supporting implementation of the PKCS#7 SignedAndEnvelopedData type.
Each PKCS#7 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 SignedAndEnvelopedData content type is defined as:
signedAndEnvelopedData OBJECT IDENTIFIER ::= { pkcs-7 4 }
which corresponds to the OID string "1.2.840.1.113549.1.7.4".
The PKCS #7: Cryptographic Message Syntax Version 1.5 (RFC 2315) specifies the SignedAndEnvelopedData content type for providing a syntax for building digital envelopes whose authenticity and integrity is ensured by digatal signatures. Content of any type may be enveloped for any number of recipients and signed by any number of signers in parallel.
For each recipient, a commonly at random generated content-encryption key is encrypted with the particular recipient´s public 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.
For each signer, a message digest is computed on the content with a signer-specific message-digest algorithm. Subsequently, again for each signer, the corresponding message digest from the previous step is encrypted with the particular signer´s private key, and the result is encrypted with the content-encryption key. This double encrypted message digest and some signer-specific information are collected into aSignerInfo value. The digital signature for each signer is the recovered single encrypted message digest.
Finally all created SignerInfo and RecipientInfo values are collected together with the encrypted content for forming a SignedAndEnvelopedData structure.
This class implements the SignedAndEnvelopedData structure resulting from the last step described above. The SignedAndEnvelopedDatatype is defined as ASN.1 SEQUENCE type containing the following components (see PKCS #7: Cryptographic Message Syntax Version 1.5 (RFC 2315)):
```
 SignedAndEnvelopedData ::= SEQUENCE {
    version                 Version,
    recipientInfos          RecipientInfos,
    digestAlgorithms        DigestAlgorithmIdentifiers,
    encryptedContentInfo    EncryptedContentInfo,
    certificates                  [0] IMPLICIT Certificates OPTIONAL,
    crls                    [1] IMPLICIT CertificateRevocationLists OPTIONAL,
    signerInfos             SignerInfos }
 
```
The digestAlgorithms field contains the object identifiers of the message digest algorithms used by the several signers for digesting the content. The optional certificates field shall contain certificate chains for all the signers of the signerInfos field. The optional crls field may supply information about the revocation status of the certificates specified in the certificates field. The encryptedContentInfo field specifies the content type, the content-encryption algorithm, and holds the encrypted content. The non-empty SignerInfos and RecipientInfos collect per-signer (respectively per-recipient) information for all parciticipated signers (recipients). Each SignerInfo includes the double encrypted message digest in its encrypted_digest field, and each RecipientInfo includes the content-encryption key, encrypted with the particular recipient´s public key.
A recipient, when receiving the SignedAndEnvelopedData message, decrypts the encrypted content-encryption key from the corresponding RecipientInfo with his/her private key for subsequently decrypting the encrypted content using the content-encryption key just recovered. Subsequently the recovered content-encryption key is used for decrypting the double encrypted message digest for each signer, and the result is decrypted with the signer´s public key giving the recovered message digest, which can be compared with an independently computed message digest for verifying the signature.
For more information consult the PKCS #7: Cryptographic Message Syntax Version 1.5 (RFC 2315) specification. Note, that PKCS#7 Version 1.6 removes support for extended certificates, which already is considered by this implementation.
It is recommended to use a sequential combination of the signed-data and the enveloped-data content types instead of using the signed-and-enveloped-data content type, since the signed-and-enveloped-data content type does not have authenticated or unauthenticated attributes, and does not provide enveloping of signer inforamtion other than the signature.

Assuming that signer_certs and recipient_certs represent the certifcate chains of some single signer and some intended recipient, a typical proceeding may perform the following steps for building a SignedAndEnvelopedDataStream object to be sent to the recipient:
```
 //the data to be signed and enveloped supplied from an input stream:
 InputStream data_is = ...;
 //create a SignedAndEnvelopedDataStream object thereby supplying the data
 //input stream and the content-encryption algorithm:
 SignedAndEnvelopedDataStream saed = new new SignedAndEnvelopedDataStream(data_is, AlgorithmID.des_EDE3_CBC);
 //supply the signer´s certificate chain (generally, there may be more than only
 //one signer):
 saed.setCertificates(signer_certs);
 //create a SignerInfo structure for the signer entity thereby
 //specifying the signer´s certificate by an IssuerAndSerialNumber
 //structure, the signer´s digest algorithm, and the signer´s private key;
 //the IssuerAndSerialNumber can be created from signer_certs[0], which constitutes
 //the signer´s certificate:
 IssuerAndSerialNumber issuer_and_serialNr = new IssuerAndSerialNumber(signer_certs[0]);
 SignerInfo signer_info = new SignerInfo(issuer_and_serialNr, AlgorithmID.sha, privateKey);
 //add the SignerInfo just created to the SignedAndEnvelopedDataStream object:
 saed.addSignerInfo(signer_info);
 //create a RecipientInfo for the intended recipient thereby specifiying
 //its certificate (for obtaining the IssuerAndSerialNumber) and the key
 //encryption algorithm to be used (at this time only the rsaEncryption method
 //is supported):
 RecipientInfo recipient = new RecipientInfo(recipient_certs[0], AlgorithmID.rsaEncryption);
 //add the recipient to the SignedAndEnvelopedDataStream object:
 saed.addRecipientInfo(recipient);
 //write the SignedAndEnvelopedDataStream structure to an output stream thereby
 //actually performing digest computation, encryption and encoding:
 int blockSize = ...;
 OuputStream encoded_stream = ...;
 saed.writeTo(encoded_stream, blockSize);
 
```
When a positve block size is specified for encoding the SignedAndEnvelopedData to a stream, the encrypted data is BER encoded as indefinite constructed octet string being composed of a series of definite primitive encoded octet strings of blockSize length, e.g.:
```
 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 indefinte constrcuted 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).
Each recipient decrypts the content-encryption key with his/her private key and subsequently decrypts the encrypted content and the double-encrypted message digest for each signer with the recovered content-encryption key. The signature is verifiied by decrypting the (now single-) encrypted message digest with the signer´s public key for comparing it with a independently computet message digest, e.g.:
```
 //create a SignedAndEnvelopedDataStream from the received DER encoding
 SignedAndEnvelopedDataStream saed =
                          new SignedAndEnvelopedDataStream(encoded_stream);
 //setup the cipher for decryption with the recipient´s private key
 int recipientInfoIndex = 0;
 saed.setupCipher(privateKey, recipientInfoIndex);
 //get and read the data for encrypting the content and updating the hash computation
 //needed for verification:
 InputStream data_is = saed.getInputStream();
 byte[] buf = new byte[1024];
 int r;
 while ((r = data_is.read(buf)) > 0) {
     // do something useful
 }
 //verify the signatures of all participated signers:
 SignerInfo[] signer_infos = saed.getSignerInfos();
 for (int i=0; i<signer_infos.length; i++) {
     try {
       // verify the signed data using the SignerInfo at index i
       X509Certificate signer_cert = saed.verify(i);
       // if the signature is OK the certificate of the signer is returned
       System.out.println("Signature OK from signer: "+signer_cert.getSubjectDN());
     } catch (SignatureException ex) {
       // if the signature is not OK a SignatureException is thrown
       System.out.println("Signature ERROR from signer: "
                           + signed_and_enveloped_data.getCertificate(signer_infos[i].getIssuerAndSerialNumber()).getSubjectDN());
     }
 }
 
```
See Also:
SignerInfo, RecipientInfo, IssuerAndSerialNumber, SignedDataStream, EnvelopedDataStream

Field Summary
- Fields inherited from class iaik.pkcs.pkcs7.SignedDataStream
  block_size, certificates, content_info, content_type, crls, EXPLICIT, IMPLICIT, input_stream, mode, signer_infos, this_object, version

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`SignedAndEnvelopedDataStream()` Default constructor for dynamic object creation in ContentInfo.
	`SignedAndEnvelopedDataStream(java.io.InputStream is)` Creates a new SignedAndEnvelopedDataStream where the DER encoded data is read from the given InputStream.
	`SignedAndEnvelopedDataStream(java.io.InputStream is, AlgorithmID contentEA)` Creates a new PKCS#7 SignedAndEnvelopedData object where the content is read from the supplied InputStream.
	`SignedAndEnvelopedDataStream(java.io.InputStream is, AlgorithmID contentEA, int keyLen)` Creates a new PKCS#7 SignedAndEnvelopedData object where the content is read from the supplied InputStream.

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 the SignedAndEnvelopedData from a DerInputStream.
`ObjectID`	`getContentType()` Returns the content type this class implements.
`EncryptedContentInfoStream`	`getEncryptedContentInfo()` Returns the encrypted content info included in this SignedAndEnvelopedData object.
`byte[]`	`getMessageDigest(AlgorithmID digestAlgorithm)` Returns the message digest calculated for a specific algorithm.
`RecipientInfo[]`	`getRecipientInfos()` Returns all the recipient infos included in this SignedAndEnvelopedData object.
`void`	`setRecipientInfos(RecipientInfo[] recipients)` Sets the recipient infos.
`void`	`setupCipher(java.security.PrivateKey recipientPrivateKey, int recipientInfoIndex)` Uses the specified private key to setup the Cipher for decrypting the content-encryption key and subsequently using it to decrypt the encrypted content of this`SignedAndEnvelopedData` object for the requesting recipient, specified by its `recipientInfoIndex`.
`ASN1Object`	`toASN1Object()` Returns this PKCS#7 SignedAndEnvelopedDataStream as ASN1Object.
`protected ASN1Object`	`toASN1Object(int blockSize)` Returns this SignedAndEnvelopedDataStream as ASN1Object where a constructed OCTET STRING is used for encoding the content.
`java.lang.String`	`toString()` Returns a string giving some information about this SignedAndEnvelopedDataStream object.
`java.lang.String`	`toString(boolean detailed)` Returns a string giving some - if requested - detailed information about this SignedAndEnvelopedDataStream object.
`void`	`verify(java.security.PublicKey publicKey, int signerInfoIndex)` Uses the provided public key for verifying the signature that has been created by the `signerInfoIndex`´th signer.

Methods inherited from class iaik.pkcs.pkcs7.SignedDataStream
addSignerInfo, getCertificate, getCertificates, getCRLs, getDigestAlgorithms, getInputStream, getMessageDigest, getMode, getSignedDigest, getSignerInfos, getVersion, notifyEOF, setBlockSize, setCertificates, setCRLs, setInputStream, setMessageDigest, setSignerInfos, verify, verify, verifyAndValidate, verifyAndValidate, writeTo, writeTo

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

Methods inherited from interface iaik.pkcs.pkcs7.ContentStream
setBlockSize

Methods inherited from interface iaik.utils.EOFListener
notifyEOF

- Constructor Detail
  - SignedAndEnvelopedDataStream
```
protected SignedAndEnvelopedDataStream()
```
    Default constructor for dynamic object creation in ContentInfo. An application shall not use this constructor for creating a SignedAndEnvelopedDataStream object.
  - SignedAndEnvelopedDataStream
```
public SignedAndEnvelopedDataStream(java.io.InputStream is,
                            AlgorithmID contentEA)
                             throws java.security.NoSuchAlgorithmException
```
    Creates a new PKCS#7 SignedAndEnvelopedData object where the content is read from the supplied InputStream. The content type is set to PKCS#7 Data.
    
    Parameters:
    is - the InputStream containg 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
  - SignedAndEnvelopedDataStream
```
public SignedAndEnvelopedDataStream(java.io.InputStream is,
                            AlgorithmID contentEA,
                            int keyLen)
                             throws java.security.NoSuchAlgorithmException
```
    Creates a new PKCS#7 SignedAndEnvelopedData object where the content is read from the supplied InputStream. The content type is set to PKCS#7 Data.
    
    Parameters:
    is - the InputStream containg the data to envelope
    contentEA - the content encryption algorithm for encrypting the content
    keyLen - the key length for the encryption key
    
    Throws:
    
    java.security.NoSuchAlgorithmException - if there is no implementation for the specified algorithm
  - SignedAndEnvelopedDataStream
```
public SignedAndEnvelopedDataStream(java.io.InputStream is)
                             throws PKCSParsingException,
                                    java.io.IOException
```
    Creates a new SignedAndEnvelopedDataStream where the DER encoded data is read from the given InputStream.
    
    Parameters:
    is - the InputStream holding a DER encoded PKCS#7 SignedAndEnvelopedData object
    
    Throws:
    
    java.io.IOException - if an I/O error occurs during reading from the InputStream
    
    PKCSParsingException - if an error occurs while parsing the object
- Method Detail
  - decode
```
public void decode(java.io.InputStream is)
            throws java.io.IOException,
                   PKCSParsingException
```
    Reads and decodes the SignedAndEnvelopedData from a DerInputStream. If the supplied InputStream actually is not an instance of DerInputStream, internally a DerInputStream is created before parsing the data.
    
    Specified by:
    
    decode in interface ContentStream
    
    Overrides:
    
    decode in class SignedDataStream
    
    Parameters:
    is - the InputStream holding a DER encoded PKCS#7 SignedAndEnvelopedData object
    
    Throws:
    
    java.io.IOException - if an I/O error occurs during reading from the InputStream
    
    PKCSParsingException - if an error occurs while parsing the object
  - setupCipher
```
public void setupCipher(java.security.PrivateKey recipientPrivateKey,
               int recipientInfoIndex)
                 throws PKCSException,
                        java.security.NoSuchAlgorithmException,
                        java.security.InvalidKeyException
```
    Uses the specified private key to setup the Cipher for decrypting the content-encryption key and subsequently using it to decrypt the encrypted content of thisSignedAndEnvelopedData object for the requesting recipient, specified by its recipientInfoIndex. This method first uses the given private key for decrypting the encrypted temporary symmetric key obtained from the corresponding RecipientInfo structure, and subsequently uses this key to setup a CipherInputStream.
    Unlike the non-stream supporting SignedAndEnvelopedData 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:
    recipientPrivateKey - the private key of one recipient specified in a RecipientInfo object
    recipientInfoIndex - specifies which RecipientInfo the private key belongs to
    
    Throws:
    
    PKCSException - if there occurs an error while decrypting the data
    
    java.security.NoSuchAlgorithmException - if there is no implementation of the content-encryption algorithm
    
    java.security.InvalidKeyException - if the specified private key is not valid
  - getContentType
```
public ObjectID getContentType()
```
    Returns the content type this class implements.
    
    Specified by:
    
    getContentType in interface ContentStream
    
    Overrides:
    
    getContentType in class SignedDataStream
    
    Returns:
    ObjectID.pkcs7_signedAndEnvelopedData
  - setRecipientInfos
```
public void setRecipientInfos(RecipientInfo[] recipients)
```
    Sets the recipient infos.
    Each single RecipientInfo specifies the particular recipient´s certificate by IssuerAndSerialNumber, and the key encryption algorithm to be used; currently only PKCS#1 rsaEncryption is supported.
    Example:
```
 RecipientInfo[] recipients = new RecipientInfo[2];
 recipients[0] = new RecipientInfo(cert1, AlgorithmID.rsaEncryption);
 recipients[1] = new RecipientInfo(cert2, AlgorithmID.rsaEncryption);
 enveloped_data.setRecipientInfos(recipients);
 
```
    Parameters:
    recipients - a collection of per-recipient information
    See Also:
    RecipientInfo
  - addRecipientInfo
```
public void addRecipientInfo(RecipientInfo recipient)
```
    Adds one recipient to the list of recipient infos.
    The RecipientInfo specifies the particular recipient´s certificate by IssuerAndSerialNumber, and the key encryption algorithm to be used; currently only PKCS#1 rsaEncryption is supported.
    Example:
```
 RecipientInfo recipient = new RecipientInfo(cert, AlgorithmID.rsaEncryption);
 enveloped_data.addRecipientInfos(recipient);
 
```
    Parameters:
    recipient - the RecipientInfo to be added
  - verify
```
public void verify(java.security.PublicKey publicKey,
          int signerInfoIndex)
            throws java.security.SignatureException
```
    Uses the provided public key for verifying the signature that has been created by the signerInfoIndex´th signer.
    
    Overrides:
    
    verify in class SignedDataStream
    
    Parameters:
    publicKey - the public key of the signer to verify the message
    signerInfoIndex - the index into the SignerInfos array for identifying the SignerInfo belonging to the signer whose signature has to be verified
    
    Throws:
    
    java.security.SignatureException - if the signature turns out to be incorrect
  - getRecipientInfos
```
public RecipientInfo[] getRecipientInfos()
```
    Returns all the recipient infos included in this SignedAndEnvelopedData object.
    
    Returns:
    an array containing all the RecipientInfo objects included in this SignedAndEnvelopedData
    See Also:
    setRecipientInfos(iaik.pkcs.pkcs7.RecipientInfo[])
  - getEncryptedContentInfo
```
public EncryptedContentInfoStream getEncryptedContentInfo()
```
    Returns the encrypted content info included in this SignedAndEnvelopedData object. When calling this method for obtaining the inherent EncryptedContentInfoStream an explicit cast to EncryptedContentInfoStream has to be made:
```
 EncryptedContentInfoStream eci = (EncryptedContentInfoStream)saed.getEncryptedContentInfo();
 
```
    Returns:
    the encrypted content info
  - toASN1Object
```
public ASN1Object toASN1Object()
                        throws PKCSException
```
    Returns this PKCS#7 SignedAndEnvelopedDataStream as ASN1Object.
    
    Specified by:
    
    toASN1Object in interface ContentStream
    
    Overrides:
    
    toASN1Object in class SignedDataStream
    
    Returns:
    this SignedAndEnvelopedData as ASN1Object.
    
    Throws:
    
    PKCSException - if the ASN1Object could not be created
  - toASN1Object
```
protected ASN1Object toASN1Object(int blockSize)
                           throws PKCSException
```
    Returns this SignedAndEnvelopedDataStream as ASN1Object where a constructed OCTET STRING is used for encoding the content.
    
    Overrides:
    
    toASN1Object in class SignedDataStream
    
    Parameters:
    blockSize - the block size defining the encoding scheme - and specifying the length of each primitive encoded octet string component, if positive
    
    Throws:
    
    PKCSException - if the ASN1Object could not be created
  - toString
```
public java.lang.String toString()
```
    Returns a string giving some information about this SignedAndEnvelopedDataStream object.
    
    Overrides:
    
    toString in class SignedDataStream
    
    Returns:
    the string representation
  - toString
```
public java.lang.String toString(boolean detailed)
```
    Returns a string giving some - if requested - detailed information about this SignedAndEnvelopedDataStream object.
    
    Specified by:
    
    toString in interface ContentStream
    
    Overrides:
    
    toString in class SignedDataStream
    
    Parameters:
    detailed - - whether or not to give detailed information
    
    Returns:
    the string representation
  - getMessageDigest
```
public byte[] getMessageDigest(AlgorithmID digestAlgorithm)
                        throws java.security.NoSuchAlgorithmException
```
    Returns the message digest calculated for a specific algorithm.
    
    Returns:
    the message digest calculated while writing the content
    
    Throws:
    
    java.security.NoSuchAlgorithmException - if there is no message digest for the specified algorithm

Class SignedAndEnvelopedDataStream

Field Summary

Fields inherited from class iaik.pkcs.pkcs7.SignedDataStream

Constructor Summary

Method Summary

Methods inherited from class iaik.pkcs.pkcs7.SignedDataStream

Methods inherited from class java.lang.Object

Methods inherited from interface iaik.pkcs.pkcs7.ContentStream

Methods inherited from interface iaik.utils.EOFListener

Constructor Detail

SignedAndEnvelopedDataStream

SignedAndEnvelopedDataStream

SignedAndEnvelopedDataStream

SignedAndEnvelopedDataStream

Method Detail

decode

setupCipher

getContentType

setRecipientInfos

addRecipientInfo

verify

getRecipientInfos

getEncryptedContentInfo

toASN1Object

toASN1Object

toString

toString

getMessageDigest