com.ibm.security.smime
Class SMIMESender

java.lang.Object
  |
  +--com.ibm.security.smime.SMIMESender

public final class SMIMESender
extends Object
implements Cloneable

Sends a S/MIME message to a recipient or writes the S/MIME message to a file. Construct this object with a PKCS #7 ContentInfo, PKCS #10 CertificationRequest, or a preconstructed SMIMEMessage object.

This definition reflects the S/MIME Version 2 Message Specification RFC 2311 specifications dated March 1998.

See Also:
SMIME

Constructor Summary
SMIMESender()
          Create an uninitialized SMIMESender object.
SMIMESender(byte[] der)
          Create a SMIMESender object with a DER byte array of a ContentInfo object.
SMIMESender(byte[] der, String provider)
          Create a SMIMESender object with a DER byte array of a ContentInfo object.
SMIMESender(CertificationRequest certRequest)
          Create a SMIMESender object with the specified CertificationRequest object.
SMIMESender(CertificationRequest certRequest, String provider)
          Create a SMIMESender object with the specified CertificationRequest object.
SMIMESender(ContentInfo contentInfo)
          Create a SMIMESender object with the specified ContentInfo object.
SMIMESender(ContentInfo contentInfo, String provider)
          Create a SMIMESender object with the specified ContentInfo object.
SMIMESender(SMIMEMessage message)
          Create a SMIMESender object with the specified SMIMEMessage object.
SMIMESender(SMIMEMessage message, String provider)
          Create a SMIMESender object with the specified SMIMEMessage object.
SMIMESender(String provider)
          Create an uninitialized SMIMESender object.
 
Method Summary
 void addRecipientCertificate(Certificate[] certs)
          Add an array of recipient certificates to the S/MIME message.
 Object clone()
          Creates a clone of this SMIMESender object.
 byte[] encrypt(int encryptionStrength)
          Encrypts the current ContentInfo with a generated secret key and encrypts the secret key with the recipient certificate(s) that were already specified for this SMIMESender object.
 byte[] encrypt(String encryptionAlgorithm, int keySize)
          Encrypts the current ContentInfo with a generated secret key and encrypts the secret key with the recipient certificate(s) that were already specified for this SMIMESender object.
 byte[] getBase64Content()
          Returns the BASE64 DER-encoded content of the ContentInfo or CertificationRequest that this SMIMESender object contains.
 CertificationRequest getCertificationRequest()
          Returns the CertificationRequest object for this SMIMESender object.
 ContentInfo getContentInfo()
          Returns a copy of the ContentInfo object for this SMIMESender object.
 String getFileName()
          Returns the value for the filename Content-Disposition MIME attribute.
 String getMailhost()
          Get the mailhost value for this SMIMESender object.
 String getSMIMEType()
          Returns the value for the smime-type Content-Type MIME attribute.
 boolean hasRecipientCertificate()
          Check if this SMIMESender object contains one or more recipient certificates.
 void mail(byte[] message, String senderAddress, String recipientAddress, String subject)
          Mails the specified byte array message to the specified recipient address via SMTP.
 void mail(String senderAddress, String recipientAddress, String subject)
          Mails the SMIMEMessage to the specified recipient address via SMTP.
 void setCertificateOnly(Certificate[] certs)
          Set the ContentInfo object to a certificate-only SignedData object with the specified certificate array.
 void setCertificationRequest(CertificationRequest certRequest)
          Set the CertificationRequest object for this SMIMESender object.
 void setContentInfo(ContentInfo contentInfo)
          Set the ContentInfo object for this SMIMESender object.
 void setMailhost(String mailhost)
          Set the mailhost value for this SMIMESender object.
 void setMessageWithHeader(String message)
          Creates a ContentInfo Data object with the specified message and predefined MIME header for this SMIMESender object.
 void setRecipientCertificate(Certificate[] certs)
          Set the recipient certificates for the S/MIME message.
 byte[] sign(Certificate signerCert, String digestSignatureAlgorithm, PrivateKey privateKey)
          Signs the current ContentInfo with the specified certificate and private key.
 byte[] signSignatureOnly(Certificate signerCert, String digestSignatureAlgorithm, PrivateKey privateKey)
          Signs the current ContentInfo with the specified certificate and private key.
 String toString()
          Returns a string representation of this SMIMESender object.
 void writeMailToFile(byte[] message, String filename, String senderAddress, String recipientAddress, String subject)
          Writes the specified byte array to the specified file.
 void writeMailToFile(String filename, String senderAddress, String recipientAddress, String subject)
          Writes the SMIMEMessage to the specified file.
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

