PKCSHSM_MK_CHANGE(1)

✨ PKCSHSM_MK_CHANGE ✨

okay bestie, buckle up, we're doing section 1 of the openCryptoki manuals and this one is a whole ✨journey✨ — it's pkcshsm_mk_change, the utility that manages and controls the re-enciphering of secure keys for a concurrent HSM master key change for openCryptoki. 💅

---

🌸 NAME 🌸

pkcshsm_mk_change — utility to manage and control the re-enciphering of secure keys for a concurrent HSM master key change for openCryptoki. no cap, that's literally it.

---

🎀 SYNOPSIS 🎀

pkcshsm_mk_change command [OPTIONS]

pkcshsm_mk_change --help|-h

---

🦋 DESCRIPTION 🦋

So here's the tea, bestie. This tool 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). And those HSM master key(s)? They have to be changed (rolled) from time to time, depending 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. every single one. no keys left behind. 😤

Changing HSM master keys needs to be coordinated between the HSM security officer and an openCryptoki administrator — it's giving collab era 🫶. 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, they literally won't even notice. main character energy for real. ✨

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. yes, the literal string 0.0. that's not a typo, that's the vibe. 🙈

🌈 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. several. whole. days. 😭 patience is a virtue bestie.

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. so like, reboot? fine. interrupt steps 3 and 7? absolutely not. 🚫

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. after that? it's giving "too late, we're committed". 💀

---

👑 COMMANDS 👑

💜 Initiate a master key change for openCryptoki

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. yes, you gotta hand over the receipts. 🧾

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. so have that pin ready bestie, don't be scrambling. 🔑

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. write. it. down. fr fr. 📝

🌸 Finalize a master key change for openCryptoki

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.

🎀 Cancel a master key change for openCryptoki

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.

🦋 List master key change operations

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. window shopping but for key operations. 👀

---

💅 OPTIONS 💅

• -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. the classic escape hatch. 🏃‍♀️

---

⭐ SEE ALSO ⭐

• opencryptoki(7)

---

okay that's the whole page bestie, go forth and roll those master keys responsibly 💖✨

sign-off time: this was 3.27.0, dated August 2022, and it lives in the openCryptoki manual pages. 🎀🦋🌸 stay slay, stay enciphered, and never ever interrupt steps 3 and 7. 💅👑