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

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