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

java.lang.Object
- iaik.security.smime.EncryptedContent

```
public class EncryptedContent
extends java.lang.Object
```
This class can be used to create S/MIME encrypted emails in combination with the javax.mail package.
S/MIME (Secure/Multipurpose Internet Mail Extensions) provides a consistent way to send and receive secure MIME data. Based on the popular Internet MIME standard, S/MIME provides the following cryptographic security services for electronic messaging applications: authentication, message integrity and non-repudiation of origin (using digital signatures) and privacy and data security (using encryption) (see S/MIME Version 2 Message Specification).
This class supports the creation and handling of S/MIME encrypted (enveloped) messages in combination with the javax.mail architecture. For creating and working with signed S/MIME messages, use the SignedContent class of the iaik.security.smime package.
S/MIME (Secure/Multipurpose Internet Mail Extensions) specifies the application/pkcs7-mime (smime-type "enveloped-data") type for data enveloping.
The whole (prepared) MIME entity to be enveloped into a PKCS #7: Cryptographic Message Syntax Version 1.5 (RFC 2315) object of type EnvelopedData which subsequently is inserted into an application/pkcs7-mime MIME entity. The smime-type parameter for enveloped messages is "enveloped-data", the file extension is ".p7m" (see S/MIME Version 2 Message Specification). The "Content-" headers of a sample message would look like:
```
 Content-Type: application/pkcs7-mime; smime-type=enveloped-data;
     name="smime.p7m"       
 Content-Transfer-Encoding: base64
 Content-Disposition: attachment; filename="smime.p7m"

 rfvbn...
 
 
```
For creating a new EncryptedContent to be sent, first use a proper constructor, and subsequently supply the content by means of a setContent, setText, or setDataHandler method. Recipients are added by calling the addRecipient method thereby specifying the recipient´s certificate, and the key encryption algorithm to be used (which has to be AlgorithmID.rsaEncryption). When setting the content encryption algorithm by means of the setEncryptionAlgorithm method, optionally the key length may be specified. The S/MIME Version 2 Message Specification recommends DES EDE3 CBC and RC2 CBC to be used as content encryption algorithms. Only for the latter the key length has a meaning and may specify 40, 68, or 128 (default) bits. Note, that according S/MIME, this implementation only allows DES EDE3 CBC, DES CBC, and RC2 CBC as content encryption algorithms. Before actually sending the Message with the encrypted content, the setHeaders method shall be called for properly updating the message headers. Typical usage:
```
 MimeMessage msg = new MimeMessage(session);
 ...
 EncryptedContent ec = new EncryptedContent();
 // set the smime-type parameter to "enveloped-data"
 ec.setSMimeType();
 ec.setContent(...);
 ec.addRecipient(recipientCertificate, AlgorithmID.rsaEncryption);
 ec.setEncryptionAlgorithm(algorithm, keyLength);
 // update message headers
 ec.setHeaders(msg);

 msg.setContent(ec, ec.getContentType());
 Transport.send(msg);
 
```
A recipient uses the decryptSymmetricKey method for decrypting the encrypted content encryption key with her/his private key, and subsequently reads the content, e.g.:
```
 EncryptedContent ec = (EncryptedContent)msg.getContent();
 //recipient at index 0 decrypts the content encryption key:
 ec.decryptSymmetricKey(privateKey, 0);
 // get the content
 Object content = ec.getContent();
 ...
 
```
For more information about the JavaMail architecture, and how to parsing messages, consult Sun´s JavaMail specification.
For using the IAIK-JCE S/MIME classes, an application also will need the packages:
- mail.jar: Get it from Sun.
- activation.jar: Get it from Sun.
- OPTIONAL: pop3.jar: If you need POP3 access. Get it from knife.
Furthermore, for telling JAF the data content handlers for the supported S/MIME types, a RFC1524 mailcap file with the following contents has to be put in the lib directory of your JDK (
/lib):
```
 # Default mailcap file for the JavaMail System
 #
 # for our content-handlers
 #
 text/plain;;   x-java-content-handler=com.sun.mail.handlers.text_plain
 multipart/*;;  x-java-content-handler=com.sun.mail.handlers.multipart_mixed
 message/*;;    x-java-content-handler=com.sun.mail.handlers.message_rfc822
 #
 # IAIK 'mailcap' file
 #
 multipart/signed;;               x-java-content-handler=iaik.security.smime.signed_content
 application/x-pkcs7-signature;;  x-java-content-handler=iaik.security.smime.signed_content
 application/x-pkcs7-mime;;       x-java-content-handler=iaik.security.smime.encrypted_content
 application/x-pkcs10;;           x-java-content-handler=iaik.security.smime.pkcs10_content
 application/pkcs7-signature;;    x-java-content-handler=iaik.security.smime.signed_content
 application/pkcs7-mime;;         x-java-content-handler=iaik.security.smime.encrypted_content
 application/pkcs10;;             x-java-content-handler=iaik.security.smime.pkcs10_content
 
```
When creating a new EncryptedContent to be sent per default the old S/MIME content types (application/x-pkcs7-mime, application/x-pkcs7-signature) are used. For using the new types call the static useNewContentTypes method of the SMimeParameters class before creating a new EncryptedContent object, e.g.:
```
 //switch to new content types
 SMimeParameters.useNewContentTypes(true);
 //create a SignedContent
 EncryptedContent sc = new EncryptedContent();
 ...
 
```
See Also:
SMimeEncrypted

