Re-enciphering secure keys from a repository

Read how to use the zkey reencipher command to re-encipher a secure key that is stored in a secure key repository.

Before you begin

This task requires that a new CCA or EP11 AES master key has been set on the attached cryptographic coprocessors with the TKE. Using the zkey utility for re-enciphering a CCA AES secure key requires the IBM® CCA host library (libcsulcca.so). For re-enciphering an EP11 AES secure key, zkey requires the Linux® on Z Enterprise PKCS #11 (EP11) Support Program (EP11 host library) to be installed.

To obtain information about your current secure key, perform the procedure described in Validating a secure key from the secure key repository.

Procedure

Load the key parts for a new CCA or EP11 AES master key using the TKE.
If you use multiple APQNs with the same master key, load the same new master key on these APQNs. Do not yet set the new master key active at this time.
Re-encipher all secure keys contained in the secure key repository that are associated with the APQN for which you change the master key.
For example, you can use a command similar to the following:
```
zkey reencipher --apqns <apqn1,apqn2,...>
```
Note:
You can re-encipher a secure key that is currently enciphered under the master key in the CURRENT register of the CCA or EP11 coprocessor to the master key in the NEW register, as long as the new master key has not been activated (set). For this purpose, use option --to-new with the zkey utility.

You can also re-encipher a secure AES DATA or AES CIPHER key that is currently enciphered under the master key in the OLD register of the cryptographic adapter to the master key in the CURRENT register. For this purpose, use option --from-old with the zkey utility. This option is not available for EP11 AES keys, as cryptographic coprocessors in EP11 mode do not have an OLD register.

If both options --from-old and --to-new are specified, a secure key that is currently enciphered with the master key in the OLD register is re-enciphered with the master key in the NEW register.

Finally, you can use the auto-detection function of zkey. The utility detects whether the secure key is enciphered with a master key from the OLD or from the CURRENT register and re-enciphers the secure key with the appropriate new master key as described.

Re-enciphering a secure key contained in the secure key repository can be performed in-place, or in staged mode. Staged mode means that the re-enciphered secure key is stored in a separate file in the secure key repository. Thus the current secure key is still valid at this point. Once the new CCA or EP11 master key has been set (made active), you need to rerun the reencipher command with option --complete to complete the staged re-enciphering. Re-enciphering from CURRENT to NEW is performed in staged mode by default. You can use option --staged to force a staged re-enciphering for the OLD to CURRENT case.

Examples:
```
zkey reencipher --apqns <apqn1,apqn2,...> --from-old --staged

zkey reencipher --apqns <apqn1,apqn2,...> --to-new --staged

zkey re-encipher --apqns <apqn1,apqn2,...> --staged
```
Now set the new master key active. Use the functions provided by the TKE for this purpose.
Complete the re-enciphering:
```
zkey reencipher --apqns <apqn1,apqn2,...> --complete
```
Note: To re-encipher a single secure key stored in the key repository, run:
```
# zkey reencipher --name secure_key1
```
This re-enciphers the secure key with the name secure_key1.
For more information, see Managing a secure key repository.