AES keys and operations

Keys

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

An AES key that was previously stored in the CCA key storage area. The key object contains the CCA label for the key.
The following example illustrates creating an AES key object for a key already that is stored in the CCA key storage area with the label "MY.ENCRYPT.ED.AESKEY", then (for purposes of illustration) deleting the CCA key storage area entry.
```
// create a key object for an existing CCA key storage area entry
// (No checking is done to verify that the entry exists, or
// that the key it contains is actually an AES key.)
//
SecretKeyFactory aesKeyFactory =
        SecretKeyFactory.getInstance("AES", "IBMJCECCA");
KeyLabelKeySpec spec =
        new KeyLabelKeySpec("MY.ENCRYPT.ED.AESKEY");
SecretKey key = aesKeyFactory.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 CCA key storage area 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.
//
```
A key object that contains the CCA key storage area label for a clear AES key can be used for CBC mode, CFB mode, OFB mode, ECB mode, or GCM mode encryption and decryption with the IBMJCECCA provider.
A key object that contains the CCA key storage area label for an encrypted AES key can be used for CBC mode, CFB mode, OFB mode, ECB mode, or GCM mode encryption and decryption with the IBMJCECCA provider.

A key object that contains the CCA key storage area label for an encrypted AES key can be passed to an IBMJCECCA RSA Cipher object to be wrapped for export to another host.

An AES 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 AES 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 an AES 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 an AES hardware token.

For more information about wrapping and unwrapping AES keys, see RSA keys.
An AES 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 an AES key object that contains a hardware key token
```
CCAAlgorithmParameterSpec ccaAlgParmSpec =
        new CCAAlgorithmParameterSpec();
KeyGenerator keyGen =
        KeyGenerator.getInstance( "AES", "IBMJCECCA" );
keyGen.init( ccaAlgParmSpec, null );
Key aesKey = keyGen.generateKey();
```
A key object that contains an AES hardware token can be used for CBC mode or ECB mode encryption and decryption with the IBMJCECCA provider.
A key object that contains an AES hardware token can be passed to an IBMJCECCA RSA Cipher object to be wrapped for export to another host.

An AES 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 AES 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 an AES 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 an AES hardware token.

For more information about wrapping and unwrapping AES keys, see RSA keys.
An AES 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 storage area 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 AES 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("AES", "IBMJCECCA");
keyGen.init( ccaAlgParmSpec, null );
Key thisKey = keyGen.generateKey();
```
The following examples illustrates generating a protected AES key token, storing it in a new CCA key storage area entry with the label "AN.AESTOKEN.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,
                                      "AN.AESTOKEN.INCKDS");
KeyGenerator keyGen = KeyGenerator.getInstance("AES", "IBMJCECCA");
keyGen.init(ccaAlgParmSpec, null);
Key thisKey = keyGen.generateKey();
```
A key object that contains the CCA key storage area label for an encrypted AES key can be used for CBC mode, CFB mode, OFB mode, ECB mode, or GCM mode encryption and decryption with the IBMJCECCA provider.
A key object that contains the CCA key storage area label for an encrypted AES key can be passed to an IBMJCECCA RSA Cipher object to be wrapped for export to another host.

An AES 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 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 an AES 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 an AES hardware token.

For more information about wrapping and unwrapping AES keys, see RSA keys

Operations

The hardware JCE implementation (IBMJCECCA) of AES does not change any of the APIs that are available in the software JCE implementation. Therefore, an application that used the AES capabilities of the software JCE implementation does not require modification to use the IBMJCECCA provider, except for specific references to the provider. For example, if a call to the getInstance() API specified the software JCE provider, you must change the call to specify the IBMJCECCA provider instead.

The IBMJCECCA provider hardware cryptographic devices support only the Cipher Feedback (CFB), the Cipher Block Chaining (CBC), Output Feedback (OFB), Galois/Counter Mode (GCM), and the Electronic Code Book (ECB) versions of AES. Software failover support, as provided for DES and DESede, is available for AES ECB ciphers and AES CBC ciphers only.