org.webdocwf.util.smime.smime
Class SignedSMIME

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

public class SignedSMIME
extends java.lang.Object

SignedSMIME class is used for creating and sending signed 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:

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.

Message can be external (explicit) or internal (implicit) signed. External signing allows email receiving clients wihouth implemented SMIME capabilities to preview the signed SMIME email messages.

Message can be signed with or without Signed Attributes. Signed Attributes are one optional part of CMS (Cryptographic Message Syntax) signed objects, and consist of some atributes used in the process of signing (date and time of signing, capabilities of sending email client, message digest value...). If those attributes are ommited, only pure message is taken in the process of signing.

Digest algorithm can be SHA1, MD2 or MD5 which depends on selected signing algorithm.

Capabilities Attributes are one of Signed Attributes, and in the process of signing (if Signed Attributes are involved) can be set. This attributes indicate to recipient email client which encipher, symmetric and/or signature algorithms signer's email client preferes, and they can be used in the next communication between each others. Setting this posibilities is optional, but if it is set, order of adding gives the information about most preferes algorithms within paricular group of algorithms. Defined Capabilities Attributes in this version of Signed SMIME can be from group: RC2 40, RC2 64, RC2 128, DES and DES_EDE3 for symmetric encryption algorihms, from group: MD2 with RSA, MD5 with RSA, SHA1 with RSA and SHA1 with DSA for signing algorithms, and RSA for encipher algorithm. For more information see setCapabilities method in this class.

Certificates of signers and their root authorities can be included in the signed message. This posibilities allow the recipient of signed SMIME message to automatically include signer's certificates as trusted, and verify signed message. This posibilities are optional.

More than one signer can perform signing of message and they can use different signing algorithms. Digital signing can be performed by SHA1_WITH_RSA, MD2_WITH_RSA, MD5_WITH_RSA or SHA1_WITH_DSA.


Constructor Summary
SignedSMIME(java.lang.String smtpHost, java.lang.String fromAddress, java.lang.String subject)
          Initializes the JavaMail session for SMTP and MimeMessage for signing.
SignedSMIME(java.lang.String smtpHost, java.lang.String fromAddress, java.lang.String subject, java.lang.String content)
          Initializes the JavaMail session for SMTP and MimeMessage for signing.
 
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 addCertificate(java.security.cert.X509Certificate cert)
          Adds additional certificate to signed message.
 void addRecipient(java.lang.String recipientAddress, java.lang.String type)
          Adds recipient address, type and .cer file of email recipient.
 void addSigner(java.lang.String pfxfileName, java.lang.String password, java.lang.String signingAlg, boolean includingCert, boolean includingSignAttrib)
          Adds signer to signed S/MIME message
 void addSigner(java.security.cert.X509Certificate[] chain, java.security.PrivateKey privKey, java.lang.String signingAlg, boolean includingCert, boolean includingSignAttrib)
          Adds signer to signed S/MIME message
 javax.mail.internet.MimeMessage getSignedMessage()
          Returns SMIME Message
 void send()
          Sends S/MIME message to SMTP host
 void setCapabilities(java.lang.String type0, int par10, int par20, int par30, int par40, int par50)
          Sets Capabilities Attributes (method is optional, but if exists, must be performed before addSigner method).
 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
 void signing()
          Creates and signes the message with default implicit signing.
 void signing(boolean externalSignature)
          Creates and signes the message
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

SignedSMIME

public SignedSMIME(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 MimeMessage for signing. 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 the 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.

SignedSMIME

public SignedSMIME(java.lang.String smtpHost,
                   java.lang.String fromAddress,
                   java.lang.String subject)
            throws SMIMEException
Initializes the JavaMail session for SMTP and MimeMessage for signing. 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.


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 for 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)
                  throws SMIMEException
Adds recipient address, type and .cer file of email recipient.
Parameters:
recipientAddress - email address of recipent (fields TO or CC or BCC in email message header)
type - should be TO, CC or BCC.
Throws:
SMIMEException - if type of addressing of the 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

setCapabilities

public void setCapabilities(java.lang.String type0,
                            int par10,
                            int par20,
                            int par30,
                            int par40,
                            int par50)
                     throws SMIMEException
Sets Capabilities Attributes (method is optional, but if exists, must be performed before addSigner method). Depending on parameter type0, other five parameters make order in specific group of algorithms. Groups of algorithms with positions of specific algorithms are:
(SIGNATURE, MD2 with RSA, MD5 with RSA, SHA1 with RSA, SHA1 with DSA, Unused field)
(SYMMETRIC, RC2 40 bits, RC2 64 bits, RC2 128 bits, DES, DES_EDE3)
(ENCIPHER, RSA, Unused field, Unused field, Unused field, Unused field)

