com.dstc.security.smime
Class SMIMECipher

java.lang.Object
  |
  +--com.dstc.security.smime.SMIMECipher

public class SMIMECipher
extends Object

A class for encryption and decryption of MIME messages according to RFC 2633 "S/MIME Version 3 Message Specification".

This class can be used in both encryption and decryption modes, depending on whether initEncrypt() or initDecrypt() is called.

An encrypted S/MIME message consists fundamentally of the original message encrypted with a content encryption key, and means for conveying the content encryption key securely to one or more recipients.

The current version supports both the symmetric cipher algorithms Triple DES and RC2 (either 128-bit or 40-bit) for content encryption specified in RFC 2633.

Encrypted content encryption keys through the RSA public key algorithm is the only method supported in this release for conveying content encryption keys. This method requires each recipient to have an RSA private key and an X.509 certificate for the accompanying RSA public key.

Example usage:

    /////// encryption ///////

    // a JavaMail MimeMessage, appropriately constructed 
    // including MIME headers (see JavaMail API for details)
    MimeMessage msg = ....

    // an X.509Certificate for a recipient "Joe"
    X509Certicate joeCert = ....

    // an appropriately seeded SecureRandom instance
    // NB: the default SecureRandom seeding is expensive
    SecureRandom rand = ....

    // Initialize an SMIMECipher for encryption for Joe to decrypt, 
    // with Triple DES as the content key encryption algorithm
    SMIMECipher cipher = new SMIMECipher();
    cipher.initEncrypt(rand, "DESede", new X509Certificate[]{joeCert};
    
    // Sets the MimeMessage to encrypt
    cipher.setMessage(msg);

    // Encrypts it
    MimeMessage encrypted = cipher.encrypt();

    // Sends it off to Joe,
    // eg. using javax.mail.Transport.send(msg);
    // (See JavaMail API for details)

    /////// decryption ///////

    // When Joe receives the S/MIME message, he instantiates a MimeMessage
    // from it (See JavaMail API for details)
    MimeMessage forJoe = ....
   
    // Joe initializes an SMIMECipher for decryption with his PrivateKey
    // and accompanying X.509Certificate
    SMIMECipher cipher = new SMIMECipher();
    cipher.initDecrypt(joePrivateKey, joeCert);

    // Sets the message to decrypt
    cipher.setMessage(forJoe)

    // ... decrypts it
    DecryptionResult res = cipher.decrypt();

    // ... and obtains the decrypted message
    MimeMessage msg = res.getMessage();

 

See Also:
DecryptionResult, EnvelopedData

Constructor Summary
SMIMECipher()
          Default constructor
 
Method Summary
 DecryptionResult decrypt()
          Decrypts the previously set MimeMessage, and if successful returns a DecryptionResult through which the decrypted MimeMessage can be retrieved.
 MimeMessage encrypt()
          Encrypts the previously set MimeMessage, and if successful returns a MimeMessage encapsulating a representation of the encrypted message.
 void initDecrypt(PrivateKey priv, X509Certificate cert)
          Initializes for decryption of one or more encrypted MimeMessages with a PrivateKey and corresponding X.509 certificate
 void initEncrypt(SecureRandom rand, String algName, X509Certificate[] certs)
          Initializes for encryption of one or more MimeMessages with a SecureRandom instance, a content encryption algorithm, and an array of X509Certificates for intended recipients.
 void setMessage(MimeMessage origMsg)
          Sets the MimeMessage to encrypt or decrypt.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

SMIMECipher

public SMIMECipher()
Default constructor
Method Detail

initEncrypt

public void initEncrypt(SecureRandom rand,
                        String algName,
                        X509Certificate[] certs)
                 throws SMIMEException
Initializes for encryption of one or more MimeMessages with a SecureRandom instance, a content encryption algorithm, and an array of X509Certificates for intended recipients.

The SecureRandom instance is used to generate content encryption keys and should be seeded properly. The content encryption algorithms supported are "DESede", "RC2" and "RC2/40" (40-bit RC2).

Encrypted content keys are constructed for each of the certificates in a subsequent encrypt() call. It is up to the caller to ensure that this list of certificates includes at least one for each recipient of the MimeMessage to be encrypted (and set in a subsequent setMessage() call). Otherwise, some recipients of the encrypted message will not be able to decrypt the message.

Each certificate must have its key usage set for key encipherment, if a key usage extension exists.

Parameters:
rand - random number generator
algName - content encryption algorithm name, and must be one of "DESede", "RC2" and "RC2/40"
certs - X509Certificates for intended recipients of encrypted MimeMessages

initDecrypt

public void initDecrypt(PrivateKey priv,
                        X509Certificate cert)
                 throws SMIMEException
Initializes for decryption of one or more encrypted MimeMessages with a PrivateKey and corresponding X.509 certificate
Parameters:
priv - PrivateKey to decrypt encrypted MimeMessages
cert - X509Certificate corresponding to the PrivateKey

setMessage

public void setMessage(MimeMessage origMsg)
                throws MessagingException,
                       IOException,
                       SMIMEException
Sets the MimeMessage to encrypt or decrypt. A copy of the passed-in message is made with the MimeMessage copy constructor in JavaMail 1.2 and subsequently modified during the encryption or decryption process. The passed-in MimeMessage is unmodified.

If encrypting, encrypted content encryption keys are constructed for recipients as denoted by the array of certificates set in initEncrypt(). It is up to the caller to ensure that all recipients as denoted by address headers in the MimeMessage each correspond to at least one certificate passed in initEncrypt(). Otherwise some recipients will not be able to decrypt the subsequently encrypted message.

Parameters:
origMsg - a MimeMessage to encrypt or decrypt

decrypt

public DecryptionResult decrypt()
                         throws IOException,
                                MessagingException,
                                SMIMEException
Decrypts the previously set MimeMessage, and if successful returns a DecryptionResult through which the decrypted MimeMessage can be retrieved.

NB: If the previously set MimeMessage is not a signed message, an S/MIME Exception will be thrown.

After this call, the state is reset to what it was in right after the previous call to initDecrypt().

Returns:
DecryptionResult representing the result of decryption

encrypt

public MimeMessage encrypt()
                    throws SMIMEException,
                           MessagingException,
                           IOException
Encrypts the previously set MimeMessage, and if successful returns a MimeMessage encapsulating a representation of the encrypted message.

After this call, the state is reset to what it was in right after the previous call to initEncrypt().

Returns:
the encrypted MimeMessage