SMIMESender

public SMIMESender()
Create an uninitialized SMIMESender object. This uninitialized object can be initialized with a ContentInfo, CertificationRequest, or an array of Certificate objects at a later time.

SMIMESender

public SMIMESender(String provider)
Create an uninitialized SMIMESender object. This uninitialized object can be initialized with a ContentInfo, CertificationRequest, or an array of Certificate objects at a later time.

SMIMESender

public SMIMESender(byte[] der)
            throws IOException
Create a SMIMESender object with a DER byte array of a ContentInfo object.
Parameters:
der - a DER byte array of a ContentInfo object.
Throws:
IOException - on decoding errors.

SMIMESender

public SMIMESender(byte[] der,
                   String provider)
            throws IOException
Create a SMIMESender object with a DER byte array of a ContentInfo object.
Parameters:
der - a DER byte array of a ContentInfo object.
provider - the provider to be used with pkcs.
Throws:
IOException - on decoding errors.

SMIMESender

public SMIMESender(ContentInfo contentInfo)
Create a SMIMESender object with the specified ContentInfo object. This constructor will make a clone of the ContentInfo object.
Parameters:
contentInfo - ContentInfo object

SMIMESender

public SMIMESender(ContentInfo contentInfo,
                   String provider)
Create a SMIMESender object with the specified ContentInfo object. This constructor will make a clone of the ContentInfo object.
Parameters:
contentInfo - ContentInfo object
provider - the provider to be used with pkcs

SMIMESender

public SMIMESender(CertificationRequest certRequest)
Create a SMIMESender object with the specified CertificationRequest object. This constructor will make a clone of the CertificationRequest object.
Parameters:
contentInfo - ContentInfo object

SMIMESender

public SMIMESender(CertificationRequest certRequest,
                   String provider)
Create a SMIMESender object with the specified CertificationRequest object. This constructor will make a clone of the CertificationRequest object.
Parameters:
contentInfo - ContentInfo object
provider - the provider to be used with pkcs

SMIMESender

public SMIMESender(SMIMEMessage message)
            throws IOException
Create a SMIMESender object with the specified SMIMEMessage object. This constructor will create a ContentInfo of the Data type with the byte array representation of the SMIMEMesasge object.
Parameters:
SMIMEMessage - SMIMEMessage object

SMIMESender

public SMIMESender(SMIMEMessage message,
                   String provider)
            throws IOException
Create a SMIMESender object with the specified SMIMEMessage object. This constructor will create a ContentInfo of the Data type with the byte array representation of the SMIMEMesasge object.
Parameters:
SMIMEMessage - SMIMEMessage object
provider - the provider to be used
Method Detail

clone

public Object clone()
Creates a clone of this SMIMESender object.
Overrides:
clone in class Object
Returns:
clone of this SMIMESender object.

hasRecipientCertificate

public boolean hasRecipientCertificate()
Check if this SMIMESender object contains one or more recipient certificates.
Returns:
true if one or more recipient certificates were set; false, otherwise.

addRecipientCertificate

public void addRecipientCertificate(Certificate[] certs)
Add an array of recipient certificates to the S/MIME message. This method aids in the creation of the EnvelopedData object as part of the encrypt method.
Parameters:
certs - Certificate array

setRecipientCertificate

public void setRecipientCertificate(Certificate[] certs)
Set the recipient certificates for the S/MIME message. This method aids in the creation of the EnvelopedData object as part of the encrypt method.
Parameters:
certs - Certificate array

setCertificateOnly

public void setCertificateOnly(Certificate[] certs)
                        throws IOException,
                               PKCSException
Set the ContentInfo object to a certificate-only SignedData object with the specified certificate array. The generated SignedData object will be placed within a ContentInfo object, which in turn will be stored in this SMIMESender object. This method aids in the creation of a p7c certs-only SMIME message.
Parameters:
certs - Certificate array
Throws:
IOException - on SignedData construction errors.
PKCSException - if the ContentInfo or CertificationRequest value was already set.

setContentInfo

public void setContentInfo(ContentInfo contentInfo)
                    throws PKCSException
