org.webdocwf.util.smime.smime
Class EnvelopedSMIME

java.lang.Object
  |
  +--org.webdocwf.util.smime.smime.EnvelopedSMIME

public class EnvelopedSMIME

extends java.lang.Object

EnvelopedSMIME class is used for creating and sending encrypted S/MIME message.

Email message is in general composed of the content of the message and of one or more attachments. The content is visible part of the message, and attacments are mostly files or other binary data, which are not visible parts of message and which are used by email as a transport medium. In this implementation content can be represented in two different forms:

• text/plain (only text withouth any formating) or
• text/html (html coded view of message)

Also, content can be absent, but than at least one attachment must be added. Content can be set on few manners. For text/plain type it can be done in time of construction with constructor designed special for creation of text/plain messages. Also, text content can be created by any of setContent() methods, if construction of object was done by other constructor which create object with empty content. Construction with other constructor offers a few different posibilities for importing content data (File, InputStream, String) by using appropriate setContent() method. If method with four parameters is used, 3rd ant 4th parameters are not in use for text/plain message and could be set null. For setting text/html content, construction of object should be done only by second mentioned constructor, which creates object with empty content. Content should be populated by html code with setContent() method. 3rd parameter is used for resolving relative addresses of resources in html code (images, movies...) and 4th parameter serves as data source for resources that are on special way addressed in html code. Also, there is a setContent() method which doesn't care about resources and which creates message content withouth them. For more information refer to setContent() methods.

Message can contain any number of attachments. Also, message can be wihouth any attachment, but then content must be present. Every attachment should be added by performing single addAttachment() method. Attachments can be added from file or from InputStream. Mime-type which corresponds to particular attachment is obtained according to extension of file name (virtual or real file name) passed to addAttachment() method. File mime.types in META_INF directory contains list of mime-types and corresponding extensions which are used in determination of mime-type. File can be changed to satisfy secific requrements. For more information refer to addAttachmenttent() method.

Encryption of message is performed by symmetric encryption with random generated symmetric key. This key is then encrypted by assymetric encryption with a recipient's public key, and sent together with encrypted message to recipient in CMS (Cryptographic Message Syntax) enveloped object. For all recipients of the message (if there is more than one) operation of encrypting symmetric key must be performed with his corresponding public key (from .cer file). Encryption can be performed by following algorithms and corresponding key sizes:

RC2_CBC, 40 bits (default encryption)
RC2_CBC, 64 bits
RC2_CBC, 128 bits
DES, 56 bits
DES_EDE3_CBC, 128 bits
DES_EDE3_CBC, 192 bits

As a asymmetric algorithm, RSA algorithm is used.

Constructor Summary

EnvelopedSMIME(java.lang.String smtpHost, java.lang.String fromAddress, java.lang.String subject)
Initializes the JavaMail session for SMTP and the MimeMessage for encryption.

EnvelopedSMIME(java.lang.String smtpHost, java.lang.String fromAddress, java.lang.String subject, java.lang.String content)
Initializes the JavaMail session for SMTP and the MimeMessage for encryption.

Method Summary

void	addAttachment(java.io.File file) Adds file as attachment to email message
void	addAttachment(java.io.InputStream data, java.lang.String fileName) Adds data from InputStream as attachment to email message
void	addAttachment(java.lang.String fileName) Adds file as attachment to email message
void	addRecipient(java.lang.String recipientAddress, java.lang.String type, java.lang.String cerFileName) Adds recipient address, type and .cer file of email recipient to encrypted message.
void	enveloping() Envelopes message with default algorithm RC2_CBC, 40 bits
void	enveloping(java.lang.String algorithmName, int keyLength) Envelopes message with given algorithm name and key length
javax.mail.internet.MimeMessage	getEnvelopedMessage() Returns SMIME Message
void	send() Sends S/MIME message to SMTP host
void	setContent(java.io.File inFile, java.lang.String type) Sets message content from file represented by File object.
void	setContent(java.io.InputStream content, java.lang.String type) Sets message content from InputStream.
void	setContent(java.io.InputStream content, java.lang.String type, java.lang.String path, java.io.InputStream[] resources) Sets message content from InputStream.
void	setContent(java.lang.String content, java.lang.String type) Sets message content from String.
void	setContent(java.lang.String content, java.lang.String type, java.lang.String path, java.io.InputStream[] resources) Sets message content.
void	setReply(java.lang.String replyAddress) Sets REPLY TO field in message header

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

