com.ibm.security.smime.jmail
Class SMIMEMimeMessage

com.ibm.security.smime.jmail.SMIMEMimeMessage

public class SMIMEMimeMessage

This class allows construction of SMIMEMimeMessage objects that can be used to send S/MIME PKCS #7 and #10 messages.

S/MIME PKCS #7 messages include:

S/MIME PKCS #7 messages utilize the PKCS7MimeDataSource and PKCS7MimeHandler classes. Use the SMIMEMimeMultipart class to send a multipart/signed message with detached contents.

S/MIME PKCS #10 messages are used to send CertificationRequest objects and these messages utilize the PKCS10MimeDataSource and PKCS10MimeHandler classes.

See Also:
SMIME, SMIMEMimeMultipart, PKCS7MimeDataSource, PKCS7MimeHandler, PKCS10MimeDataSource, PKCS10MimeHandler

Constructor Summary
protected SMIMEMimeMessage(com.ibm.security.smime.jmail.Folder folder, InputStream is, int msgnum)
          Constructs a MimeMessage by reading and parsing the data from the specified MIME InputStream.
protected SMIMEMimeMessage(com.ibm.security.smime.jmail.Folder folder, InputStream is, int msgnum, String provider)
          Constructs a MimeMessage by reading and parsing the data from the specified MIME InputStream.
protected SMIMEMimeMessage(com.ibm.security.smime.jmail.Folder folder, int msgnum)
          Constructs an empty MimeMessage object with the given Folder and message number.
protected SMIMEMimeMessage(com.ibm.security.smime.jmail.Folder folder, com.ibm.security.smime.jmail.InternetHeaders headers, byte[] content, int msgnum)
          Constructs a MimeMessage from the given InternetHeaders object and content.
protected SMIMEMimeMessage(com.ibm.security.smime.jmail.Folder folder, com.ibm.security.smime.jmail.InternetHeaders headers, byte[] content, int msgnum, String provider)
          Constructs a MimeMessage from the given InternetHeaders object and content.
protected SMIMEMimeMessage(com.ibm.security.smime.jmail.Folder folder, int msgnum, String provider)
          Constructs an empty MimeMessage object with the given Folder and message number.
  SMIMEMimeMessage(com.ibm.security.smime.jmail.Session session)
          Default constructor.
  SMIMEMimeMessage(com.ibm.security.smime.jmail.Session session, InputStream is)
          Constructs a MimeMessage by reading and parsing the data from the specified MIME InputStream.
  SMIMEMimeMessage(com.ibm.security.smime.jmail.Session session, InputStream is, String provider)
          Constructs a MimeMessage by reading and parsing the data from the specified MIME InputStream.
  SMIMEMimeMessage(com.ibm.security.smime.jmail.Session session, String provider)
          Default constructor.
 
Method Summary
 void addRecipientCertificate(Certificate[] certs)
          Add an array of recipient certificates to the S/MIME message.
 ContentInfo decrypt(PrivateKey recipientPrivateKey, Certificate recipientCert)
          Decrypts the ContentInfo that contains an EnvelopedData object for this SMIMEMimeMessage object.
 void encrypt(Object message, int encryptionStrength)
          Encrypts the message with a generated secret key and encrypts the secret key with the recipient certificate(s) that were already specified for this SMIMEMimeMessage object.
 void encrypt(Object message, String encryptionAlgorithm, int keySize)
          Encrypts the message with a generated secret key and encrypts the secret key with the recipient certificate(s) that were already specified for this SMIMEMimeMessage object.
 CertificationRequest getCertificationRequest()
          Returns the CertificationRequest object contained within this SMIMEMimeMessage, if any.
 ContentInfo getContentInfo()
          Returns a copy of the ContentInfo object contained within this SMIMEMimeMessage, if any.
 boolean isCertificationRequest()
          Returns whether or not this SMIMEMimeMessage is a pkcs10 message.
 boolean isEnvelopedData()
          Returns whether or not this SMIMEMimeMessage is an enveloped-data message.
 boolean isSignedData()
          Returns whether or not this SMIMEMimeMessage is a signed-data message.
 boolean isSignedDataCertificateOnly()
          Returns whether or not this SMIMEMimeMessage is a certs-only message.
 boolean isSignedDataSignatureOnly()
          Returns whether or not this SMIMEMimeMessage is a multipart/signed message.
 void setCertificateOnly(Certificate[] certs)
          Set the content of this SMIMEMimeMessage object to a certificate-only SignedData object with the specified certificate array.
 void setCertificationRequest(CertificationRequest certRequest)
          Set the CertificationRequest object for this SMIMEMimeMessage object.
 void setRecipientCertificate(Certificate[] certs)
          Set the recipient certificates for the S/MIME message.
 void sign(Object message, Certificate signerCert, PrivateKey privateKey, String digestSignatureAlgorithm)
          Signs the message with the specified private key.
 String toString()
          Returns a string representation of this SMIMEMimeMessage object.
 boolean verify(Certificate signerCert)
          Verifies the ContentInfo that contains a SignedData object for this SMIMEMimeMessage object.
 boolean verify(Certificate signerCert, byte[] msg)
          Verifies the ContentInfo that contains a SignedData object for this SMIMEMimeMessage object.
 