Set the ContentInfo object for this SMIMESender object. This method will make a clone of the ContentInfo object.
Parameters:
contentInfo - ContentInfo object
Throws:
PKCSException - if the ContentInfo or CertificationRequest value was already set.

getContentInfo

public ContentInfo getContentInfo()
Returns a copy of the ContentInfo object for this SMIMESender object.
Returns:
ContentInfo object

setCertificationRequest

public void setCertificationRequest(CertificationRequest certRequest)
                             throws PKCSException
Set the CertificationRequest object for this SMIMESender object. This method will make a clone of the CertificationRequest object.
Parameters:
certRequest - CertificationRequest object
Throws:
PKCSException - if the ContentInfo or CertificationRequest value was already set.

getCertificationRequest

public CertificationRequest getCertificationRequest()
Returns the CertificationRequest object for this SMIMESender object. CertificationRequest objects are immutable.
Returns:
CertificationRequest object

setMailhost

public void setMailhost(String mailhost)
Set the mailhost value for this SMIMESender object.
Parameters:
mailhost - SMTP mail host address

getMailhost

public String getMailhost()
Get the mailhost value for this SMIMESender object.
Returns:
mailhost String

setMessageWithHeader

public void setMessageWithHeader(String message)
                          throws PKCSException
Creates a ContentInfo Data object with the specified message and predefined MIME header for this SMIMESender object. The following header is appended before the message is stored in the Data object: Content-Type: text/plain; charset="us-ascii"\r\n\r\n

To specify a different header, create the Data object independently and store it as a ContentInfo object on an uninitialized SMIMESender object.

Parameters:
message - String to set as the message contents.
Throws:
PKCSException - on Data creation error or if the ContentInfo or CertificationRequest for this SMIMESender object was already set.

encrypt

public byte[] encrypt(int encryptionStrength)
               throws PKCSException,
                      IOException,
                      NoSuchAlgorithmException
Encrypts the current ContentInfo with a generated secret key and encrypts the secret key with the recipient certificate(s) that were already specified for this SMIMESender object. The ContentInfo for this SMIMESender object will change to EnvelopedData. This method will create a EnvelopedData object of the p7m type.

This method requires that the recipient certificate(s) must have been previously set on this SMIMESender object.

Parameters:
encryptionStrength - specified by SMIME.WEAK_ENCRYPTION, SMIME.MEDIUM_ENCRYPTION, or SMIME.STRONG_ENCRYPTION
Throws:
IOException - on encryption error.
PKCSException - key encryption error.
NoSuchAlgorithmException - on invalid algorithm error.

encrypt

public byte[] encrypt(String encryptionAlgorithm,
                      int keySize)
               throws PKCSException,
                      IOException,
                      NoSuchAlgorithmException
Encrypts the current ContentInfo with a generated secret key and encrypts the secret key with the recipient certificate(s) that were already specified for this SMIMESender object. The ContentInfo for this SMIMESender object will change to EnvelopedData. This method will create a EnvelopedData object of the p7m type.

This method requires that the recipient certificate(s) must have been previously set on this SMIMESender object.

Parameters:
encryptionAlgorithm - encryption algorithm String
keySize - length of the encryption key
Returns:
byte array of the S/MIME message
Throws:
IOException - on encryption error.
PKCSException - key encryption error.
NoSuchAlgorithmException - on invalid algorithm error.

sign

public byte[] sign(Certificate signerCert,
                   String digestSignatureAlgorithm,
                   PrivateKey privateKey)
            throws PKCSException,
                   IOException,
                   NoSuchAlgorithmException
Signs the current ContentInfo with the specified certificate and private key. The ContentInfo for this SMIMESender object will change to SignedData. This method will create a SignedData object of the p7m type.
Parameters:
signerCert - certificate of the signer
privateKey - private key of the certificate
digestSignatureAlgorithm - signature algorithm
Returns:
byte array of the S/MIME message
Throws:
PKCSException - on signing error.
IOException - on signing error.
NoSuchAlgorithmException - on signing error.

signSignatureOnly

public byte[] signSignatureOnly(Certificate signerCert,
                                String digestSignatureAlgorithm,
                                PrivateKey privateKey)
                         throws PKCSException,
                                IOException,
                                NoSuchAlgorithmException
