Re-enciphering AES secure keys

Use the zkey reencipher command to re-encipher an existing secure key with a new master key. An AES secure key must be re-enciphered when the AES master key of the CCA or EP11 cryptographic coprocessor changes.

The CCA cryptographic coprocessor has three different registers to store master keys:

  • The CURRENT register contains the current master key.
  • The OLD register contains the previously used master key. Secure keys enciphered with the master key contained in the OLD register can still be used until the master key is changed again.
  • The NEW register contains the new master key to be set. The master key in the NEW register cannot be used until it is made the current master key. You can pro-actively re-encipher a secure key with the NEW master key before this key is made the CURRENT key. Use the --to-new option to do this.
Note: An EP11 cryptographic coprocessor has only two registers to store master keys, CURRENT and NEW. Therefore, old master keys are no longer available as soon as a new master key is set CURRENT.

Use the --from-old option to re-encipher a secure key that is currently enciphered with the master key in the OLD register with the master key in the CURRENT register. If both the --from-old and --to-new options 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. If both options are omitted, zkey automatically detects whether the secure key is currently enciphered with the master key in the OLD register or with the master key in the CURRENT register. If currently enciphered with the master key in the OLD register, it is re-enciphered with the master key in the CURRENT register. If it is currently enciphered with the master key in the CURRENT register, it is re-enciphered with the master key in the NEW register. If for this case the NEW register does not contain a valid master key, then the re-encipher operation fails.

To re-encipher secure keys contained in the secure key repository, specify the name of the key or a pattern containing wildcards using the --name option. When wildcards are used you must quote the value. You can also specify the --apqns option to re-encipher those secure keys that are associated with the specified cryptographic coprocessors (APQNs). You can use wildcards for the APQN specification. When wildcards are used you must quote the value. If both options --name and --apqns are specified then all secure keys contained in the key repository that match both patterns are re-enciphered. If both options are omitted, then all secure keys contained in the key repository are re-enciphered.

Re-enciphering a secure key contained in the secure key repository can be performed in-place, or in staged mode:
In-place
immediately replaces the secure key in the repository with the re-enciphered secure key. Re-enciphering from OLD to CURRENT is performed in-place per default. You can use option --in-place to force an in-place re-enciphering for the CURRENT to NEW case. Be aware that a secure key that was re-enciphered in-place from CURRENT to NEW is no longer valid, until the new CCA or EP11 master key has been made the current one.
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 and made active, you must rerun the re-encipher command with option --complete to complete the staged re-enciphering. Re-enciphering from CURRENT to NEW is performed in staged mode per default. For CCA master keys, you can use option --staged to force a staged re-enciphering for the OLD to CURRENT case.
Note: The reencipher command requires the CCA host library (libcsulcca.so) to be installed for the support of CCA secure keys. It requires the Linux® on Z Enterprise PKCS #11 (EP11) Support Program (EP11 host library) to be installed for support of secure keys of type EP11-AES.

Examples: Assuming there is only one secure key (secure_xtskey1) matching the filters in the --name and --apqns options, the following three examples deliver the same result:


# zkey reencipher --name secure_xtskey1
# zkey reencipher --apqns 03.0039 --staged
# zkey reencipher --name "sec*" --apqns "*.0039" --staged

Re-enciphering key 'secure_xtskey1'
The secure key is currently enciphered with the CURRENT master key and is
being re-enciphered with the NEW master key

Staged re-enciphering is initiated for key 'secure_xtskey1'. After the NEW 
master key has been set to become the CURRENT master key run 'zkey reencipher'
with option '--complete' to complete the re-enciphering process

1 keys re-enciphered, 0 keys skipped, 0 keys failed to re-encipher