iaik.smime

Class CompressedContent

java.lang.Object

iaik.smime.CompressedContent

All Implemented Interfaces:

SMimeContentType

public class CompressedContent
extends java.lang.Object
implements SMimeContentType

This class can be used to create compressed S/MIME emails in combination with the JavaMail API (javax.mail package).

The S/MIMEv3.1 (Secure/Multipurpose Internet Mail Extensions) protocol specifies the compressed-data content type for compressing MIME entities by using the CMS type CompressedData. After preparing the MIME entity in the usual way it is packed it into a CMS CompressedData object, wrapped by the CMS ContentInfo object. Finally the ContentInfo is put into a S/MIME entity of content type application/pkcs7-mime with the following MIME headers:

 Content-Type: application/pkcs7-mime; smime-type=compressed-data;
     name=smime.p7z
 Content-Transfer-Encoding: base64
 Content-Disposition: attachment; filename=smime.p7z
 

After having created a new CompressedContent object, the content to be compressed has to be supplied by means of a setContent, setText, or setDataHandler method. Before actually sending the message with the compressed content, the compression algorithm has to be set, and method setHeaders shall be called for properly updating the message headers, e.g.:

 // the mail session
 Session = ...;
 // create a new MIME message and set Subject, From, To,... headers 
 MimeMessage msg = new MimeMessage(session);
 ...
 // This step could be signing, encrypting, etc...
 ...
 // create a CompressedContent object
 CompressedContent compressed = new CompressedContent();
 // supply the content, e.g.:
 DataHandler dh = ...;
 compressed.setDataHandler(dh);
 // set the compression algorithm to be used, default is zlib compression
 // if a different algorithm is desired, a CompressionProvider which provides
 // a different set of algorithms can be set using the setCompressionProvider method
 compressed.setCompressionAlgorithm(CompressionProvider.zlib_compressed);
 // update message headers
 compressed.setHeaders(msg);
 // set the CompressedContent as content of the message
 msg.setContent(compressed, compressed.getContentType());
 // send the message
 Transport.send(msg);
 

A recipient simply accesses the content of the compressed message, e.g.:

 CompressedContent compressed = (CompressedContent)msg.getContent();
 // get the (decompressed, original) content 
 Object content = compressed.getContent();
 ...
 

For more information about the JavaMail architecture, and how to handling MIME messages, consult Sun´s JavaMail specification.

For using the IAIK-JCE S/MIME classes, an application also will need the following packages:

• mail.jar: JavaMail API from Sun.
• activation.jar: JavaBeans Activation Framework from Sun.
• OPTIONAL: pop3.jar (maybe already included in mail.jar): If you need POP3 access

The JAF assignment between MIME-types and content handlers is done by means of a RFC 1524 mailcap file which is included in the IAIK-CMS distribution. It defines the following classes as content handlers for the corresponding MIME types:

 #
 # IAIK 'mailcap' file entries
  #
 multipart/signed;;               x-java-content-handler=iaik.smime.signed_content
 application/x-pkcs7-signature;;  x-java-content-handler=iaik.smime.signed_content
 application/x-pkcs7-mime;;       x-java-content-handler=iaik.smime.encrypted_content
 application/x-pkcs10;;           x-java-content-handler=iaik.smime.pkcs10_content
 application/pkcs7-signature;;    x-java-content-handler=iaik.smime.signed_content
 application/pkcs7-mime;;         x-java-content-handler=iaik.smime.encrypted_content
 application/pkcs10;;             x-java-content-handler=iaik.smime.pkcs10_content
 

The content handlers are registered by copying the mailcap file into the lib directory of your JDK (/lib). Alternatively you may register the IAIK-S/MIME mailcap file dynamically by using the default command map:

 String mailcapFileName = ...;
 MailcapCommandMap mc = new MailcapCommandMap(mailcapFileName);
 CommandMap.setDefaultCommandMap(mc);
 

For a more detailed description of mailcap handling consult the Javadoc of the Activation Framework.

When creating a new CompressedContent to be sent per default the new S/MIME content types (application/pkcs7-mime) are used. For using the old types (application/x-pkcs7-mime) call the static useNewContentTypes method of the SMimeParameters class before creating a new CompressedContent object, e.g.:

 //switch to old content types
 SMimeParameters.useNewContentTypes(false);
 //create a SignedContent
 CompressedContent sc = new CompressedContent();
 ...
 