Signs the current ContentInfo with the specified certificate and private key. This method will change the ContentInfo for this SMIMESender object to SignedData and remove the content from the SignedData's EncapsulatedContentInfo. This method will create a SignedData object of the p7s type and return a multipart S/MIME message in a byte array.

For the S/MIME message byte array returned by the signSignatureOnly method, use the mail method that accepts a byte array, otherwise the generated multipart message will not be mailed.

Parameters:
signerCert - certificate of the signer
privateKey - private key of the certificate
digestSignatureAlgorithm - signature algorithm
Returns:
byte array of the multipart S/MIME message
Throws:
PKCSException - on signing error.
IOException - on signing error.
NoSuchAlgorithmException - on signing error.

getBase64Content

public byte[] getBase64Content()
                        throws IOException
Returns the BASE64 DER-encoded content of the ContentInfo or CertificationRequest that this SMIMESender object contains.

getSMIMEType

public String getSMIMEType()
Returns the value for the smime-type Content-Type MIME attribute. If this SMIMESender object contains a CertificationRequest object, this method will return null.

getFileName

public String getFileName()
Returns the value for the filename Content-Disposition MIME attribute. This value depends on the CertificationRequest or ContentInfo object that this SMIMESender object contains.

mail

public void mail(String senderAddress,
                 String recipientAddress,
                 String subject)
          throws PKCSException,
                 IOException
Mails the SMIMEMessage to the specified recipient address via SMTP. The S/MIME message is composed of the stored PKCS #7 ContentInfo or PKCS #10 CertificationRequest object for this SMIMESender object.

For the S/MIME message byte array returned by the signSignatureOnly method, use the mail method that accepts a byte array, otherwise the generated multipart message will not be mailed.

The recipientAddress and recipient certificates for this object govern to whom this message is sent:

Parameters:
senderAddress - e-mail address of the sender
recipientAddress - e-mail address of the recipient.
subject - Subject of the message
Throws:
PKCSException - on mailing error.
IOException - on mailing error.

mail

public void mail(byte[] message,
                 String senderAddress,
                 String recipientAddress,
                 String subject)
          throws PKCSException,
                 IOException
Mails the specified byte array message to the specified recipient address via SMTP. This method can be used to send the byte array returned from the sign and encrypt methods.

The recipientAddress and recipient certificates for this object govern to whom this message is sent:

Parameters:
message - Byte array of the message
senderAddress - e-mail address of the sender
recipientAddress - e-mail address of the recipient.
subject - Subject of the message
Throws:
PKCSException - on mailing error.
IOException - on mailing error.

writeMailToFile

public void writeMailToFile(String filename,
                            String senderAddress,
                            String recipientAddress,
                            String subject)
                     throws PKCSException,
                            IOException
Writes the SMIMEMessage to the specified file. The S/MIME message is composed of the stored PKCS #7 ContentInfo or PKCS #10 CertificationRequest object for this SMIMESender object.

The recipientAddress and recipient certificates for this object govern to whom this message is sent:

If there are more than one recipientAddress e-mails, the method will append a "." + filenumber string to the end of the specified filename.

Parameters:
filename - File name to which to write
senderAddress - e-mail address of the sender
recipientAddress - e-mail address of the recipient.
subject - Subject of the message
Throws:
PKCSException - on writing error.
IOException - on writing error.

writeMailToFile

public void writeMailToFile(byte[] message,
                            String filename,
                            String senderAddress,
                            String recipientAddress,
                            String subject)
                     throws PKCSException,
                            IOException
Writes the specified byte array to the specified file. This method should be used with the returned byte array from the signSignatureOnly method to write a multipart S/MIME message. This method can also be used to write the byte array returned from the sign and encrypt methods as a S/MIME message.

The recipientAddress and recipient certificates for this object govern to whom this message is sent:

If there are more than one recipientAddress e-mails, the method will append a "." + filenumber string to the end of the specified filename.

Parameters:
message - Byte array of the message
filename - File name to which to write
senderAddress - e-mail address of the sender
recipientAddress - e-mail address of the recipient.
subject - Subject of the message
Throws:
PKCSException - on writing error.
IOException - on writing error.

toString

public String toString()
Returns a string representation of this SMIMESender object. Returns the contained ContentInfo or CertificationRequest object.
Overrides:
toString in class Object
Returns:
a string representation of this object.