Migrating applications to PCI-HSM 2016 compliance mode

Edit online

You can migrate existing applications to PCI-HSM 2016. This involves converting the keys that are used by the application to key tokens that are tagged as compliant to PCI-HSM 2016.

The migration process completes with existing key tokens that are converted to being compliant-tagged. Before you complete the migration, it is important that the necessary steps are taken so that upon completion of the migration, future key tokens can be created as compliant-tagged.

Identifying key tokens to be converted using compliance warning events

Except for the Cipher Text Translate2 (CSNBCTT2) verb, a compliant-tagged key cannot be used in a cryptographic operation with a non-compliant-tagged key. Therefore, with that one exception, the key migration process needs to ensure that for each key that is to be compliant-tagged, all keys it can be used with, must also be compliant-tagged.

One procedure for migrating keys is to put them into one of the following five categories in order from top to bottom:

  1. Keys that are used in non-compliant or unsupported ways. These keys are included in compliance warning events with any of the following results:
    • Non-compliant service
    • Compliance not supported
    • Non-compliant service operation.

    Before these keys can be compliant-tagged, there must be a change to use them in a supported, compliant way.

  2. Keys that are used with a key in category (1). Since keys in this category are used with keys that should not be compliant-tagged, by extension they should not be compliant-tagged.
  3. Keys that are not compliant. The overall warning event result would indicate that a non-compliant key was used and this key is marked as a non-compliant key. The reason for the non-compliance needs to be determined and fixed before the key can be compliant-tagged. For more information, see Restrictions on creation and use of PCI-HSM 2016 compliant key tokens.
  4. Keys that are used with a key in category (3). Since keys in this category are used with keys that cannot be compliant-tagged, by extension these keys should not be compliant-tagged.
  5. Keys that are compliant and only used in compliant ways. These keys are only included in warning events with an overall result of compliance.

For help interpreting the compliance warning events, see section Warning log message layout.

As the issues in categories 1 to 4 are resolved, you are left only with keys in category 5. At this point, you can successfully compliant-tag all your keys. Further information is in Migration mode.

It might be the case that not all keys can become compliant-tagged, for instance, when a key is used in a verb that does not support compliance. In this case, you have a key or keys that remain in category 1 and possibly also in category 2 that should not be compliant-tagged. The keys in category 5 can still be compliant-tagged. A similar situation arises when a key that is used in an otherwise compliant way is itself non-compliant. In this case, you have a key or keys that are remaining in category 3 and possibly also in category 4 that should not be compliant-tagged. Once again, the keys in category 5 can still be compliant-tagged. These scenarios are not mutually exclusive so you might end up with keys in categories 1 to 5 at migration time. If the categories are strictly adhered to, you can compliant-tag the keys in category 5.

All requests that are selected for compliance warning processing should be routed to a CEX6C coprocessor by the application. The CCA host library does not change application routing decisions if a CEX5C cryptographic coprocessors has been selected for processing. To avoid application changes, it is recommended to disable any CEX5C instances using the chzcrypt -d command before making use of the warning mode with CEX6C adapters. This will avoid any errors from routing issues.

Identifying key tokens to be converted outside of compliance warning events

Since compliance warnings are based on actual usage, be especially aware of operations (for example, infrequent operations) which might not be started during the period where warnings are being collected. These operations would not show up in a warning log and so must be discovered and analyzed independently.

It might be necessary to do an analysis of the key storage to identify the key tokens to be converted. If the key labels follow a naming convention, the DES Key Record List (CSNBKRL) and Combined Key Record List (CSNBCKRL) callable services can be used to produce a list of labels according to a filter. You can use the panel.exe utility to list all the DES key tokens from key storage. The panel.exe utility also uses the CSNBKRL and CSNBCKRL services.

Key tokens that are identified in this way do not have any information about how they are used. So either the usage of such key tokens must be understood, or all the key tokens that are used must be converted together.

Ensure the key tokens identified can become compliant-tagged

When the key tokens to be converted have been identified, you need to ensure that the process of compliant-tagging the key tokens is successful. Compliant-tagged key tokens cannot be used with non-compliant-tagged key tokens. So you do not want the conversion of some tokens to fail while others succeed. You do this by compliance-checking the key tokens first. Key tokens are compliance-checked by using the Key Translate2 (CSNBKTR2) verb with the COMP-CHK keyword.

Migration mode

Existing keys are transformed into compliant-tagged keys using the migration mode of the adapter domain. This migration mode is a temporary sub-state of the PCI-HSM 2016 compliance mode.

The process is like follows:

  1. Your cryptographic coprocessor starts in a normal, non-compliant mode.
  2. Take one or more domains to the PCI-HSM 2016 compliance mode, using the TKE workstation for administrative steps.
  3. Now you can create new tokens with the compliance-tag. You cannot migrate legacy tokens by adding the compliance-tag while in the operational compliance mode, because this is a sensitive operation that could compromise security.
  4. Take one or more domains to migration mode, using the TKE workstation for administrative steps.
    Note: You can only enter the migration mode from the PCI-HSM 2016 compliance mode.
  5. Now you can migrate legacy tokens using the CSNBKTR2 verb with the COMP-TAG keyword.

The migration mode has an inactivity timeout. If no key migration actions (initiated from the CSNBKTR2J verb using the COMP-TAG keyword) are received within 30 minutes, then the domain automatically exits migration mode and returns to the PCI-HSM 2016 compliance mode. Note that in migration mode you are allowed to migrate legacy tokens by adding the compliance-tag . However, no compliance-tagged key operations other than key migration are allowed in migration mode, as required for PCI-HSM 2016 compliance.

Converting key tokens to become compliant-tagged

Make sure to identify all key tokens that must be converted, because they cannot be used in a non-compliant way. Then verify that they can be converted to compliant-tagged key tokens. If your verification is successful, you can start the conversion.

At this point, you must decide what backup strategy, if any, to pursue. Depending on the nature of your workloads, your backup strategy can include, but is not be limited to:
  1. Making a backup copy of the key storage.
  2. Retrieving the key tokens to be converted from the key storage and storing them in a file.

Instead of making a backup copy of the key storage, you can write the compliant-tagged key tokens to new key storage labels.

Key tokens are converted to compliant-tagged tokens by using the Key Translate2 (CSNBKTR2) verb with the COMP-TAG keyword.

To begin the conversion, at least one CCA coprocessor must be placed in migration mode by using the TKE workstation. To confirm the compliance mode of a CCA coprocessor, view the hardware status panel. Also, take note of the number of CCA coprocessors in PCI-HSM 2016 compliance mode without being in migration mode. A coprocessor in migration mode cannot handle requests that contain compliant-tagged key tokens. Therefore, if workloads that use compliant-tagged key tokens are already in use (for example, you previously converted some key tokens to compliant-tagged), you must keep one or more coprocessors in PCI-HSM 2016 compliance mode, but not in migration mode.

At this point in the process, none of the key tokens should fail because they were previously compliance-checked. However, if for some reason there is a failure such that some of the key tokens were converted and others were not, the key tokens should be brought back to a consistent state as soon as possible. This means that the key tokens should be updated such that they are all compliant-tagged or all non-compliant-tagged. If a backup copy of the CKDS was made, it can be used to make all the key tokens non-compliant-tagged until the issue can be resolved. If the process involves creating compliant-tagged key tokens under new key labels, the old labels can still be used until the issue is resolved.