Enhydra-Oyster 2.1-7 API

org.enhydra.oyster.smime
Class EnvelopedSMIME

java.lang.Object
  extended byorg.enhydra.oyster.smime.BaseSMIMEObject
      extended byorg.enhydra.oyster.smime.EnvelopedSMIME
All Implemented Interfaces:
EnvelopedConstants, KeyStoreConstants

public class EnvelopedSMIME
extends BaseSMIMEObject
implements EnvelopedConstants

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:

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


Field Summary
 
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.EnvelopedConstants
DES, DES_EDE3_CBC, RC2_CBC
 
Fields inherited from interface org.enhydra.oyster.crypto.consts.KeyStoreConstants
BKS, JKS, PKCS12, UBER
 
Constructor Summary
protected EnvelopedSMIME()
          Simple constructor.
  EnvelopedSMIME(javax.mail.internet.MimeMessage mimeMessage)
          Construction of message with external prepared MimeMessage object.
  EnvelopedSMIME(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.
  EnvelopedSMIME(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, java.security.KeyStore kStore, java.lang.String alias)
          Adds recipient address, type and recipient's certificate via KeyStore object and apropriate alias.
 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 addRecipient(java.lang.String recipientAddress, java.lang.String type, java.lang.String ksPath, java.lang.String ksType, java.lang.String password, java.lang.String alias)
          Adds recipient address, type and recipient's certificate via path to the KeyStore file, KeyStore type, password and apropriate alias.
 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()
          Deprecated.  
 
Methods inherited from class org.enhydra.oyster.smime.BaseSMIMEObject
addAttachment, addAttachment, addAttachment, addAttachment, addAttachment, addAttachment, getMimeMessage, initMimeMessage, reset, 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

EnvelopedSMIME

protected EnvelopedSMIME()
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.


EnvelopedSMIME

public EnvelopedSMIME(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.

EnvelopedSMIME

public EnvelopedSMIME(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.

EnvelopedSMIME

public EnvelopedSMIME(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,
                         java.lang.String cerFileName)
                  throws SMIMEException
Adds recipient address, type and .cer file of email recipient to encrypted message. At least one recipient must be declared as TO type.

Overrides:
addRecipient in class BaseSMIMEObject
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 the messages is not TO, CC, or BCC. Also it can be caused by non SMIMEException which is MessagingException.

addRecipient

public void addRecipient(java.lang.String recipientAddress,
                         java.lang.String type,
                         java.security.KeyStore kStore,
                         java.lang.String alias)
                  throws SMIMEException
Adds recipient address, type and recipient's certificate via KeyStore object and apropriate alias. Certificate information should be passed only in the case of Enveloped message or Signed and Enveloped message. Otherwise those arguments represent redundance values and they should be given as null.

Overrides:
addRecipient in class BaseSMIMEObject
Parameters:
recipientAddress - email address of recipent (fields TO or CC or BCC in email message header)
type - should be TO, CC or BCC
kStore - instance of KeyStore class which represents an in-memory collection of keys and certificates.
alias - alias name which corresponds to desired certificate. If alias is given as null, then reading results are unpredictable.
Throws:
SMIMEException - if type of addressing of messages is not TO, CC or BCC. Also, it can be caused by non SMIMEException which can be one of the following: IOException, MessagingException, FileNotFoundException, NoSuchProviderException, CertificateException.

addRecipient

public void addRecipient(java.lang.String recipientAddress,
                         java.lang.String type,
                         java.lang.String ksPath,
                         java.lang.String ksType,
                         java.lang.String password,
                         java.lang.String alias)
                  throws SMIMEException
Adds recipient address, type and recipient's certificate via path to the KeyStore file, KeyStore type, password and apropriate alias. Certificate information should be passed only in the case of Enveloped message or Signed and Enveloped message. Otherwise those arguments represent redundance values and they should be given as null.

Overrides:
addRecipient in class BaseSMIMEObject
Parameters:
recipientAddress - email address of recipent (fields TO or CC or BCC in email message header)
type - should be TO, CC or BCC
ksPath - is path to the file representation of KeyStore which holds collection of keys and certificates. This file can be PKCS12 type (file with .p12 or .pfx extension) or can be key store of other types readable by 'BouncyCastle' or 'Sun' KeyStore implementation.
ksType - is type of KeyStore. It can be one of the following types: JKS for 'Sun' KeyStore, 'BKS', 'PKCS12' or 'UBER') for 'BouncyCastle' KeyStore. If ksType is given as null it will be assumed that .cer file is in use, and alias parameter will be ignored, so this method becomes equivalent to addRecipient() method which deal only with .cer files.
password - password used to access the corresponding private key, stored in given KeyStore file.
alias - alias name which corresponds to desired private key. If alias is given as null, then reading results are unpredictable. to recipient (file with .cer extension)
Throws:
SMIMEException - if type of addressing of messages is not TO, CC or BCC. Also, it can be caused by non SMIMEException which can be one of the following: IOException, MessagingException, FileNotFoundException, NoSuchProviderException, CertificateException.

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

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

Returns:
Enveloped S/MIME message

Enhydra-Oyster 2.1-7 API