com.dstc.security.cms
Class CMSCipher

java.lang.Object
  |
  +--com.dstc.security.cms.CMSCipher

public class CMSCipher
extends Object

A class for encrypting (enveloping) data according to RFC 2630 "Cryptographic Message Syntax" and for decrypting data generated according to that specification.

Encrypting to multiple recipients is supported. Each recipient must have a suitable X.509 certificate for either an RSA public key or a Diffie-Hellman public key.

Content encryption algorithms supported are TripleDES and RC2 (either 128-bit or 40-bit).

The content encryption key can be conveyed to be recipient in two possible means. If a recipient has an RSA certificate, the KeyTransport option is used, whereas for a Diffie-Hellman certificate, the KeyAgreement option is used. In both cases, a content encryption key is carried in encrypted form along with the encrypted data. In KeyTransport mode, a recipient's RSA public key is used to encrypt the content encryption key. In KeyAgreement mode, the Ephemeral-Static Diffie-Hellman algorithm is used with a sender-generated key pair and a recipient Diffie-Hellman certificate to generate a key encrypting key which is then used to "wrap" or encrypt the content encryption key.

Example usage:

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

    // Some data to be encrypted, available as an InputStream
    InputStream data = ....

    // Wrap with a CMSTypedDataInputStream
    CMSTypedDataInputStream cis = new CMSTypedDataInputStream(data);
                            
    // an X.509Certificate for a recipient "Joe"
    X509Certicate joeCert = ....

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

    // Initialize a CMSCipher for encryption for Joe to decrypt,
    // with Triple DES as the content key encryption algorithm
    CMSCipher cipher = new CMSCipher();
    cipher.initEncrypt(rand, new X509Certificate[]{joeCert}, "DESede");

    // Sets the data to encrypt
    cipher.setDataToBeEncrypted(cis);

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

    // Read from stream to obtain encrypted data
    .......

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

    // Joe obtains the encrypted data and instantiates an InputStream
    // from it
    InputStream forJoe = .......

    // Joe initializes a CMSCipher for decryption with his PrivateKey
    // and accompanying X.509Certificate
    CMSCipher cipher = new CMSCipher();
    cipher.initDecrypt(joePrivateKey, joeCert);

    // Sets the data to decrypt
    cipher.setDataToBeDecrypted(forJoe)

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

    // ... obtains the decrypted data as an InputStream
    CMSTypedDataInputStream decrypted = res.getDecrypted();

    // ... and reads decrypted data from the stream
    ..........
 

See Also:
CMSTypedDataInputStream, DecryptionResult, EnvelopedData, SMIMECipher

Constructor Summary
CMSCipher()
          Default constructor
 
Method Summary
 DecryptionResult decrypt()
          Decrypts the previously supplied CMS enveloped data and returns a DecryptionResult instance from which the recovered plaintext data can be read.
 CMSTypedDataInputStream encrypt()
          Encrypts the previously supplied data and returns a CMSTypedDataInputStream from which the CMS enveloped data can be read.
 void initDecrypt(PrivateKey priv, X509Certificate cert)
          Initializes for decryption of one or more instances of CMS enveloped data with a recipient's private key and associated certificate.
 void initEncrypt(SecureRandom rand, X509Certificate[] rcptCerts, String cipherAlg)
          Initializes for encryption of one or more instances of data with a random number generator together with the content encryption algorithm and a list of recipient certificates.
 void setDataToBeDecrypted(InputStream is)
          Supplies the CMS enveloped data to be decrypted in the form of an InputStream.
 void setDataToBeEncrypted(CMSTypedDataInputStream is)
          Supplies the data to be encrypted (turned into CMS enveloped data) in the form of a CMSTypedDataInputStream.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

CMSCipher

public CMSCipher()
Default constructor
Method Detail

initEncrypt

public void initEncrypt(SecureRandom rand,
                        X509Certificate[] rcptCerts,
                        String cipherAlg)
                 throws CMSException
Initializes for encryption of one or more instances of data with a random number generator together with the content encryption algorithm and a list of recipient certificates. The SecureRandom instance is used to generate session keys and should be carefully seeded. The cipher algorithm can be one of three supported algorithms: DESede, RC2 or RC2/40. Each recipient certificate must be for either an RSA or a Diffie-Hellman public key.

initDecrypt

public void initDecrypt(PrivateKey priv,
                        X509Certificate cert)
                 throws CMSException
Initializes for decryption of one or more instances of CMS enveloped data with a recipient's private key and associated certificate.

setDataToBeEncrypted

public void setDataToBeEncrypted(CMSTypedDataInputStream is)
                          throws CMSException
Supplies the data to be encrypted (turned into CMS enveloped data) in the form of a CMSTypedDataInputStream. The data to be encrypted could itself be signed or enveloped data (for instance, obtained from calling sign() on a CMSSignature), thereby allowing arbitrary nesting of CMS data.

setDataToBeDecrypted

public void setDataToBeDecrypted(InputStream is)
                          throws CMSException
Supplies the CMS enveloped data to be decrypted in the form of an InputStream.

No checks are performed on the supplied InputStream at this point.


encrypt

public CMSTypedDataInputStream encrypt()
                                throws CMSException,
                                       IOException
Encrypts the previously supplied data and returns a CMSTypedDataInputStream from which the CMS enveloped data can be read.

A call to this method resets the state to when initEncrypt() was last called.


decrypt

public DecryptionResult decrypt()
                         throws CMSException,
                                IOException
Decrypts the previously supplied CMS enveloped data and returns a DecryptionResult instance from which the recovered plaintext data can be read.

A call to this method resets the state to when initDecrypt() was last called.