Triple DES (DESede or 3DES) keys and operations

Keys

The hardware JCE implementation (IBMJCECCA) extends the triple DES key that is available in the software JCE implementation. In the software JCE implementation, the triple DES key material is stored in the key object. The IBMJCECCA implementation extends this by adding the following alternative representations:

A triple DES key that was previously stored in the CCA key storage area. The key object contains the CCA key storage area label for the key.
The following example illustrates creating a triple DES key object for a key that is already stored in the CCA key storage area with the label "MY.ENCRYPT.ED.TDESKEY", then (for purposes of illustration) deleting the CCA key storage area entry.
```
// create a key object for an existing entry
// (No checking is done to verify that the entry exists, or
// that the key it contains is actually a DESede key.)
//
SecretKeyFactory desKeyFactory =
        SecretKeyFactory.getInstance("DESede", "IBMJCECCA");
KeyLabelKeySpec spec =
        new KeyLabelKeySpec("MY.ENCRYPT.ED.TDESKEY");
SecretKey key = desKeyFactory.generateSecret(spec);

// delete the entry from the CCA key storage area.
// (An exception is thrown if the CCA key storage area entry does not exist.)
//
key.deleteCKDSEntry();

//
// Note that, in this example, the Java key object still
// exists, but the key entry it represents has been deleted.
// Any attempt to use the object "key" will cause an exception
// containing a hardware return code and reason code.
//
```
On z800 and z900 machines, a key object that contains the label for an encrypted DES key can be used for CBC mode encryption and decryption with the IBMJCECCA provider.
On z890, z990, and newer zSeries processors, a key object containing the label for a clear DES key can be used for CBC mode, CFB mode, or ECB mode encryption and decryption with the IBMJCECCA provider. This environment also supports using a key object that contains the label for an encrypted DES key for CBC mode encryption and decryption with the IBMJCECCA provider.

A key object that contains the label for an encrypted triple DES key can be passed to an IBMJCECCA RSA Cipher object to be wrapped for export to another host.

A triple DES key that was wrapped by an RSA Cipher can be passed to the IBMJCECCA RSA Cipher to be unwrapped for import from another host. By default, the resulting (unwrapped) key object contains a clear triple DES key. If a CCAAlgorithmParameterSpec is created with no type specified, or with type CCAAlgorithmParameterSpec.SECURE_INTERNAL_TOKEN, and the RSA Cipher is initialized with this CCAAlgorithmParameterSpec, the resulting (unwrapped) key object contains a triple DES hardware token. If a CCAAlgorithmParameterSpec is created with type CAAlgorithmParameterSpec.CKDS, and the RSA Cipher is initialized with this CCAAlgorithmParameterSpec, the resulting (unwrapped) key object contains the label for a entry in the system CCA key storage area that contains a triple DES hardware token.

For more information about wrapping and unwrapping triple DES keys, see RSA keys.
A triple DES key that is generated by an IBMJCECCA call to the underlying hardware. The key object contains a hardware token. This token contains the key encrypted with the host primary key. The key material for this type of key is never resident in system memory in clear form.
The following example illustrates generating a triple DES key object that contains a hardware key token
```
// create a new key token and a key object to represent it
//
CCAAlgorithmParameterSpec ccaAlgParmSpec =
        new CCAAlgorithmParameterSpec();
KeyGenerator keyGen =
        KeyGenerator.getInstance( "DESede", "IBMJCECCA" );
keyGen.init( ccaAlgParmSpec, null );
Key tdesKey = keyGen.generateKey();
```
A key object that contains a triple DES hardware token can be used for CBC mode encryption and decryption with the IBMJCECCA provider.
A key object that contains a triple DES hardware token can be passed to an IBMJCECCA RSA Cipher object to be wrapped for export to another host.