Constructor Detail

SMIMEMimeMessage

protected SMIMEMimeMessage(com.ibm.security.smime.jmail.Folder folder,
                           InputStream is,
                           int msgnum)
                    throws com.ibm.security.smime.jmail.MessagingException
Constructs a MimeMessage by reading and parsing the data from the specified MIME InputStream. The InputStream will be left positioned at the end of the data for the message. Note that the input stream parse is done within this constructor itself.

SMIMEMimeMessage

protected SMIMEMimeMessage(com.ibm.security.smime.jmail.Folder folder,
                           InputStream is,
                           int msgnum,
                           String provider)
                    throws com.ibm.security.smime.jmail.MessagingException
Constructs a MimeMessage by reading and parsing the data from the specified MIME InputStream. The InputStream will be left positioned at the end of the data for the message. Note that the input stream parse is done within this constructor itself.

SMIMEMimeMessage

protected SMIMEMimeMessage(com.ibm.security.smime.jmail.Folder folder,
                           int msgnum)
                    throws com.ibm.security.smime.jmail.MessagingException
Constructs an empty MimeMessage object with the given Folder and message number.

SMIMEMimeMessage

protected SMIMEMimeMessage(com.ibm.security.smime.jmail.Folder folder,
                           int msgnum,
                           String provider)
                    throws com.ibm.security.smime.jmail.MessagingException
Constructs an empty MimeMessage object with the given Folder and message number.

SMIMEMimeMessage

protected SMIMEMimeMessage(com.ibm.security.smime.jmail.Folder folder,
                           com.ibm.security.smime.jmail.InternetHeaders headers,
                           byte[] content,
                           int msgnum)
                    throws com.ibm.security.smime.jmail.MessagingException
Constructs a MimeMessage from the given InternetHeaders object and content.

SMIMEMimeMessage

protected SMIMEMimeMessage(com.ibm.security.smime.jmail.Folder folder,
                           com.ibm.security.smime.jmail.InternetHeaders headers,
                           byte[] content,
                           int msgnum,
                           String provider)
                    throws com.ibm.security.smime.jmail.MessagingException
Constructs a MimeMessage from the given InternetHeaders object and content.

SMIMEMimeMessage

public SMIMEMimeMessage(com.ibm.security.smime.jmail.Session session)
Default constructor. An empty message object is created. The headers field is set to an empty InternetHeaders object. The flags field is set to an empty Flags object.

SMIMEMimeMessage

public SMIMEMimeMessage(com.ibm.security.smime.jmail.Session session,
                        String provider)
Default constructor. An empty message object is created. The headers field is set to an empty InternetHeaders object. The flags field is set to an empty Flags object.

SMIMEMimeMessage

public SMIMEMimeMessage(com.ibm.security.smime.jmail.Session session,
                        InputStream is)
                 throws com.ibm.security.smime.jmail.MessagingException
Constructs a MimeMessage by reading and parsing the data from the specified MIME InputStream. The InputStream will be left positioned at the end of the data for the message. Note that the input stream parse is done within this constructor itself.

SMIMEMimeMessage

public SMIMEMimeMessage(com.ibm.security.smime.jmail.Session session,
                        InputStream is,
                        String provider)
                 throws com.ibm.security.smime.jmail.MessagingException
Constructs a MimeMessage by reading and parsing the data from the specified MIME InputStream. The InputStream will be left positioned at the end of the data for the message. Note that the input stream parse is done within this constructor itself.
Method Detail

isSignedDataSignatureOnly