EnvelopedSMIME

public EnvelopedSMIME(java.lang.String smtpHost,
                      java.lang.String fromAddress,
                      java.lang.String subject,
                      java.lang.String content)
               throws SMIMEException

Initializes the JavaMail session for SMTP and the MimeMessage for encryption. Dynamically loads the BC and SUN provider necessary for encryption. This constructor is used for creating message with text/plain content. For creating html formated content (text/html), other constructor should be used in combination with one of setContent methods. Note that after using this constructor setContent method can be used only if "content" argument of constructor was given as null, otherwise setContent method can't be used because content is already set as text/plain.

Parameters:

smtpHost - name of SMTP host used for sending email

fromAddress - email address of sender (FROM field in email header)

subject - subject of email (SUBJECT field in email header)

content - text/plain content of email message

Throws:

SMIMEException - if smtpHost or fromAddress parameters are null. Also, it can be caused by non SMIMEException which is MessagingException.

EnvelopedSMIME

public EnvelopedSMIME(java.lang.String smtpHost,
                      java.lang.String fromAddress,
                      java.lang.String subject)
               throws SMIMEException

Initializes the JavaMail session for SMTP and the MimeMessage for encryption. Dynamically loads the BC and SUN provider necessary for encryption. This constructor does not create content of message and it can be set later with one of setContent methods. Also, message can be left withouth content, but then at least one attachement must be added.

Parameters:

smtpHost - name of SMTP host used for sending email

fromAddress - email address of sender (FROM field in email header)

subject - subject of email (SUBJECT field in email header)

Throws:

SMIMEException - if smtpHost or fromAddress parameters are null. Also, it can be caused by non SMIMEException which is MessagingException.

Method Detail

setContent

public void setContent(java.lang.String content,
                       java.lang.String type,
                       java.lang.String path,
                       java.io.InputStream[] resources)
                throws SMIMEException

Sets message content. Message content can be given in two differrent forms: text and html code. If content is type of text, parameter "type" should be "text/plain" and other two parameters are not in use (should be set null). If content is type of html code, parameter "type" should be set as "text/html", otherwise (if it is set as "text/plain") html code is processed as a plain text. This method can be performed only once.

In case of html content, it is essential to (on appropriate way) associate some attributes of particular elements in html code ("background" or "src" atributes) with corresponding ressources (URL-s, relative file addresses or byte array streams). This resources should all be sent with message to enable recipient to see complete html message. Location of resources can be given in few different forms and depending on that, allocation resolving can be successful or not. Following text represents different possibilities for defining locations of resources (pictures, animations, sound...) inside of html code passed to this method, and necessery passed additional parameters used for resolving this resource locations.

• URL defined as: http://... is left unchanged. This resource is not sent with the message and it couldn't be seen by recipient if it is not online on the internet.
• URL defined as: file://... is transformed to corresponding Content ID if the resource can be found on specified location and it is sent with message.
• Absolute path, for example defined as: "c:\tmp\test\picture.bmp", is transformed to corresponding Content ID if the resource can be found on specified location, and is sent with message. If all resources in html code are specified with its absolute path, the 3rd parameter in this method can be null.
• Relative path of all resources specified in html code, for example defined as: ".\test\picture.bmp" and ".\example\flush.swf", must be defined to be relative to same directory path (in this case it is c:\tmp). This parameter (common directory path) is given as 3rd parameter in this method, and is named "path". If html code is obtained from .html file, necessery common directory path is usually path to this .html file. Location of resource is transformed to corresponding Content ID if the resource can be found on specified location. This location is sent with the message.
• Byte array stream as resource for html attribute must be referenced from html code as:
  
  

   *****nnn<virtual_file_name>
  
   
  

  Five '*' characters (must be five) define that it is resource expected from the stream. Other three characters must be digits (000-999) and represent index of corresponding stream in stream array. virtual_file_name is name and extension assigned to data passed from stream. Name is used in construction of "name" parameter in Content-Type, while extension of file name is used in detection of appropriate mime-type. Lenght of virtual_file_name is not important. If there is no data referenced from byte array stream ,4th parameter of this method named "resources" can be null. Also, if all resources are passed through the array of streams, 3th parameter ("path") can be null. Location of resource is transformed to corresponding Content ID if no error has occured during the process of allocation.

