PKCSHSM_MK_CHANGE(1) openCryptoki PKCSHSM_MK_CHANGE(1)

pkcshsm_mk_change - utility to manage and control the re-enciphering of secure keys for a concurrent HSM master key change for openCryptoki.

pkcshsm_mk_change command [OPTIONS]

pkcshsm_mk_change --help|-h

Manages and controls the re-enciphering of secure keys for a concurrent HSM master key change for openCryptoki. Secure keys are encrypted by the HSM master key(s). The HSM master key(s) must be changed (rolled) from time to time, dependent on policies defined by the HSM security officer. Whenever a HSM master key is changed, all secure keys that are encrypted with that HSM master key must be re-enciphered with the new to be set master key.

Changing HSM master keys needs to be coordinated between the HSM security officer and an openCryptoki administrator. The HSM security officer performs a master key change via the TKE (Trusted Key Entry), while the openCryptoki administrator performs administrative steps using the pkcshsm_mk_change tool to re-encipher all openCryptoki token and session key objects, as well as currently active crypto operation states with the new master key. Applications using those keys can continue to run, the re-enciphering process takes place transparently to them.

A concurrent master key change works as follows:

1.
The HSM security officer loads the new master keys using the TKE into the NEW register of the set of APQNs logically belonging together.

2.
The HSM security officer notifies the openCryptoki administrator that new master keys have been loaded for all the APQNs.
3.
The openCryptoki administrator uses the pkcshsm_mk_change to initiate a master key change for openCryptoki, specifying the set of APQNs (and master key types) that are to be changed. The pkcshsm_mk_change tool communicates with running applications and performs/controls re-encipherment of the key objects with the new master key.
4.
When the pkcshsm_mk_change tool has completed its re-encipherment processing, the openCryptoki administrator notifies the HSM security officer that openCryptoki is ready to set/activate the new master keys.
5.
The HSM security officer coordinates with other (non-openCryptoki) applications and once all users of the APQNs are OK, he sets/activates the new master keys on the APQNs.
6.
The HSM security officer notifies the openCyptoki administrator when for all APQNs the new master key have been set/activated.
7.
The openCryptoki administrator uses the pkcshsm_mk_change tool to finalize the master key change for openCryptoki. The tool communicates with running applications and performs/controls finalizing the re-encipherment of the key objects with the new master key.
8.
When the pkcshsm_mk_change tool has completed its finalizing processing, the master key change operation is complete.

The whole procedure can take an arbitrary amount of time. Especially the time between the moment when the new master key has been loaded on all APQNs, and the moment the new master keys are set/activated can even last several days, due to time required for coordination with other (non-openCryptoki) applications/users of the APQNs to prepare for the master key change.

The time to perform the re-encipherment and finalization (steps 3 and 7) of all key objects as such depends on the amount of keys and openCryptoki applications using them, but is usually relatively short, i.e. seconds up to a few minutes.

The system where openCryptoki runs may be restarted while a master key change is ongoing, provided that the re-encipherment and finalization steps (steps 3 and 7) are not interrupted.

An ongoing master key change operation can be canceled using the pkcshsm_mk_change tool, as long as for none of the APQNs the new master key has been set/activated, that is up to step 5 from above.

pkcshsm_mk_change reencipher [--apqns|-a APQNS] [--ep11-wkvp|-e WKVP] [--cca-sym-mkvp|-s MKVP] [--cca-asym-mkvp|-S MKVP] [--cca-aes-mkvp|-A MKVP] [--cca-apka-mkvp|-p MKVP] [--verbose|-v LEVEL]

Use the reencipher command to initiate a master key change operation for the specified APQNs and master key types and re-encipher all session and token key objects of the affected tokens. For each master key type that is changed, the verification pattern of the new, to be set master key must be specified.

A CryptoExpress adapter in CCA coprocessor mode has 4 different master keys: SYM, ASYM, AES, and APKA. The CCA token of openCryptoki only uses SYM, AES, and APKA. Each master key type can be change individually, or together with others. You can use the TKE or the panel.exe tool to query the master key verification patterns: 'panel.exe --mk-query --mktype=<type> --mkregister=NEW'. For master key types SYM and ASYM, use the hex string under [RND], for types AES and APKA use the hex string under [VER]. For AES and APKA you can also find the master key verification patterns in sysfs: 'cat /sys/bus/ap/devices/<card>.<domain>/mkvps'.

A CryptoExpress adapter in EP11 coprocessor mode has only one master key, called the EP11 wrapping key (WK). You can use the TKE or the ep11info tool to query the current wrapping key verification pattern (WKVP) of an EP11 APQN: 'ep11info -m <adapter> -d <domain> -D'. You can also find the wrapping key verification pattern for EP11 APQNs in sysfs: 'cat /sys/bus/ap/devices/<card>.<domain>/mkvps'.

the pkcshsm_mk_change reencipher command will query all available slots and determine if the token in the slot is affected by the master key change, based on the list of APQNs and master key types. For each affected slot, it prompts for the USER pin.

On successful completion, the id of the master key change operation is displayed. This id must later be specified when finalizing or canceling the operation using the finalize or cancel command.

pkcshsm_mk_change finalize [--id|-i OPERATION-ID] [--verbose|-v LEVEL]

Use the finalize command to finalize a master key change operation when the new master key has been activated on the APQNs. The id of the master key change operation to finalize must be specified.

pkcshsm_mk_change cancel [--id|-i OPERATION-ID] [--verbose|-v LEVEL]

Use the cancel command to finalize a master key change operation. The id of the master key change operation to cancel must be specified. A master key change operation can only be canceled as long as for none of the APQNs the new master key have been set/activated.

pkcshsm_mk_change list [--id|-i OPERATION-ID] [--verbose|-v LEVEL]

Use the list command to list currently active master key change operations. If no operation ID is specified, all currently active master key change operations are displayed, otherwise only the specified one is displayed.

Specifies a comma separated list of APQNs for which a master key change is to be performed. Each APQN must be specified in the form card.domain, where both card and domain are in hex, as displayed by the lszcrypt command. Multiple APQNs are separated by a comma. This options is only valid with the reencipher command.
Specifies the EP11 wrapping key verification pattern (WKVP) of the new, to be set EP11 wrapping key as a 16 bytes hex string. This options is only valid with the reencipher command. You can use the TKE or the ep11info tool to query the current wrapping key verification pattern (WKVP) of an EP11 APQN: 'ep11info -m <adapter> -d <domain> -D'. You can also find the wrapping key verification pattern for EP11 APQNs in sysfs: 'cat /sys/bus/ap/devices/<card>.<domain>/mkvps'.
Specifies the CCA master key verification pattern (MKVP) of the new, to be set CCA SYM master key as a 8 bytes hex string. This options is only valid with the reencipher command. You can use the TKE or the panel.exe tool to query the master key verification patterns: 'panel.exe --mk-query --mktype=SYM --mkregister=NEW'. Use the hex string under [RND].
Specifies the CCA master key verification pattern (MKVP) of the new, to be set CCA ASYM master key as a 8 bytes hex string. This options is only valid with the reencipher command. You can use the TKE or the panel.exe tool to query the master key verification patterns: 'panel.exe --mk-query --mktype=ASYM --mkregister=NEW'. Use the hex string under [RND].
Specifies the CCA master key verification pattern (MKVP) of the new, to be set CCA AES master key as a 8 bytes hex string. This options is only valid with the reencipher command. You can use the TKE or the panel.exe tool to query the master key verification patterns: 'panel.exe --mk-query --mktype=AES --mkregister=NEW'. Use the hex string under [VER]. You can also find the AES master key verification patterns in sysfs: 'cat /sys/bus/ap/devices/<card>.<domain>/mkvps'.
Specifies the CCA master key verification pattern (MKVP) of the new, to be set CCA APKA master key as a 8 bytes hex string. This options is only valid with the reencipher command. You can use the TKE or the panel.exe tool to query the master key verification patterns: 'panel.exe --mk-query --mktype=APKA --mkregister=NEW'. Use the hex string under [VER]. You can also find the APKA master key verification patterns in sysfs: 'cat /sys/bus/ap/devices/<card>.<domain>/mkvps'.
Specifies the id of the master key change operation for the finalize, cancel, or list command. On successful completion of the reencipher command, the id of the master key change operation is displayed.
Specifies the verbose level (optional): none (default), error, warn, info, devel, or debug.
Displays help text and exits.

August 2022 3.23