Constructor Summary

Constructors
Constructor and Description
`EncryptedContent()` Creates a new EncryptedContent object.
`EncryptedContent(javax.activation.DataSource dataSource)` Constructs a EncryptedContent object from the given data source.
`EncryptedContent(SignedContent signedContent)` Creates a new S/MIME encrypted and signed content.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`addRecipient(X509Certificate certificate, AlgorithmID keyEncAlg)` Adds one recipient.
`void`	`decryptSymmetricKey(KeyAndCertificateSource keyAndCertificateSource)` Locates one of user's decryption keys that is appropriate for decrypting one of the content-encryption keys, decrypts the content-encryption key, and prepares the cipher for decrypting the encrypted content.
`int`	`decryptSymmetricKey(java.security.PrivateKey recipientPrivateKey, int recipientInfoIndex)` Uses the specified private key to setup the cipher for decrypting this S/MIME object.
`void`	`decryptSymmetricKey(User user)` Locates one of user's decryption keys that is appropriate for decrypting one of the content-encryption keys, decrypts the content-encryption key, and prepares the cipher for decrypting the encrypted content.
`java.lang.Object`	`getContent()` Returns the content as a Java object.
`java.io.InputStream`	`getContentInputStream()` Returns an InputStream for this part's unparsed content.
`java.lang.String`	`getContentType()` Returns the ContentType and any attached parameters of this EncryptedObject.
`javax.activation.DataHandler`	`getDataHandler()` Return a DataHandler for the content within this part.
`AlgorithmID`	`getEncryptionAlgorithm()` Returns the content-encryption algorithm (including any associated parameters) of this EncryptedContent.
`java.io.InputStream`	`getInputStream()` Returns an InputStream for this part's content.
`int`	`getRecipientInfoIndex(X509Certificate recipientCertificate)` Returns the recipient info index matching to the supplied recipient certificate.
`RecipientInfo[]`	`getRecipientInfos()` Returns information about all recipients of this message.
`void`	`setContent(javax.mail.Multipart multipart)` This method sets the given Multipart object as this EncryptedObject's content.
`void`	`setContent(java.lang.Object content, java.lang.String type)` A convenience method for setting this EncryptedObject's content.
`void`	`setContentContentHeaders(javax.mail.Header[] headers)` Set some headers for the entity to be signed.
`void`	`setContentContentTransferEncoding(java.lang.String cte)` Sets the content transfer encoding of the entity to be signed.
`void`	`setDataHandler(javax.activation.DataHandler dataHandler)` Sets the content wrapped by a `javax.activation.DataHandler`.
`void`	`setEncryptionAlgorithm(AlgorithmID contentEncAlg, int keyLength)` Sets the symmetric algorithm for encrypting the message.
`void`	`setHeaders(javax.mail.Message message)` Sets additional headers of the message containing this EncryptedContent.
`void`	`setSMimeType()` Sets the smime-type parameter to "enveloped-data".
`void`	`setText(java.lang.String text)` A convenience method that sets the given String as this EncryptedObject's content with a MIME type of "text/plain".
`void`	`writeTo(java.io.OutputStream os)` Writes this EncryptedContent DER encoded to the given output stream.

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

- Constructor Detail
  - EncryptedContent
```
public EncryptedContent()
```
    Creates a new EncryptedContent object.
    Use a proper setContent, setText, or setDataHandler method for supplying the content to be enveloped. Recipients are added by calling the addRecipient method thereby specifying the recipient´s certificate, and the key encryption algorithm to be used (which has to be AlgorithmID.rsaEncryption). When setting the content encryption algorithm by means of the setEncryptionAlgorithm method, optionally the key length may be specified. The S/MIME Version 2 Message Specification recommends DES EDE3 CBC and RC2 CBC to be used as content encryption algorithms. Only for the latter the key length has a meaning and may specify 40, 68, or 128 (default) bits. Note, that according S/MIME, this implementation only allows DES EDE3 CBC, DES CBC, and RC2 CBC as content encryption algorithms. Before actually sending the Message with the encrypted content, the setHeaders method shall be called for properly updating the message headers. Typical usage:
```
 MimeMessage msg = new MimeMessage(session);
 ...
 EncryptedContent ec = new EncryptedContent();
 ec.setContent(...);
 ec.addRecipient(recipientCertificate, AlgorithmID.rsaEncryption);
 ec.setEncryptionAlgorithm(algorithm, keyLength);
 ec.setHeaders(msg);

 msg.setContent(ec, ec.getContentType());
 Transport.send(msg);
 
```
    When using this constructor the smime-type parameter will not be set. Use the setSMimeType parameter for setting the "enveloped-data" smime-type parameter.
  - EncryptedContent
```
public EncryptedContent(SignedContent signedContent)
```
    Creates a new S/MIME encrypted and signed content. When using this constructor the smime-type parameter will not be set. Use the setSMimeType parameter for setting the "enveloped-data" smime-type parameter.
    
    Parameters:
    signedContent - the SignedContent as content of this EncryptedContent
  - EncryptedContent
```
public EncryptedContent(javax.activation.DataSource dataSource)
                 throws java.io.IOException
```
    Constructs a EncryptedContent object from the given data source. The given data source is expected to supply an DER encoded PKCS#7 ContentInfo object holding the enveloped data. During a mail session this constructor usually will not be called directly. Rather it is called by a proper data content handler encrypted_content supplying the data source.
    For more information on data handling using the javax.activation.DataSource for "MIME type based" data access, see Sun´s JavaBeans Activation Framework (JAF) sepecification.
    
    Parameters:
    dataSource - the DataSource supplying the enveloped data
    
    Throws:
    
    java.io.IOException - if an I/O error occurs during reading the object
- Method Detail
  - setSMimeType
```
public void setSMimeType()
```
    Sets the smime-type parameter to "enveloped-data".
  - getContentType
```
public java.lang.String getContentType()
```
    Returns the ContentType and any attached parameters of this EncryptedObject. This method shall be used when setting an EncryptedContent object as the content of a Message.
```
 Message msg = ...;
 EncryptedContent ec = new EncryptedContent();
 msg.setContent(ec, ec.getContentType());
 ...
 
```
    Returns:
    the content type of this Encrypted object
  - setDataHandler
```
public void setDataHandler(javax.activation.DataHandler dataHandler)
```
    Sets the content wrapped by a javax.activation.DataHandler. This method provides the mechanism to set this EncryptedContent's content, e.g:
```
 DataHandler dataHandler = new DataHandler(...);
 EncryptedContent sc = new EncryptedContent();
 ec.setDataHandler(dataHandler);
 
```
    The DataHandler wraps around the actual content. It allows clients to discover the operations available on the content, and to instantiate the appropriate component to perform those operations. For more information consult Sun´s JavaBeans Activation Framework (JAF) sepecification.
    Parameters:
    dataHandler - the DataHandler for the content
  - setContent
```
public void setContent(java.lang.Object content,
              java.lang.String type)
```
    A convenience method for setting this EncryptedObject's content. The part internally wraps the content in a DataHandler.
    Note that a DataContentHandler class for the specified type should be available to the JavaMail implementation for this to work right; i.e., to do setContent(foobar, "application/x-foobar"), a DataContentHandler for "application/x-foobar" should be installed. Refer to the Java Activation Framework for more information.
    
    Parameters:
    content - a java object
    type - MIME type of this object
  - setText
```
public void setText(java.lang.String text)
```
    A convenience method that sets the given String as this EncryptedObject's content with a MIME type of "text/plain".
    
    Parameters:
    text - the text that is the EncryptedObject's content
  - setContent