For example, if we wish to set Capabilities Attributes for symmetric algorithms in order: RC2 64 bits, RC2 40 bits and DES, encipher algorithm RSA (only possible in this version), and signature algorithms in order: SHA1 with RSA, MD5 with RSA and MD2 with RSA, we should make following lines of code

setCapabilities ("SYMMETRIC", 2, 1, 0, 3, 0)
setCapabilities ("ENCIPHER", 1, 0, 0, 0, 0)
setCapabilities ("SIGNATURE", 3, 2, 1, 0, 0)

0 means exclusion of algorithm from the specified position in the method. It is free to decide which algorithm will be included, or which group of algorithm will be included in Capabilities Attributes. If no groups are added, capabilities attributes won't be added to Signed Attributes. If two or more signers will sign the message, and their capabilities are different, this method should be performed before every signing if we wish to specify Capabilities Attributes for all particular signers. If type0 parameter is set as:
setCapabilities ("DEFAULT", 0, 0, 0, 0, 0)
it is equivalent to:
setCapabilities ("SYMMETRIC", 1, 0, 0, 0, 0)
setCapabilities ("ENCIPHER", 0, 0, 1, 0, 0)
setCapabilities ("SIGNATURE", 1, 0, 0, 0, 0)
Parameters:
type0 - sets group of algorithms for capabilities attributes. It can be set with values: SIGNATURE, SYMMETRIC, ENCIPHER or DEFAULT.
par10 - sets order in group of parameters, or exclude some algorithms from capabilities atributes. Can take values 1, 2, 3, 4 or 5 and 0 for exclusion of the particular algorithm.
par20 - same as for par10
par30 - same as for par10
par40 - same as for par10
par50 - same as for par10
Throws:
SMIMEException - if method is performed more than three times for one signer, or in case of wrong values of parameters.

addSigner

public void addSigner(java.lang.String pfxfileName,
                      java.lang.String password,
                      java.lang.String signingAlg,
                      boolean includingCert,
                      boolean includingSignAttrib)
               throws SMIMEException
Adds signer to signed S/MIME message
Parameters:
pfxfileName - path and file name with certificate and private key corresponding to the sender of the message (file with .p12 or .pfx extension)
password - used to access to .pfx or .p12 file
signingAlg - algorithm used for signing (can be SHA1_WITH_RSA, MD2_WITH_RSA, MD5_WITH_RSA or SHA1_WITH_DSA).
includingCert - including/not including certificates to signed message
includingSignAttrib - including/not including signed attributes to signed message. Must be set to true in case of implicit signing
Throws:
SMIMEException - caused by non SMIMEException which can be one of the following: FileNotFoundException, NoSuchProviderException, KeyStoreException CertificateException, NoSuchAlgorithmException or IOException.

addSigner

public void addSigner(java.security.cert.X509Certificate[] chain,
                      java.security.PrivateKey privKey,
                      java.lang.String signingAlg,
                      boolean includingCert,
                      boolean includingSignAttrib)
Adds signer to signed S/MIME message
Parameters:
chain - certificate chain. First certificate in array must be owner's certificate, and last certificate has to be root certificate
privKey - private key corresponding to owner's certificate (DSA or RSA depend on type of signing)
signingAlg - algorithm used for signing (can be SHA1_WITH_RSA, MD2_WITH_RSA, MD5_WITH_RSA or SHA1_WITH_DSA).
includingCert - including/not including certificates to signed message
includingSignAttrib - including/not including signed attributes to signed message. Must be set to true in case implicit signing

addCertificate

public void addCertificate(java.security.cert.X509Certificate cert)
Adds additional certificate to signed message.
Parameters:
cert - X509 certificate.

signing

public void signing()
             throws SMIMEException
Creates and signes the message with default implicit signing.
Throws:
SMIMEException - if one of recipients is not declared as TO recipient, or if there is no message for signing. Also, it can be caused by non SMIMEException which can be one of the following: MessagingException or IOException.

signing

public void signing(boolean externalSignature)
             throws SMIMEException
Creates and signes the message
Parameters:
externalSignature - choice between implicit and explicit signing (true = explicit or external signing, false = implicit or internal signing).
Throws:
SMIMEException - if one of recipients is not declared as TO recipient, or if there is no message for signing. Also, it can be caused by non SMIMEException which can be one of the following: MessagingException, or IOException.

getSignedMessage

public javax.mail.internet.MimeMessage getSignedMessage()
Returns SMIME Message
Returns:
Signed 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.


Copyright © 2002-2002 Together Teamlösungen. All Rights Reserved.