public boolean isSignedDataSignatureOnly()
Returns whether or not this SMIMEMimeMessage is a multipart/signed message. A multipart/signed message has the message detached from the signature-only SignedData object within the ContentInfo object.
Returns:
true if this SMIMEMimeMessage object has a ContentType basetype of "multipart/signed" and a protocol of "application/x-pkcs7-signature"; returns false if the above conditions were not met or if the ContentType could not be retrieved or parsed.

isSignedDataCertificateOnly

public boolean isSignedDataCertificateOnly()
Returns whether or not this SMIMEMimeMessage is a certs-only message. A certs-only message has a ContentInfo object with a SignedData object that has one or more certificates and does not have contents or signers.
Returns:
true if this SMIMEMimeMessage object has a ContentType basetype of "application/x-pkcs7-mime" and a smimetype of "certs-only"; returns false if the above conditions were not met or if the ContentType could not be retrieved or parsed.

isSignedData

public boolean isSignedData()
Returns whether or not this SMIMEMimeMessage is a signed-data message. A signed-data message has a ContentInfo object with a SignedData object that has one or more certificates, contents, and one or more signers.
Returns:
true if this SMIMEMimeMessage object has a ContentType basetype of "application/x-pkcs7-mime" and a smimetype of "signed-data"; returns false if the above conditions were not met or if the ContentType could not be retrieved or parsed.

isEnvelopedData

public boolean isEnvelopedData()
Returns whether or not this SMIMEMimeMessage is an enveloped-data message. An enveloped-data message has a ContentInfo object with a EnvelopedData object that has one or more recipients with an encrypted secret key and encrypted contents.
Returns:
true if this SMIMEMimeMessage object has a ContentType basetype of "application/x-pkcs7-mime" and a smimetype of null; returns false if the above conditions were not met or if the ContentType could not be retrieved or parsed.

isCertificationRequest

public boolean isCertificationRequest()
Returns whether or not this SMIMEMimeMessage is a pkcs10 message. A pkcs10 message has a CertificationRequest object.
Returns:
true if this SMIMEMimeMessage object has a ContentType basetype of "application/x-pkcs10"; returns false if the above condition was not met or if the ContentType could not be retrieved or parsed.

setCertificationRequest

public void setCertificationRequest(CertificationRequest certRequest)
                             throws com.ibm.security.smime.jmail.MessagingException,
                                    PKCSException
Set the CertificationRequest object for this SMIMEMimeMessage object.

This SMIMEMimeMessage object must not already contain a ContentInfo or CertificationRequest object, otherwise this method will throw a PKCSException.

Parameters:
certRequest - CertificationRequest object

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 PKCSException,
                               IOException,
                               NoSuchAlgorithmException,
                               com.ibm.security.smime.jmail.MessagingException
Set the content of this SMIMEMimeMessage object to a certificate-only SignedData object with the specified certificate array. This method aids in the creation of certs-only p7c SMIME messages.

This SMIMEMimeMessage object must not already contain a ContentInfo or CertificationRequest object, otherwise this method will throw a PKCSException.

Parameters:
certs - Certificate array
Throws:
PKCSException - on SignedData creation errors
IOException - on SignedData creation errors
NoSuchAlgorithmException - on invalid algorithm errors
com.ibm.security.smime.jmail.MessagingException - on message creation errors

sign

public void sign(Object message,
                 Certificate signerCert,
                 PrivateKey privateKey,
                 String digestSignatureAlgorithm)
          throws PKCSException,
                 IOException,
                 NoSuchAlgorithmException,
                 com.ibm.security.smime.jmail.MessagingException
Signs the message with the specified private key. This method will set the content of this SMIMEMimeMessage to the created SignedData object with the message, signature, and certificate.

This SMIMEMimeMessage object must not already contain a ContentInfo or CertificationRequest object, otherwise this method will throw a PKCSException.

Parameters:
message - String or Multipart contents to sign
signerCert - certificate of the signer
privateKey - private key of the certificate
digestSignatureAlgorithm - signature algorithm
Throws:
PKCSException - on signing errors
IOException - on signing errors
NoSuchAlgorithmException - on invalid algorithm errors
com.ibm.security.smime.jmail.MessagingException - on message creation errors

encrypt

public void encrypt(Object message,
                    int encryptionStrength)
             throws PKCSException,
                    IOException,
                    NoSuchAlgorithmException,
                    com.ibm.security.smime.jmail.MessagingException
Encrypts the message with a generated secret key and encrypts the secret key with the recipient certificate(s) that were already specified for this SMIMEMimeMessage object. This method will set the content of this SMIMEMimeMessage to the created EnvelopedData object.