See Also:

CompressedDataStream

Field Summary

Fields inherited from interface iaik.smime.SMimeContentType

LOG

Constructor Summary

Constructors

Constructor and Description
CompressedContent() Creates a new CompressedContent object.
CompressedContent(javax.activation.DataSource datasource) Constructs a CompressedContent object from the given data source.
CompressedContent(SMimeContentType smimeCT)

Method Summary

Methods

Modifier and Type	Method and Description
AlgorithmID	getCompressionAlgorithm() Return the Compression Algorithm
CompressionProvider	getCompressionProvider()
java.lang.Object	getContent() This method returns the content contained in the CompressedContent 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 CompressedContent.
javax.activation.DataHandler	getDataHandler() Return a DataHandler for the content within this part.
java.lang.String	getSMimeType() Returns the SMimeType string.
void	setCompressionAlgorithm(AlgorithmID algorithmid) Sets the Compression Algorithm which is used to Compress the Data.
void	setCompressionProvider(CompressionProvider compressionprovider) Sets the Compression Provider to be used for Compression.
void	setContent(javax.mail.Multipart multipart) This method sets the given Multipart object as this compressed object's content.
void	setContent(java.lang.Object content, java.lang.String type) A convenience method for setting this compresesed object's content.
void	setContentContentHeaders(javax.mail.Header[] headers) Set some headers for the entity to be compressed.
void	setContentContentTransferEncoding(java.lang.String s) Sets the content transfer encoding of the entity to be compressed.
void	setDataHandler(javax.activation.DataHandler datahandler) Sets the content wrapped by a javax.activation.DataHandler.
void	setHeaders(javax.mail.Part part) Sets additional headers of the message containing this CompressedContent.
void	setSession(javax.mail.Session session) Set the mail session to use when sending this message.
void	setSMimeType() Sets the smime-type parameter to "compressed-data".
void	setText(java.lang.String text) A convenience method that sets the given String as this CompressedObject's content with a MIME type of "text/plain".
void	writeTo(java.io.OutputStream outputstream) Writes this CompressedContent 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

CompressedContent

public CompressedContent(javax.activation.DataSource datasource)
                  throws java.io.IOException

Constructs a CompressedContent object from the given data source. 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

CompressedContent

public CompressedContent(SMimeContentType smimeCT)
                  throws javax.mail.MessagingException

Throws:

javax.mail.MessagingException

CompressedContent

public CompressedContent()

Creates a new CompressedContent object.

Use a proper setContent,setText, or setDataHandlermethod for supplying the content to be enveloped. Before actually sending the Message with the compressed content, the setHeadersmethod shall be called for properly updating the message headers. Typical usage (Wrapping an explicit signed message (content-type "multipart/signed")):

 
  MimeMessage msg = new MimeMessage(session);
  ...
  boolean implicit = false;
  SignedContent sc = new SignedContent(implicit);
  set the content to be signed
  sc.setContent(...);
  sc.setCertificates(certificates);
  sc.addSigner(privateKey, signerCertificate);
  ...
  CompressedContent cc = new CompressedContent(sc);
  cc.setCompressionAlgorithm(AlgorithmID.zlib_compress);
  cc.setContent(...);
  cc.setHeaders(msg);
 
  msg.setContent(cc, cc.getContentType());
  Transport.send(msg);
  
 

When using this constructor the smime-type parameter will not be set. Use the setSMimeTypeparameter for setting the "compressed-data" smime-type parameter.

Method Detail

writeTo

public void writeTo(java.io.OutputStream outputstream)
             throws javax.mail.MessagingException,
                    java.io.IOException

Writes this CompressedContent 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

setText

public void setText(java.lang.String text)
             throws javax.mail.MessagingException

A convenience method that sets the given String as this CompressedObject's content with a MIME type of "text/plain".

Parameters:

text - the text that is the CompressedObject's content

Throws:

javax.mail.MessagingException

setDataHandler

public void setDataHandler(javax.activation.DataHandler datahandler)
                    throws javax.mail.MessagingException

