Enhydra-Oyster 2.1-7 API

org.enhydra.oyster.smime
Class SignedSMIME

java.lang.Object
  extended byorg.enhydra.oyster.smime.BaseSMIMEObject
      extended byorg.enhydra.oyster.smime.BaseSignedSMIMEObject
          extended byorg.enhydra.oyster.smime.SignedSMIME
All Implemented Interfaces:
KeyStoreConstants, SignedConstants

public class SignedSMIME
extends BaseSignedSMIMEObject

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 creates 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 to 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 specific 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.


Field Summary
 
Fields inherited from class org.enhydra.oyster.smime.BaseSignedSMIMEObject
aditionalCerts, capabilities, capabilities2, capabilitiesTemp, certChainArray, digestArray, digestArray2, including, including2, ksArray, privKeyArray
 
Fields inherited from class org.enhydra.oyster.smime.BaseSMIMEObject
bodyPartArray, certArray, charsetEnc, contentPresence, externalMessagePresence, indicatorTo, message
 
Fields inherited from interface org.enhydra.oyster.crypto.consts.SignedConstants
MD2_WITH_RSA, MD5_WITH_RSA, SHA1_WITH_DSA, SHA1_WITH_RSA
 
Fields inherited from interface org.enhydra.oyster.crypto.consts.KeyStoreConstants
BKS, JKS, PKCS12, UBER
 
Constructor Summary
protected SignedSMIME()
          Simple constructor.
  SignedSMIME(javax.mail.internet.MimeMessage mimeMessage)
          Construction of message with external prepared MimeMessage object.
  SignedSMIME(java.lang.String smtpHost, java.lang.String fromAddress, java.lang.String subject, java.lang.String charset)
          Initializes the JavaMail session for SMTP and the MimeMessage object for message which will be sent.
  SignedSMIME(java.lang.String smtpHost, java.lang.String fromAddress, java.lang.String subject, java.lang.String content, java.lang.String charset)
          Initializes the JavaMail session for SMTP and the MimeMessage object for message which will be sent.
 
Method Summary
 void addRecipient(java.lang.String recipientAddress, java.lang.String type)
          Adds recipient email address and type.
 javax.mail.internet.MimeMessage getSignedMessage()
          Deprecated.  
 void signing()
          Creates and signes the message with default implicit signing.
 void signing(boolean externalSignature)
          Creates and signes the message.
 
Methods inherited from class org.enhydra.oyster.smime.BaseSignedSMIMEObject
addCertificate, addSigner, addSigner, addSigner, addSigner, reset, setCapabilities
 
Methods inherited from class org.enhydra.oyster.smime.BaseSMIMEObject
addAttachment, addAttachment, addAttachment, addAttachment, addAttachment, addAttachment, addRecipient, addRecipient, addRecipient, getMimeMessage, initMimeMessage, send, setCharsetEncoding, setContent, setContent, setContent, setContent, setContent, setContent, setContent, setContent, setContent, setContent, setReply
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

SignedSMIME

protected SignedSMIME()
Simple constructor. Dynamically loads the BC and SUN provider necessary for cryptography processing. This constructor does not create MIME message object, so it is obligatory to invoke initMimeMessage() method after this constructor.


SignedSMIME

public SignedSMIME(java.lang.String smtpHost,
                   java.lang.String fromAddress,
                   java.lang.String subject,
                   java.lang.String content,
                   java.lang.String charset)
            throws SMIMEException
Initializes the JavaMail session for SMTP and the MimeMessage object for message which will be sent. Dynamically loads the BC and SUN provider necessary for cryptography processing. 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). This argument can be null, but email message will be sent withouth SUBJECT.
content - text/plain content of email message. This argument can be null, but later one of setContent() methods or one of addAttachment() methods should be called
charset - character set for passed subject and content. The given Unicode string will be charset-encoded using the specified charset. The charset is also used to set the "charset" parameter. For example German letters should be encoded by usage of 'ISO-8859-1' charset. If charset parameter is null and subject or content contains non US-ASCII characters, it will be encoded using the platform's default charset.
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,
                   java.lang.String charset)
            throws SMIMEException
Initializes the JavaMail session for SMTP and the MimeMessage object for message which will be sent. Dynamically loads the BC and SUN provider necessary for cryptography processing. 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). This argument can be null, but email message will be sent withouth SUBJECT.
charset - character set for passed subject and content. The given Unicode string will be charset-encoded using the specified charset. The charset is also used to set the "charset" parameter. For example German letters should be encoded by usage of 'ISO-8859-1' charset. If charset parameter is null and subject or content contains non US-ASCII characters, it will be encoded using the platform's default charset.
Throws:
SMIMEException - if smtpHost or fromAddress parameters are null. Also, it can be caused by non SMIMEException which is MessagingException.

SignedSMIME

public SignedSMIME(javax.mail.internet.MimeMessage mimeMessage)
            throws SMIMEException
Construction of message with external prepared MimeMessage object. Usage of this constructor disables usage of setContent() and addAttachment() methods. Also, all recipients (TO, CC or BCC type) must be declared again via setRecipient() method, even if they were previously set. Be very carefull with usage of this constructor because all MimeBodyPart objects and MimeMultipart objects used in construction of given MimeMessage object, must have correct defined Content header arguments, and contents. Contents must be formed in format which can be recognised and appropriate interpreted in the process of sending mail. If there is any special content object added to MimeBodyPart object or MimeMultipart object, the appropriate DataContent handler must be created for that object and set to corresponding BodyPart.

Parameters:
mimeMessage - external created MimeMessage object
Throws:
SMIMEException - if smtpHost or fromAddress parameter is null. Also, it can be caused by non SMIMEException which is MessagingException.
Method Detail

addRecipient

public void addRecipient(java.lang.String recipientAddress,
                         java.lang.String type)
                  throws SMIMEException
Adds recipient email address and type. At least one recipient must be declared as TO type.

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. Also it can be caused by non SMIMEException which is MessagingException.

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()
Deprecated.  

Returns SMIME Message. This method returns same object as getMimeMessage() method located in super class and will be removed in future release.

Returns:
Signed S/MIME message

Enhydra-Oyster 2.1-7 API