This SMIMEMimeMessage object must not already contain a ContentInfo or CertificationRequest object, otherwise this method will throw a PKCSException. This method requires that the recipient certificate(s) must have been previously set on this SMIMEMimeMessage object.

Parameters:
message - String or Multipart contents to encrypt
encryptionStrength - specified by SMIME.WEAK_ENCRYPTION, SMIME.MEDIUM_ENCRYPTION, or SMIME.STRONG_ENCRYPTION
Throws:
IOException - on encryption errors
PKCSException - key encryption errors
NoSuchAlgorithmException - on invalid algorithm errors
com.ibm.security.smime.jmail.MessagingException - on message creation errors

encrypt

public void encrypt(Object message,
                    String encryptionAlgorithm,
                    int keySize)
             throws PKCSException,
                    IOException,
                    NoSuchAlgorithmException,
                    com.ibm.security.smime.jmail.MessagingException
Encrypts the message with a generated secret key and encrypts the secret key with the recipient certificate(s) that were already specified for this SMIMEMimeMessage object. This method will set the content of this SMIMEMimeMessage to the created EnvelopedData object.

This SMIMEMimeMessage object must not already contain a ContentInfo or CertificationRequest object, otherwise this method will throw a PKCSException. This method requires that the recipient certificate(s) must have been previously set on this SMIMEMimeMessage object.

Parameters:
message - String or Multipart contents to encrypt
encryptionAlgorithm - encryption algorithm String
keySize - length of the encryption key
Throws:
IOException - on encryption errors
PKCSException - key encryption errors
NoSuchAlgorithmException - on invalid algorithm errors
com.ibm.security.smime.jmail.MessagingException - on message creation errors

verify

public boolean verify(Certificate signerCert)
               throws PKCSException,
                      IOException,
                      NoSuchAlgorithmException
Verifies the ContentInfo that contains a SignedData object for this SMIMEMimeMessage object. The SMIMEMimeMessage must be of type signed-data or multipart/signed.

This method will attempt to use the multipart message stored with this SMIMEMimeMessage object for signed, multipart messages. Otherwise, this method will attempt to use any stored contents within the message or SignedData object.

Parameters:
signerCert - certificate of the signer
Returns:
true, if the content is verfied, false otherwise.
Throws:
PKCSException - on verification error.
IOException - on verification error.
NoSuchAlgorithmException - on invalid algorithm errors.

verify

public boolean verify(Certificate signerCert,
                      byte[] msg)
               throws PKCSException,
                      IOException,
                      NoSuchAlgorithmException
Verifies the ContentInfo that contains a SignedData object for this SMIMEMimeMessage object. The SMIMEMimeMessage must be of type signed-data or multipart/signed.
Parameters:
signerCert - certificate of the signer
msg - byte array to compute the message digest comparision. If not specified, this method will attempt to use the multipart message stored with this SMIMEMimeMessage object for signed, multipart messages. If not specified, this method will attempt to use any stored contents within the message or SignedData object.
Returns:
true, if the content is verfied, false otherwise.
Throws:
PKCSException - on verification error.
IOException - on verification error.
NoSuchAlgorithmException - on invalid algorithm errors.

decrypt

public ContentInfo decrypt(PrivateKey recipientPrivateKey,
                           Certificate recipientCert)
                    throws IOException,
                           PKCSException,
                           com.ibm.security.smime.jmail.MessagingException
Decrypts the ContentInfo that contains an EnvelopedData object for this SMIMEMimeMessage object. If the SMIMEMimeMessage contained a signed and encrypted message, the returned contentInfo
Parameters:
recipientPrivateKey - private key of the recipient
recipientCert - certificate of the recipient
Returns:
ContentInfo decrypted from the EnvelopedData object.
Throws:
IOException - on decryption error.
PKCSException - key decryption error.
IllegalArgumentException - if the ContentType is not EnvelopedData.

getContentInfo

public ContentInfo getContentInfo()
Returns a copy of the ContentInfo object contained within this SMIMEMimeMessage, if any.
Returns:
ContentInfo object or null.

getCertificationRequest

public CertificationRequest getCertificationRequest()
Returns the CertificationRequest object contained within this SMIMEMimeMessage, if any.
Returns:
CertificationRequest object or null.

toString

public String toString()
Returns a string representation of this SMIMEMimeMessage object. The string will contain the type of PKCS #7 or #10 message and whether or not the SMIMEMimeMessage object contains a ContentInfo or CertificationRequest object.
Returns:
a string representation of this object.