```
public void setContent(javax.mail.Multipart multipart)
```
    This method sets the given Multipart object as this EncryptedObject's content.
    
    Parameters:
    multipart - the multipart object that is the EncryptedObject's content
  - getRecipientInfos
```
public RecipientInfo[] getRecipientInfos()
```
    Returns information about all recipients of this message. You will need at least the private key of one recipinet specified in this array to decrypt the message.
    
    Returns:
    all recipients who can decrypt this message
  - getRecipientInfoIndex
```
public int getRecipientInfoIndex(X509Certificate recipientCertificate)
```
    Returns the recipient info index matching to the supplied recipient certificate. 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.
    
    Parameters:
    recipientCertificate - the certificate of the recipient
    
    Returns:
    the recipient info index matching to the supplied recipient certificate, or -1 if no recipient info belonging to the given certificate can be found
  - decryptSymmetricKey
```
public int decryptSymmetricKey(java.security.PrivateKey recipientPrivateKey,
                      int recipientInfoIndex)
                        throws SMimeException,
                               java.security.InvalidKeyException
```
    Uses the specified private key to setup the cipher for decrypting this S/MIME object.
    
    Parameters:
    privateKey - the private of one recipient specified in a RecipientInfo object
    recipientInfoIndex - specifies which RecipientInfo the private key belongs to
    
    Throws:
    
    SMimeException - if there is an error while decrypting the data
    
    java.security.InvalidKeyException - if the supplied private key is inappropriate
  - decryptSymmetricKey
```
public void decryptSymmetricKey(User user)
                         throws UserNotLoggedInException,
                                NotARecipientException,
                                SMimeException
```
    Locates one of user's decryption keys that is appropriate for decrypting one of the content-encryption keys, decrypts the content-encryption key, and prepares the cipher for decrypting the encrypted content.
    The cipher will be only initialized for decrypting with this call; The encrypted-content decryption actually is done when the data is read by calling the getInputStream, getContent, or getDataHandler method. So don´t call any of these methods before decrypting the encrypted content-encryption key!
    
    Parameters:
    user - the user
    
    Throws:
    
    UserNotLoggedInException - if the user is not logged in
    
    NotARecipientException - if the user is not listed as a recipient (unable to decrypt the content)
    
    SMimeException - if an error occurs while decrypting the content-encryption key or setting up the cipher for decrypting the content
    Since:
    
    7.1
  - decryptSymmetricKey
```
public void decryptSymmetricKey(KeyAndCertificateSource keyAndCertificateSource)
                         throws NotARecipientException,
                                SMimeException
```
    Locates one of user's decryption keys that is appropriate for decrypting one of the content-encryption keys, decrypts the content-encryption key, and prepares the cipher for decrypting the encrypted content.
    The cipher will be only initialized for decrypting with this call; The encrypted-content decryption actually is done when the data is read by calling the getInputStream, getContent, or getDataHandler method. So don´t call any of these methods before decrypting the encrypted content-encryption key!
    
    Parameters:
    keyAndCertificateSource - a user's keys and certificates
    
    Throws:
    
    NotARecipientException - if the user is not listed as a recipient (unable to decrypt the content)
    
    SMimeException - if an error occurs while decrypting the content-encryption key or setting up the cipher for decrypting the content
    Since:
    
    7.1
  - setHeaders
```
public void setHeaders(javax.mail.Message message)
```
    Sets additional headers of the message containing this EncryptedContent. Till now I found no way how to set the required header for the message which contains this EncryptedContent. This method adds one header with one parameter to the specified message:
```
 Content-Disposition: attachment";
     filename="smime.p7m"
 Content-Transfer-Encoding: base64
 
```
    Parameters:
    message - message to add the headers
  - getContent
```
public java.lang.Object getContent()
                            throws java.io.IOException,
                                   javax.mail.MessagingException
```
    Returns the content as a Java object. The type of the returned object of course depends on the content itself. For example, the object returned for "text/plain" content is usually a String object. For content-types that are unknown to the DataHandler system, an input stream is returned as the content.
    
    Returns:
    an Object representing the content of the decrypted message
    
    Throws:
    
    java.io.IOException - if an I/O error occurs when getting the content from the inherent data handler
    
    javax.mail.MessagingException - if an error occurs when fetching the inherent data handler
  - getDataHandler
