Managing a concurrent master key change - pkcshsm_mk_change utility

Description

The pkcshsm_mk_change utility initiates and maintains master key changes for openCryptoki. It manages and controls the re-enciphering of secure keys for a concurrent HSM master key change. It maintains the state of each master key change operation on files stored in the file system (that is, in directory /var/lib/opencryptoki/HSM_MK_CHANGE/). Multiple master key change operations can be ongoing concurrently to running workloads. Concurrency between multiple master key change operations themselves is only possible if these changes do not apply to the same APQNs and the same master key types simultaneously. Such a concurrency is only possible on the same APQN for different master key types or on different APQNs.

Notes:

• A master key is called wrapping key in EP11. In the pkcshsm_mk_change utility, the term master key is generally used and applies to both and therefore, this term might denote an EP11 wrapping key.

Coordination of a concurrent master key rotation

Your security policies may require that in certain time intervals a new master key must be generated, for example, using a Trusted Key Entry workstation. This new master key must be loaded onto the cryptographic coprocessors . Changing master keys needs to be coordinated between the HSM security officer and an openCryptoki administrator and possibly also between further applications. All secure keys enciphered by the master key need to be re-enciphered with the new master key as part of the master key change process. However, when performing the master key change process with the help of pkcshsm_mk_change, applications can continue to run while the master key change procedure is performed.

Two parties are involved in a master key change on the HSM. The openCryptoki administrator uses the pkcshsm_mk_change tool to initiate and control a master key change operation, coordinated with the HSM security officer who performs the master key changes on the HSMs via the TKE (Trusted Key Entry) workstation. During the ongoing master key change, applications using openCryptoki can continue to run without being affected, besides possibly a slight performance degradation while master key change actions are performed.

A concurrent master key change works as follows:

1. The HSM security officer loads the new master key(s) using the TKE into the NEW register of the set of APQNs logically belonging together, that is, APQNs configured with the same master key.
2. The HSM security officer notifies the openCryptoki administrator that a new master key has been loaded for all the APQNs. Preferably, the HSM security officer also communicates the master key verification pattern of the new master key to the openCryptoki administrator.
3. The openCryptoki administrator uses the pkcshsm_mk_change tool to initiate a master key change for openCryptoki, specifying the set of APQNs that are to be changed, and the verification patterns of the new master keys to be set (per master key type). The tool communicates with the openCryptoki runtime used by the running applications and performs and controls the 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 prepared to have the new master keys being activated.
5. The HSM security officer coordinates with other (non-openCryptoki) applications and once all users of the APQNs are prepared, he or she activates the new master keys on the APQNs.
6. The HSM security officer notifies the openCryptoki administrator as soon as for all APQNs the new master key has been activated.
7. The openCryptoki administrator uses the pkcshsm_mk_change tool to finalize the master key change for openCryptoki. The tool communicates with the openCryptoki runtime used by the running applications and performs and controls the finalization of the re-encipherment of the key objects with the new master key.
8. When the pkcshsm_mk_change utility has completed its finalizing processing, the master key change operation is complete.

The time between the moment when the new master key has been loaded on all APQNs, and the moment when the new master keys are activated can even last several days, due to the time required for coordination with other (non-openCryptoki) applications or users of the APQNs.

You can restart the Linux system where openCryptoki runs while a master key change is ongoing, provided that the re-encipherment and finalization steps (step 3 and step 7) are not interrupted.

You can cancel an ongoing master key change operation, as long as for none of the APQNs the new master key has been activated, that is up to step 5.

A backup of the old secure keys is kept in attribute CKA_IBM_OPAQUE_OLD of the key objects. In case something goes wrong, you can restore the old secure keys from that attribute. For this purpose, you must implement a PKCS #11 application accessing all the key objects through regular PKCS #11 API calls to restore the secure keys by moving the secure keys from CKA_IBM_OPAQUE_OLD to CKA_IBM_OPAQUE.

Concurrent master key change considerations for access-controlled tokens