A triple DES key that was wrapped by an RSA Cipher can be passed to the IBMJCECCA RSA Cipher to be unwrapped for import from another host. By default, the resulting (unwrapped) key object contains a clear triple DES key. If the RSA Cipher object is initialized with a CCAAlgorithmParameterSpec, the resulting (unwrapped) key object contains a triple DES hardware token.

For more information about wrapping and unwrapping triple DES keys, see RSA keys.
A triple DES key that is generated by an IBMJCECCA call to the underlying hardware then stored in the CCA key storage area. The key object contains the label for the new CCA key entry. The CCA key storage area entry holds a token that contains the key encrypted with the host primary key. The key material for this type of key is never resident in system memory in clear form.
The following example illustrates generating a protected triple DES key token, storing it in a new CCA key storage area entry with an automatically generated label, and creating a key object that contains the label for the CCA key storage area entry.
```
// create a new CCA key storage area entry and a key object to represent it
//
CCAAlgorithmParameterSpec ccaAlgParmSpec =
        new CCAAlgorithmParameterSpec(CCAAlgorithmParameterSpec.CKDS);
KeyGenerator keyGen = KeyGenerator.getInstance("DESede","IBMJCECCA");
keyGen.init(ccaAlgParmSpec,null);
Key thisKey = keyGen.generateKey();
```
The following example illustrates generating a protected triple DES key token, storing it in a new CCA key storage area entry with the label "ATRIPLE.DESTOKEN.INCKDS", and creating a key object that contains the label for the CCA key storage area entry.
```
// create a new CCA key storage area entry and a key object to represent it
//
CCAAlgorithmParameterSpec ccaAlgParmSpec =
        new CCAAlgorithmParameterSpec(CCAAlgorithmParameterSpec.CKDS,
                                      "ATRIPLE.DESTOKEN.INCKDS");
KeyGenerator keyGen = KeyGenerator.getInstance("DESede", "IBMJCECCA");
keyGen.init(ccaAlgParmSpec, null);
Key thisKey = keyGen.generateKey();
```
A key object that represents a triple DES hardware token can be used for CBC mode encryption and decryption with the IBMJCECCA provider.
A key object that represents a triple DES hardware token can be passed to an IBMJCECCA RSA Cipher object to be wrapped for export to another host.

A triple DES key that was wrapped by an RSA Cipher can be passed to the IBMJCECCA RSA Cipher to be unwrapped for import from another host. By default, the resulting (unwrapped) key object contains a clear triple DES key. If a CCAAlgorithmParameterSpec is created with no type specified, or with type CCAAlgorithmParameterSpec.SECURE_INTERNAL_TOKEN, and the RSA Cipher is initialized with this CCAAlgorithmParameterSpec, the resulting (unwrapped) key object contains a triple DES hardware token. If a CCAAlgorithmParameterSpec is created with type CAAlgorithmParameterSpec.CKDS, and the RSA Cipher is initialized with this CCAAlgorithmParameterSpec, the resulting (unwrapped) key object contains the label for a CCA key storage area entry that contains a triple DES hardware token.

For more information about wrapping and unwrapping triple DES keys, see RSA keys.

Operations

Although all triple DES ciphers are available in the IBMJCECCA provider, they are not all available in the hardware devices. The hardware cryptographic devices support the Cipher Block Chaining (CBC), Cipher feedback (CFB), Output feedback (OFB), and Electronic Code Book (ECB) version of triple DES. That is, all of the triple DES ciphers are supported by the IBMJCECCA provider, but only CBC, CFB, OFB, and ECB can use hardware cryptography.

Triple DES is slightly more compute intensive than DES, but like DES is less compute intensive than asymmetric algorithms such as RSA. Therefore, for smaller data sizes, software triple DES cryptography can be faster than hardware triple DES cryptography. For this reason, triple DES with CBC, CFB, OFB, or ECB is also implemented in software within the IBMJCECCA provider. The same clip level (specified in a system property called ibm.DES.usehdwr.size) is used to determine the data size at which hardware cryptography is used for triple DES. For more information about the ibm.DES.usehdwr.size system property, see Operations.