All mentioned resource allocation types can be combined together in the same html code, and all will be processed with appropriate use of this method.

Note that number of resource references that are defined in html code by using virtual_file_names must be greater than or equal to number of elements in array of InputStream (4th parameter). If one resource (one element in array of IputStream) is used in html code more than once, it is advisable to use same virtual_file_name in html code because message is then sent with only one attached resource (image, movie...). It is essetntial that desired resource in input stream array corresponds to specified "nnn" part of virtual_file_name.

If resources specified on any described name can not be found or resolved, or if any exception has occured during its processing, they won't be added and html message will be sent withouth them.

Parameters:

content - String representation of message content (text or html code).

type - type of given content. It can take values: "text/plain" or "text/html".

path - common directory path for relative file locations in html code. It can be null if all resources set absolute path or are defined by byte array streams, or if sending resources with relative address it is not desired. Also, it is set to null in case of text/plain message.

resources - way for representing resources used in the given html code which will be added to message as array of InputStream. Detail use of this argument is described above. It can be null if no resources as byte array stream are used, or if sending resources given in that way is not desired. Also, it is set to null in case of text/plain message.

Throws:

SMIMEException - if content is tried to be added twice, or in case of wrong "type" parameter. Also, it can be caused by non SMIMEException which can be one of the following: MessagingException UnsoportedEncodingException.

setContent

public void setContent(java.io.InputStream content,
                       java.lang.String type,
                       java.lang.String path,
                       java.io.InputStream[] resources)
                throws SMIMEException

Sets message content from InputStream. This method can be performed only once. Message content can be given in two differrent forms: text and html code. If content is type of text, parameter "type" should be "text/plain", while if content is type of html code, parameter "type" should be set as "html/code". For further information refer to setContent method with four arguments (String, String, String, InputStream[] ) which is called by this method.

Parameters:

content - message content data given from any InputStream. Data can be text or html code and will be interpreted according to second parameter: "type".

type - type of given content. It can take values: "text/plain" or "text/html".

path - common directory path for relative file locations in html code. It can be null if all resources in html code have set absolute path or are defined by byte array streams, or if sending resources with relative address is not desired. Also, it is set to null in case of text/plain message.

resources - way for representing resources used in the given html code which will be added to message as array of InputStreams. Detail use of this argument is described in other setContent methods mentioned before. It can be null if no resources as byte array stream are used, or if sending resources given in that way is not desired. Also, it is set to null in case of text/plain message.

Throws:

SMIMEException - if content is tried to be added twice , in case of wrong "type" parameter or in case when parameter content is null. Also, it can be caused by non SMIMEException which is MessagingException.

setContent

public void setContent(java.io.InputStream content,
                       java.lang.String type)
                throws SMIMEException

Sets message content from InputStream. This method can be performed only once. Message content can be given in two differrent forms: text and html code. If content is type of text, parameter "type" should be "text/plain", while if content is type of html code, parameter "type" should be set as "html/code". If html code content is set by this method, message will be generated withouth inclusion of the resources defined in paricular html element's attribute ("src" and "background"). Only plain html code will be sent and any reference to local file system resources will be useless for recipient of the message. HTTP referenced resources can still be available if recipient is online on Internet. Message generated on this way is smaller so encrypting process should be faster.

Parameters:

content - message content data given from any InputStream. Data could be text or html code and will be interpreted according to second parameter: "type".

type - type of given content. It can take values: "text/plain" or "text/html".

Throws:

SMIMEException - if content is tried to be added twice , in case of wrong "type" parameter or in case when parameter content is null. Also, it can be caused by non SMIMEException which is MessagingException.

setContent

public void setContent(java.lang.String content,
                       java.lang.String type)
                throws SMIMEException

Sets message content from String. This method can be performed only once. Message content can be given in two differrent forms: text and html code. If content is type of text, parameter "type" should be "text/plain", while if content is type of html code, parameter "type" should be set as "html/code". If html code content is set by this method, message will be generated withouth inclusion of the resources defined in paricular html element's attribute ("src" or "background"). Only plain html code will be sent and any reference to local file system resources will be useless for recipient of the message. HTTP referenced resources can still be available if recipient is online on Internet. Message generated on this way is smaller, so encrypting process should be faster.

Parameters:

content - message content data given as String which can be text or html code and will be interpreted according to second parameter: "type".

type - type of given content. It can take values: "text/plain" or "text/html".

Throws:

SMIMEException - if content is tried to be added twice, or in case of wrong "type" parameter. Also, it can be caused by non SMIMEException which can be one of the following: MessagingException UnsoportedEncodingException.

setContent

public void setContent(java.io.File inFile,
                       java.lang.String type)
                throws SMIMEException

Sets message content from file represented by File object. This method can be performed only once. Message content can be given in two differrent forms: text and html code. If content is type of text, parameter "type" should be "text/plain", while if content is type of html code, parameter "type" should be set as "html/code". For further information refer to setContent method with four arguments (String, String, String, InputStream[] ) which is called by this method.

Parameters:

inFile - location of file which is used for content of the message

type - type of given content. It can take values: "text/plain" or "text/html".

Throws:

SMIMEException - if content is tried to be added twice, in case of wrong "type" parameter, or if passed file (as File object) does not exist in file sistem. Also, it can be caused by non SMIMEException which can be one of the following: MessagingException or IOException.

setReply

public void setReply(java.lang.String replyAddress)
              throws SMIMEException

Sets REPLY TO field in message header

Parameters:

replyAddress - email address used to reply

Throws:

SMIMEException - caused by non SMIMEException which is MessagingException. Also, javax.mail.internet.AddressException is thrown from instances of InternetAddress class (but AddressException extends MessagingException).

addRecipient

public void addRecipient(java.lang.String recipientAddress,
                         java.lang.String type,
                         java.lang.String cerFileName)
                  throws SMIMEException

Adds recipient address, type and .cer file of email recipient to encrypted message.

Parameters:

recipientAddress - email address of recipent (fields TO or CC or BCC in email message header)

type - should be TO, CC or BCC

cerFileName - path and file name with certificate corresponding to recipient (file with .cer extension)

Throws:

SMIMEException - if type of addressing of messages is not TO, CC or BCC.

SMIMEException - caused by non SMIMEException which is MessagingException.

addAttachment

public void addAttachment(java.lang.String fileName)
                   throws SMIMEException

Adds file as attachment to email message

Parameters:

fileName - path and file name used for attachment

Throws:

SMIMEException - if passed file (as File object) does not exist in file sistem. Also, it can be caused by non SMIMEException which is MessagingException

addAttachment

public void addAttachment(java.io.File file)
                   throws SMIMEException

Adds file as attachment to email message

Parameters:

file - used for attachment represented as File object

Throws:

SMIMEException - if passed file (as File object) does not exist in file sistem. Also, it can be caused by non SMIMEException which is MessagingException

addAttachment

public void addAttachment(java.io.InputStream data,
                          java.lang.String fileName)
                   throws SMIMEException

Adds data from InputStream as attachment to email message

Parameters:

data - byte array from InputStream

fileName - virtual or real file name (wihouth path). Correct information about name; extension of file name is especially important. Name is used in construction of "name" parameter in Content-Type header line of body parts of mime message. Extension of file is used in detection of appropriate mime-type.

Throws:

SMIMEException - caused by non SMIMEException which is MessagingException

enveloping

public void enveloping()
                throws SMIMEException

Envelopes message with default algorithm RC2_CBC, 40 bits

Throws:

SMIMEException - if one of recipients is not declared as TO recipient, or if there is no message for enveloping. Also, it can be caused by non SMIMEException which can be one of the following: CertificateException, IOException, MessagingException or FileNotFoundException.

enveloping

public void enveloping(java.lang.String algorithmName,
                       int keyLength)
                throws SMIMEException

Envelopes message with given algorithm name and key length

Parameters:

algorithmName - name of chosen algorithm used for encryption

keyLength - key size in bits

Throws:

SMIMEException - if one of recipients is not declared as TO recipient, or if there is no message for enveloping. Also, it can be caused by non SMIMEException which can be one of the following: CertificateException, IOException, MessagingException or FileNotFoundException.

getEnvelopedMessage

public javax.mail.internet.MimeMessage getEnvelopedMessage()

Returns SMIME Message

Returns:

Enveloped S/MIME message

send

public void send()
          throws javax.mail.MessagingException

Sends S/MIME message to SMTP host

Throws:

javax.mail.MessagingException - caused by use of methods from objects of class Transport.