Take care when performing a concurrent master key change for an EP11 token or a CCA token that is protected by a token-specific group (see Customizing access control to the openCryptoki tokens). The user that is initiating the concurrent master key change by running the pkcshsm_mk_change tool must be a member of all token groups of tokens affected by the master key change. If that user is not a member of the token groups, then the pkcshsm_mk_change tool does also not have access to these tokens, and thus, it can not determine if the tokens are affected by the master key change or not.

If a token would be affected by a master key change, but is not available to the pkcshsm_mk_change tool, then its key objects will not be re-enciphered, and thus the keys are most likely lost after the new master keys have been activated.

Considerations for a master key rotation on CCA cryptographic coprocessors

A CCA cryptographic adapter has four different master key types:

SYM

A Triple-DES master key, used to encipher DES and Triple-DES secure keys.

ASYM:

A Triple-DES master key, used to encipher older RSA secure keys.

AES

An AES master key, used to encipher AES secure keys.

APKA

An AES master key, used to encipher ECC secure keys, and newer RSA secure keys (those with section X’30’ and X’31’). This master key type is also used for QSA key types in CCA, wich are currently not yet supported by openCryptoki.

All four master keys can be changed together, or individually. Consequently, though this is not typical for a security environment, one can initiate multiple concurrent master key change operations, separated for the different CCA master key types, possibly for the same APQNs. An openCryptoki CCA token uses only the SYM, AES and APKA master keys. The ASYM master key is not used, because only newer RSA secure key types are used.

A CCA cryptographic adapter has three registers per master key type:

NEW

New master keys are loaded into this register. Master keys in the NEW register can only be used to re-encipher secure keys.

CURRENT

The current master key to perform cryptographic operations with secure keys.

OLD

The previous master key. Secure keys enciphered with the master key in the OLD register can still be used to perform cryptographic operations.

Invocation and usage

The general invocation scheme of the command line tool is:

1  pkcshsm_mk_change <subcommand>? args? options

where

subcommand

may accept one of the following values:

• reencipher (see Initiate a master key change plus re-encryption for openCryptoki)
• list (see List master key change operations)
• finalize (see Finalize a master key change for openCryptoki)
• cancel (see Cancel a master key change for openCryptoki)

For further information you can read the pkcshsm_mk_change man page.

Initiate a master key change plus re-encryption for openCryptoki

Use the pkcshsm_mk_change reencipher subcommand to initiate a master key change for the specified APQNs and the specified master key (wrapping key) types together with the verification patterns of the new master keys to be set. This subcommand also re-enciphers all session and token key objects of the affected tokens. It stores information persistently, returns and prints the ID of the initiated master key change operation. You must use this subcommand at the point in time when all APQNs have the new master key loaded but not yet set (that is, not yet activated). This subcommand tells the openCryptoki runtime within all applications using openCryptoki to re-encipher their key objects. It waits until all applications' openCryptoki runtime instances have completed to re-encipher their key objects. For each master key type that is changed, the verification pattern of the new, to be set master key must be specified.

A cryptographic adapter in CCA coprocessor mode can have four different types of master keys: SYM, ASYM, AES, and APKA. The CCA token of openCryptoki only uses SYM, AES, and APKA. Each master key type can be changed individually, or together with others. You can use the TKE or the panel.exe tool to query the master key verification patterns issuing the following command:

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 cryptographic coprocessor in EP11 coprocessor mode has only one master key, called the EP11 wrapping key (WK).

The pkcshsm_mk_change reencipher subcommand queries all available slots and determines 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 be specified when finalizing or canceling the operation with the finalize or cancel subcommand.

1  pkcshsm_mk_change reencipher? --apqns|-a<apqns>? --ep11-wkvp|-e<wrapping_key_verification_pattern>? --cca-sym-mkvp|-s<master_key_verification_pattern>? --cca-asym-mkvp|-S<master_key_verification_pattern>? --cca-aes-mkvp|-A<master_key_verification_pattern>? --cca-apka-mkvp|-p<master_key_verification_pattern>? --verbose|-v<level>