Sets the content wrapped by a javax.activation.DataHandler. This method provides the mechanism to set this CompressedContent's content, e.g:

 
  DataHandler dataHandler = new DataHandler(...);
  CompressedContent cc = new CompressedContent();
  cc.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

Throws:

javax.mail.MessagingException

getContent

public java.lang.Object getContent()
                            throws javax.mail.MessagingException,
                                   java.io.IOException

This method returns the content contained in the CompressedContent object. This is a convienance method that will return the data as an object. If very large data is used, the getContentInputStream() method should be used instead.

Returns:

object representing the content of this object

Throws:

javax.mail.MessagingException - If a messaging error occurs

java.io.IOException - If there was an error decoding the data

getContentType

public java.lang.String getContentType()

Returns the ContentType and any attached parameters of this CompressedContent. This method shall be used when setting a CompressedContent object as the content of a Message.

 
  Message msg = ...;
  CompressedContent cc = new CompressedContent();
  msg.setContent(cc, cc.getContentType());
  ...
  
 

Specified by:

getContentType in interface SMimeContentType

Returns:

the content type of this Compressed object

setHeaders

public void setHeaders(javax.mail.Part part)

Sets additional headers of the message containing this CompressedContent. javax.mail.Part is an interface which is implemented by Message. This method adds one header with one parameter to the specified message:

 
  Content-Disposition: attachment";
      filename="smime.p7z"
  Content-Transfer-Encoding: base64
  
 

Specified by:

setHeaders in interface SMimeContentType

Parameters:

part - Part to add the headers

setSession

public void setSession(javax.mail.Session session)

Set the mail session to use when sending this message. If not set, the default mail session is used.

Parameters:

session -

setSMimeType

public void setSMimeType()

Sets the smime-type parameter to "compressed-data".

setCompressionAlgorithm

public void setCompressionAlgorithm(AlgorithmID algorithmid)
                             throws java.security.NoSuchAlgorithmException

Sets the Compression Algorithm which is used to Compress the Data. The Default algorithm is ZLIB (AlgorithmID.zlib_compress).

Parameters:

algorithmid - - The AlgorithmID to be used for compression

Throws:

java.security.NoSuchAlgorithmException - - If algorithm does not exist

getSMimeType

public java.lang.String getSMimeType()

Returns the SMimeType string. This method will return "compressed-data" as defined in RFC 3851 section 3.2.2.

Specified by:

getSMimeType in interface SMimeContentType

Returns:

the SMimeType as a String

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

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 SMimeCompressed 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

getCompressionAlgorithm

public AlgorithmID getCompressionAlgorithm()

Return the Compression Algorithm

Returns:

AlgorithmID - The Algorithm ID of the compression Algorithm

setContent

public void setContent(javax.mail.Multipart multipart)
                throws javax.mail.MessagingException

This method sets the given Multipart object as this compressed object's content.

Parameters:

multipart - the multipart object that is the compressed object's content

Throws:

javax.mail.MessagingException

setContent

public void setContent(java.lang.Object content,
              java.lang.String type)
                throws javax.mail.MessagingException

A convenience method for setting this compresesed object'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

Throws:

javax.mail.MessagingException

setContentContentTransferEncoding

public void setContentContentTransferEncoding(java.lang.String s)
                                       throws javax.mail.MessagingException

Sets the content transfer encoding of the entity to be compressed. 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:

s - the content transfer encoding to be applied to the inner entity to be signed

Throws:

javax.mail.MessagingException

setContentContentHeaders

public void setContentContentHeaders(javax.mail.Header[] headers)
                              throws javax.mail.MessagingException

Set some headers for the entity to be compressed. 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

Throws:

javax.mail.MessagingException

setCompressionProvider

public void setCompressionProvider(CompressionProvider compressionprovider)

Sets the Compression Provider to be used for Compression. This method allows a different CompressionProvider to be set. For example, if you want to use a different algorithm than the default ZLIB compression, you could create your own CompressionProvider class which provides a different set of algorithms.

Parameters:

compressionprovider - the compression provider to be used

getCompressionProvider

public CompressionProvider getCompressionProvider()

Returns:

the Compression provider used by this class.