Re-enciphering secure keys from a file

Edit online

If a new master key must be used to re-encipher a secure key stored in a binary file, you can use the zkey reencipher command to perform this task.

Before you begin

This task requires that a new CCA or EP11 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 a file.

Procedure

Load the CCA key parts for a new AES master key or EP11 master key using the TKE.
Do not yet set the new master key active at this time.
Re-encipher the secure key.
For example, you can use a command similar to the following:
```
zkey reencipher <oldSK_binary_file> [--output <newSK_binary_file>]
```
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.
For CCA secure keys only, you can also re-encipher a secure key which 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. A cryptographic coprocessor configured in EP11 mode does not have an OLD register. So the --from-old option is not available.
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.
For more information, also refer to the zkey man page.
Examples:
```
zkey reencipher securekey.bin --from-old [--output securekey2.bin] 

zkey reencipher securekey.bin --to-new [--output securekey2.bin] 

zkey re-encipher securekey.bin [--output securekey2.bin]
```
Now set the new CCA or EP11 master key active. Use the functions provided by the TKE for this purpose.
If you stored the re-enciphered secure key in a separate file ([--output <newSK_binary_file>]), from now on you should use the new secure key file. You can still use the original secure key file until you change the master key again, because the previous master key is still available in the OLD register (not valid for EP11 coprocessors).