Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD