pkcshsm_mk_change - Man Page

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. Important: CCA does not support the concept of APQNs when running on AIX, Linux on x64, and Linux on Power; whenever an APQN is being used as input, the user must specify the value 0.0.

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.

-a,  --apqns APQNS

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.

-e,  --ep11-wkvp WKVP

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'.

-s,  --cca-sym-mkvp MKVP

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].

-S,  --cca-asym-mkvp MKVP

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].

-A,  --cca-aes-mkvp MKVP

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'.

-p,  --cca-apka-mkvp MKVP

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'.

-i,  --id OPERATION-ID

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.

-v,  --verbose LEVEL

Specifies the verbose level (optional): none (default), error, warn, info, devel, or debug.

-h,  --help

Displays help text and exits.

opencryptoki(7)