The options for all subcommands are explained in Options for the pkcshsm_mk_change utility.

Example: Initialization of an EP11 wrapping key change:

The following example shows how to initiate a master key change for all EP11 tokens that are allowed to access the specified APQNs. This master key change will then start concurrently to all running applications that exploit the applicable EP11 tokens. A prerequisite of this action is that a new EP11 wrapping key (or master key) has been loaded into the NEW register using the TKE. You need to know the User PINs of all affected slots.

# pkcshsm_mk_change reencipher --apqns 06.0033,0e.0033,1c.0033 --ep11-wkvp ef92899ebe57291ec8e8716d850ee2f7 

WARNING: The following slots have no token present:
  Slot 0
ATTENTION: If you start a concurrent master key change operation while not
all expected tokens are present, the key objects of those tokens may be lost,
if the token would be affected by the master key change.
Continue [y/N]? y
The following tokens are affected by this master key change:
  Slot 4: Label: ep11
Enter the USER PIN for slot 4:
Re-enciphering, please wait...
Completed.

Master key change operation 'uNA5QP' created.

Once the new master keys have been set/activated:
 - If you specified EXPECTED_MKVPS in your token configuration file(s),
   you must now replace the old MKVPs with the new MKVPs. 
 - Run 'pkcshsm_mk_change finalize --id uNA5QP' when the new master
   keys have been set/activated.

The ID of this master key change operation is uNA5QP and can or must be re-used in option --id|-i in subsequent subcommands.

Example: Initialization of a CCA master key change for various master key types:

# pkcshsm_mk_change reencipher --apqns 08.0033,09.0033,1b.0033 --cca-sym-mkvp 130E2053F18E5F4C 
                                 --cca-asym-mkvp F8AE2ACF8BFC57F0 
                                 --cca-aes-mkvp 7D10D17BC8A409C4 
                                 --cca-apka-mkvp 82A5E2CD5030D5EC

WARNING: The following slots have no token present:
...
The following tokens are affected by this master key change:
  Slot 2: Label: cca
...
Master key change operation 'FYZ4WC' created.
...

The ID of this master key change operation is FYZ4WC and can or must be re-used in option -i|--id in subsequent subcommands.

For further information you can read the pkcshsm_mk_change man page.

List master key change operations

Use the pkcshsm_mk_change list subcommand to list currently active master key change operations. If you do not specify an operation ID in option --id|-i (described in Initiate a master key change plus re-encryption for openCryptoki), all currently active master key change operations are displayed, otherwise only the specified one is displayed.

1  pkcshsm_mk_change list? --id|-i<operation_id>? --verbose|-v<level>

Example of listing a master key change operation:

To display information about the current master key change process as initialized with the command shown in Initiate a master key change plus re-encryption for openCryptoki, enter the following command:

# pkcshsm_mk_change list -i uNA5QP

Operation:       uNA5QP
    State:       Key objects have been re-enciphered,
                 new master key(s) can now be set/activated
    APQNs:
        06.0033
        0E.0033
        1C.0033
    New master key verification patterns:
        Type:    EP11
        MKVP:    EF92899EBE57291EC8E8716D850EE2F7
    Affected slots:
        Slot: 4 Label: ep11
            Current master key verification patterns:
                Type:    EP11
                MKVP:    8B991263E3A8F4E4BE0D5EC8F0A4DF9E

The optional -i parameter specifies the operation ID of the current master key change process. For a detailed description, see Initiate a master key change plus re-encryption for openCryptoki.

Now you need to activate the new EP11 master key using the TKE. Then you can finalize the master key change process as described in Finalize a master key change for openCryptoki.

Finalize a master key change for openCryptoki

Use the pkcshsm_mk_change finalize subcommand to finalize a master key change operation when the new master key has been activated on the APQNs. You must specify the ID of the master key change operation to be finalized.

1  pkcshsm_mk_change finalize --id|-i<operation_id>? --verbose|-v<level>

Example of finalizing a master key change:

To finalize the current master key change process as initialized with the command shown in Initiate a master key change plus re-encryption for openCryptoki, enter the following command.

# pkcshsm_mk_change finalize --id uNA5QP
Enter the USER PIN for slot 4:
Finalizing, please wait...

Master key change operation 'uNA5QP' successfully finalized.

Cancel a master key change for openCryptoki

Use the pkcshsm_mk_change cancel subcommand to cancel a master key change operation. You must specify the ID of the master key change operation to be canceled. You can only cancel a master key change operation as long as for none of the APQNs the new master key has been set (activated).

1  pkcshsm_mk_change cancel --id|-i<operation_id>? --verbose|-v<level>

Example of canceling a master key change:

To cancel the current master key change, as initialized with the command shown in Initiate a master key change plus re-encryption for openCryptoki, enter the following command:

# pkcshsm_mk_change cancel --id uNA5QP
Enter the USER PIN for slot x:
     /* ( ==> prompted for every effected token .....) */ 
Canceling, please wait...

Master key change operation 'uNA5QP' successfully canceled.

Options for the pkcshsm_mk_change utility

The following list describes the meanings of all options available for all subcommands:

--apqns|-a

This option 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, denoting the cryptographic adapter and the domain on the adapter card, for example, 0a.0024, where both numbers are specified with hexadecimal format, as displayed by the lszcrypt command.

--ep11-wkvp|-e

In parameter <wrapping_key_verification_pattern>, this option specifies the EP11 wrapping key verification pattern (WKVP) of the new EP11 wrapping key (master key) to be set as a 16 bytes hexadecimal string.

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

For more information about the ep11info tool, see Obtaining information about an EP11 environment with the ep11info tool.

--cca-sym-mkvp|-s

In parameter <master_key_verification_pattern>, this option specifies the CCA master key verification pattern (MKVP) of the new CCA SYM master key to be set as an eight bytes hex string. You can use the TKE or the panel.exe tool to query the master key verification patterns. Use the hex string under [RND].

panel.exe --mk-query --mktype=SYM --mkregister=NEW

--cca-asym-mkvp|-S

In parameter <master_key_verification_pattern>, this option specifies the CCA master key verification pattern (MKVP) of the new CCA ASYM master key to be set as an eight bytes hex string. You can use the TKE or the panel.exe tool to query the master key verification patterns. Use the hex string under [RND].

panel.exe --mk-query --mktype=ASYM --mkregister=NEW

--cca-aes-mkvp|-A

In parameter <master_key_verification_pattern>, this option specifies the CCA master key verification pattern (MKVP) of the new CCA AES master key to be set as an eight bytes hex string. You can use the TKE or the panel.exe tool to query the master key verification patterns. Use the hex string under [VER].

panel.exe --mk-query --mktype=AES --mkregister=NEW

You can also find the AES master key verification patterns in sysfs as previously described.

--cca-apka-mkvp|-p

In parameter <master_key_verification_pattern>, this option specifies the CCA master key verification pattern (MKVP) of the new CCA APKA master key to be set as an eight bytes hex string. You can use the TKE or the panel.exe tool to query the master key verification patterns. Use the hex string under [VER].

panel.exe --mk-query --mktype=APKA --mkregister=NEW

You can also find the APKA master key verification patterns in sysfs as previously described.

--id|-i

This option specifies the ID of the master key change operation in parameter <operation_id>, for example, in the pkcshsm_mk_change finalize subcommand. You cannot specify this option for the reencipher subcommand, however this ID is produced and displayed as a result of a successful completion of the reencipher subcommand. The use of this option is only required for the finalize and cancel subcommands, and is optional for the list subcommand.

--verbose|-v

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

--help|-h

Displays help text and exits. For example you can request help for the complete tool or for the subcommands separately:

pkcshsm_mk_change -h
pkcshsm_mk_change initialize -h
pkcshsm_mk_change finalize -h
pkcshsm_mk_change cancel -h
pkcshsm_mk_change list -h