```
public javax.activation.DataHandler getDataHandler()
                                            throws javax.mail.MessagingException
```
    Return a DataHandler for the content within this part. The DataHandler allows clients to operate on as well as retrieve the content.
    
    Returns:
    a DataHandler for the content
    
    Throws:
    
    javax.mail.MessagingException - if an error occurs when fetching the data handler
  - getInputStream
```
public java.io.InputStream getInputStream()
                                   throws java.io.IOException,
                                          javax.mail.MessagingException
```
    Returns an InputStream for this part's content. Any mail-specific transfer encodings will be decoded before the input stream is provided. But this also means that the message is completely parsed and therefore large messages can cause an OutOfMemoryException.
    
    Returns:
    an InputStream holding the content of the message
    
    Throws:
    
    java.io.IOException - if an I/O error occurs when getting the input stream from the inherent data handler
    
    javax.mail.MessagingException - if an error occurs when fetching the inherent data handler
  - getContentInputStream
```
public java.io.InputStream getContentInputStream()
                                          throws java.io.IOException
```
    Returns an InputStream for this part's unparsed content. No mail-specific transfer encodings will be decoded before the input stream is provided. This is typically a convenience method that just invokes the SMimeEncrypted's getInputStream() method.
    This method can be used to get the content of large messages.
    
    Returns:
    an InputStream holding supplying the unparsed message
    
    Throws:
    
    java.io.IOException
  - addRecipient
```
public void addRecipient(X509Certificate certificate,
                AlgorithmID keyEncAlg)
```
    Adds one recipient. The supplied key encryption algorithm identifier has to be AlgorithmID.rsaEncryption
    
    Parameters:
    certificate - the certificate of one recipient
    keyEncAlg - the key encryption algorithm to use (i.e. AlgorithmID.rsaEncryption)
  - setEncryptionAlgorithm
```
public void setEncryptionAlgorithm(AlgorithmID contentEncAlg,
                          int keyLength)
```
    Sets the symmetric algorithm for encrypting the message. For RC2 the key length in bits can be: 40, 64, 128 (default). If the encryption algorithm is not RC2, the keyLength parameter is ignored.
    The default value is AlgorithmID.des_EDE3_CBC
    Possible encryption algorithms are:
    - AlgorithmID.rc2_CBC with 40, 64 or 128 bits
    - AlgorithmID.des_CBC
    - AlgorithmID.des_EDE3_CBC
    Parameters:
    contentEncAlgorithm - the algorithm for encrypting the content
    keyLength - the key length for RC2
  - getEncryptionAlgorithm
```
public AlgorithmID getEncryptionAlgorithm()
```
    Returns the content-encryption algorithm (including any associated parameters) of this EncryptedContent.
    
    Returns:
    the content encryption algorithm
  - setContentContentTransferEncoding
```
public void setContentContentTransferEncoding(java.lang.String cte)
```
    Sets the content transfer encoding of the entity to be signed. This method allows to set the content transfer encoding for the inner entity when method setText or setDataHandler is used for supplying the content. However, the supplied content transfer encoding will be ignored when the inner entity is a structured entity.
    
    Parameters:
    cte - the content transfer encoding to be applied to the inner entity to be signed
  - setContentContentHeaders
```
public void setContentContentHeaders(javax.mail.Header[] headers)
```
    Set some headers for the entity to be signed. This method allows to set some headers for the inner entity when method setText or setDataHandler is used for supplying the content. However, the supplied header will be ignored when the inner entity is a structured entity. The supplied headers are not cloned!
    
    Parameters:
    headers - the headers to be applied to the inner entity to be signed
  - writeTo
```
public void writeTo(java.io.OutputStream os)
             throws java.io.IOException,
                    javax.mail.MessagingException
```
    Writes this EncryptedContent DER encoded to the given output stream.
    
    Throws:
    
    java.io.IOException - if an error occurs writing to the stream
    
    javax.mail.MessagingException - if an error occurs when fetching the data to be written

Class EncryptedContent

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

EncryptedContent

EncryptedContent

EncryptedContent

Method Detail

setSMimeType

getContentType

setDataHandler

setContent

setText

setContent

getRecipientInfos

getRecipientInfoIndex

decryptSymmetricKey

decryptSymmetricKey

decryptSymmetricKey

setHeaders

getContent

getDataHandler

getInputStream

getContentInputStream

addRecipient

setEncryptionAlgorithm

getEncryptionAlgorithm

setContentContentTransferEncoding

setContentContentHeaders

writeTo