IBM Cloud Docs
Migrating from Hyper Protect Crypto Services (HPCS) to Key Protect Dedicated

Migrating from Hyper Protect Crypto Services (HPCS) to Key Protect Dedicated

Users of Hyper Protect Crypto Services (HPCS) who want or need to migrate to Key Protect Dedicated should follow this comprehensive migration guide, which covers:

Assessment Phase:

Migration by Feature:

Completion:

Identifying HPCS usage

Check all IBM Cloud accounts for HPCS instances.

For each IBM Cloud account, run the following IBM Cloud CLI command:

ibmcloud resource service-instances --all-resource-groups --long --service-name hs-crypto --limit 100

Before you run the command, confirm that the IBM Cloud CLI is targeting the intended account:

ibmcloud target

Verify that the account that is shown in the output matches the account that you want to check. The IBM Cloud CLI operates on a single active account at a time. Running the command against the wrong account might result in missing HPCS instances.

Ensure that you:

  • Log in with a user that is an account administrator with account-wide Viewer (platform) and Reader (service) access across all services.

  • Explicitly target each account that you want to check by using the following command:

    ibmcloud target -c <account_id>

The command searches for HPCS instances across all resource groups in the targeted account, but only instances that you are authorized to see are returned. An empty result might indicate insufficient permissions or the absence of HPCS instances.

Listing HPCS instances requires service-level access because IBM Cloud IAM enforces both platform and service authorization, and HPCS restricts instance discovery to authorized users.

You can also verify HPCS usage by reviewing IBM Cloud billing reports. The presence of HPCS charges indicates that an HPCS instance exists in the account. To do so, log in to IBM Cloud with a user that is an account administrator and has sufficient permissions to view billing and usage data, open https://cloud.ibm.com/billing/usage and check for usage type Hyper Protect Crypto Services.

You can also verify HPCS usage by reviewing the IBM Cloud Resource list. To do so log in to IBM Cloud with a user that is an account administrator with account-wide Viewer (platform) and Reader (service) access across all services, open https://cloud.ibm.com/resources and check for resource instances of product Hyper Protect Crypto Services.

For more information about IAM roles and how to assign access, check out IBM Cloud IAM roles.

If no HPCS instances exist, no migration is required.

Searching for usage

If you have HPCS instances, you need to determine how you are using those resources. The following table describes various methods for identifying HPCS usage:

Table 1. Methods for identifying HPCS usage
Method Description Considerations
Activity tracking events Provides factual indication of HPCS usage through logged events Search for events by using the largest time window possible. Lack of events does not necessarily mean no usage because usage can occur during rare events (for example, restart of an IBM Cloud service instance) or between long intervals that might exceed the event retention period.
Associations Shows HPCS usage by IBM Cloud resources Lack of associations does not necessarily mean no usage due to the nature of distributed computing systems in which resources are not always in sync. Conversely, presence of associations does not necessarily mean active usage, associations can be stale. Some IBM Cloud resources do not create or use associations. List associations by using the kp registrations command.
Sync associated resources Improves synchronization of associations Use the kp key sync command to explicitly sync associated resources and get more accurate association data.
Key Usage Reporter (KUR) CLI tool provided by IBM that scans IBM Cloud accounts and generates a report of resources that reference HPCS keys, grouped by KMS instance and key. Also capable of processing activity tracking audit log files. Discovery and reporting tool only; does not perform migration actions. The tool might not detect all possible usages of keys.

Two separate tools are referenced in this document:

  • Key Migration Tool (CRKM) – used to create migration intents and trigger synchronization. This tool is required for automated CRK migration, see Key Migration Tool (CRKM). .
  • Key Usage Reporter (KUR) – a discovery and reporting tool used to identify services that reference HPCS keys. KUR does not perform migration actions. See Key Usage Reporter (KUR).

Before you proceed with migration activities, ensure that you have the latest version of the Key Protect CLI plug-in installed. This ensures compatibility with all migration features and commands.

To check your current plug-in version:

ibmcloud plugin show key-protect

To update the Key Protect CLI plug-in to the latest version:

ibmcloud plugin update key-protect

If the plug-in is not installed, you can install it by running:

ibmcloud plugin install key-protect

For both HPCS and Key Protect Dedicated, the Key Protect CLI plug-in must read the target instance endpoint from the environment variable KP_TARGET_ADDR. The KP_TARGET_ADDR variable works for both private and public endpoints.

This example command targets an example HPCS instance:

export KP_TARGET_ADDR=https://fadedbee-0000-0000-0000-1234567890ab.api.us-south.hs-crypto.appdomain.cloud

This example command targets an example Key Protect Dedicated instance:

export KP_TARGET_ADDR=https://fadedbee-0000-0000-0000-1234567890ab.api.us-south.kms.appdomain.cloud

You can find the instance endpoint for both HPCS and Key Protect Dedicated in the IBM Cloud UI console for the specific instance.

When you follow this document and use the IBM Cloud CLI to connect to HPCS, ensure that your login user has an IAM policy at the HPCS instance level. An IAM policy at key ring level or the key level might not list all associations and other resources.

Custom apps versus IBM Cloud services and software HPCS usage

HPCS usage comes from two main sources: custom apps and IBM Cloud services or software.

Custom apps

HPCS usage by custom apps occurs when custom code or ISV applications make direct use of HPCS.

Searching for HPCS usage by custom apps is a task that you need to perform with the help of HPCS activity tracking events, code search, and other methods.

Search for usage of the following:

Also search for usage of HPCS through the HPCS PKCS11 library:

Also search for usage through client SDKs:

Search IAM identities with access to HPCS, mostly service IDs and Trusted Profiles, and less commonly user identities. Any identity with roles scoped to the HPCS service, instance, Key Ring, or key is a strong indicator of potential custom application usage.

IBM Cloud services and software

To identify IBM Cloud services and software that are using HPCS, follow this recommended approach:

  1. Start with the Key Usage Reporter (KUR) - The Key Usage Reporter (KUR) tool is the recommended starting point. It scans your IBM Cloud accounts and generates a comprehensive report of resources that reference HPCS keys, grouped by service and key.

  2. Cross-reference with Activity Tracking - Review HPCS activity tracking events over the largest available time window to identify services that have recently performed cryptographic operations. The Key Usage Reporter (KUR) tool is capable of processing activity tracking audit log files, producing CSV summaries that help identify HPCS utilization.

Classifying usage

Each type of HPCS usage relevant to the migration falls into one of the following categories:

Table 2. HPCS usage types
Usage type Description
Customer root keys (CRKs) Encryption of data encryption keys
Standard keys Secrets
KMIP for VMWare Used by VMware KMIP clients
Enterprise PKCS#11 keys Used through PKCS #11 or GREP11 interfaces
UKO-managed keys Managed by Unified Key Orchestrator
Terraform Provisioning HPCS instances using infrastructure as code
Instance provisioning by using the IBM Cloud CLI Instance provisioning
Secure import of root key material Optionally used as part of key import

Migrating your root keys (CRKs)

Checking for the existence of CRKs

Use the following Bash script to count the total number of CRKs in all states for a given HPCS instance.

Make sure that you are logged in to IBM Cloud through the IBM Cloud CLI.

# count the total number of CRKs in all states 
HPCS_ADDR=https://fadedbee-0000-0000-0000-1234567890ab.api.us-south.hs-crypto.appdomain.cloud
HPCS_INSTANCE_ID=fadedbee-0000-0000-0000-1234567890ab
AUTH_HEADER="${AUTH_TOKEN:-$(jq -r .IAMToken ~/.bluemix/config.json)}"
header="$(curl -i -k -s --head \
  "${HPCS_ADDR}/api/v2/keys?state=0,1,2,3,5&extractable=false" \
  -H "authorization: ${AUTH_HEADER}" \
  -H "bluemix-instance: ${HPCS_INSTANCE_ID}" \
  -H "prefer: return=representation" \
| grep '^Key-Total:' \
| tr -d '\r')"
if [ -n "$header" ]; then
  total="${header#Key-Total: }"
  echo "Total number of CRKs in all states: $total"
else
  echo "Error: Key-Total header not found. Try logging into IBM Cloud again. Check endpoint, auth token, or permissions." >&2
fi

Replace HPCS_ADDR and HPCS_INSTANCE_ID with valid values for each HPCS instance. You can find the instance endpoint for HPCS and the instance ID in the IBM Cloud UI console for the specific instance.

The output looks similar to the following example:

Total number of CRKs in all states: 11

If there are zero CRKs across all HPCS instances, CRK migration is not required.

Check the count of CRKs in the Active (1) and Deactivated (Expired) (3) states by using the following script. Only CRKs in the Active (1) or Deactivated (Expired) (3) states can be used for cryptographic operations such aswrap, unwrap and rewrap. A CRK in Deactivated (3) supports unwrap and rewrap but not wrap.

# count the total number of CRKs in Active (1) or Deactivated (Expired) (3) states
HPCS_ADDR=https://fadedbee-0000-0000-0000-1234567890ab.api.us-south.hs-crypto.appdomain.cloud
HPCS_INSTANCE_ID=fadedbee-0000-0000-0000-1234567890ab
AUTH_HEADER="${AUTH_TOKEN:-$(jq -r .IAMToken ~/.bluemix/config.json)}"
header="$(curl -i -k -s --head \
  "${HPCS_ADDR}/api/v2/keys?state=1,3&extractable=false" \
  -H "authorization: ${AUTH_HEADER}" \
  -H "bluemix-instance: ${HPCS_INSTANCE_ID}" \
  -H "prefer: return=representation" \
| grep '^Key-Total:' \
| tr -d '\r')"
if [ -n "$header" ]; then
  total="${header#Key-Total: }"
  echo "Total number of CRKs in Active (1) or Deactivated (Expired) (3) states: $total"
else
  echo "Error: Key-Total header not found. Try logging into IBM Cloud again. Check endpoint, auth token, or permissions." >&2
fi

If there are zero CRKs in the Active (1) or Deactivated (Expired) (3) states across all HPCS instances, no CRKs are available for cryptographic operations. However, this does not necessarily mean that HPCS is not in use. Resources or applications might still be configured to reference CRKs in other states. Any attempt to perform cryptographic operations with such CRKs will fail.

Interpreting CRK counts:

Condition Interpretation Action
Total CRKs = 0 (all states) No CRKs exist in any HPCS instance CRK migration is not required
Total CRKs > 0, but Active (1) + Deactivated (3) = 0 No CRKs are currently usable for cryptographic operations Migration might still be required. Verify whether any resources or applications reference CRKs in other states
Active (1) or Deactivated (3) CRKs exist CRKs are available for cryptographic operations (fully or partially) CRK migration is required

You can obtain the full CRN of HPCS CRKs by using the IBM Cloud CLI kp keys command.

The following example lists CRKs in all states:

export KP_TARGET_ADDR=https://fadedbee-0000-0000-0000-1234567890ab.api.us-south.hs-crypto.appdomain.cloud
ibmcloud kp keys --instance-id fadedbee-0000-0000-0000-1234567890ab --crn --key-type root-key --key-states active,suspended,deactivated,destroyed --number-of-keys 5000

Replace KP_TARGET_ADDR with valid values for each HPCS instance. You can find the instance endpoint for HPCS in the IBM Cloud UI console for the specific instance.

  • The command above lists CRKs in all states, including Suspended (Disabled) and Destroyed (soft deleted) states.
  • Active cryptographic use of CRKs in Suspended (Disabled) and Destroyed (soft deleted) states is not allowed but CRKs in those states can still be referenced by IBM Cloud resources or custom code.
  • It is possible to move CRKs from Suspended (Disabled) and Destroyed (soft deleted) states to Active state.
  • The command can list up to 5000 CRKs at a time. Pagination might be needed to list all CRKs.

Customer root keys (CRKs) migration in custom applications

Custom applications can migrate CRKs to Key Protect Dedicated by rewrapping the data encryption key (DEK) that is protected by HPCS.

The migration process involves the following steps:

  • Unwrap the data encryption key (DEK) from HPCS.
  • Wrap the DEK with Key Protect Dedicated.
  • Generate a new wrapped data encryption key (WDEK).
  • Use the new WDEK for subsequent cryptographic operations.

In all cases, custom applications must:

  • Use a different endpoint. A Key Protect Dedicated instance has an endpoint that is specific to that instance.
  • Use a different key ID.
  • Use an IAM identity, most likely a service ID, that allows access to Key Protect Dedicated at the appropriate level. This might require new IAM policies that target Key Protect Dedicated.

For more information about the Key Protect API, see the Key Protect API reference.

Customer root keys (CRKs) migration in IBM Cloud services and software

Some IBM Cloud services and IBM software that integrate with HPCS can participate in an automated CRK migration workflow to Key Protect Dedicated. This workflow is based on migration intents and key lifecycle synchronization events, and is designed to minimize disruption while preserving cryptographic continuity.

Alternative migration path: re-creating service instances

An alternative to the migration intent workflow is to create a new instance of the IBM Cloud service and configure it with a CRK from Key Protect Dedicated from the start. You then copy the data and metadata from the existing service instance to the new one. After the new instance is verified, the original instance that uses the HPCS CRK can be decommissioned.

This approach might cause interruption of service during the transition period while data is being copied and references are updated to point to the new instance. The trade-off is that this approach requires provisioning new infrastructure, copying data, and updating any references (for example, endpoints, bindings, or application configuration) that point to the original service instance. Evaluate the operational cost of re-creating the service instance against the simplicity of starting fresh with a Key Protect Dedicated CRK.

This section describes the migration intent model, prerequisites, migration flow, and how to monitor progress.

Migration overview

In IBM Cloud services, Customer Root Keys (CRKs) are typically used to encrypt service-managed Data Encryption Keys (DEKs). During migration, the DEKs are rewrapped so that they become encrypted by a Key Protect Dedicated CRK instead of an HPCS CRK without requiring you to re-encrypt data.

At a high level, the migration works as follows:

  1. You declare an intent to migrate an HPCS CRK to a specific Key Protect Dedicated CRK.
  2. IBM Cloud services that are associated with that HPCS CRK detect the intent.
  3. Each service rewraps its DEKs and updates its key associations.
  4. Associations with the HPCS CRK are removed after migration is complete.

Prerequisites

Before you start CRK migration for IBM Cloud services and software, ensure that the following requirements are met:

  • Service support

  • Support for the following IBM services and software is not available at this time:

    You do not need to wait for all services to support migration intents before you begin the migration. Use the Key Usage Reporter (KUR) tool and activity tracking events to determine which services are actually using your HPCS CRKs. If your HPCS keys are used only by services that already support migration intents, you can complete the migration now.

    A single HPCS CRK can be used by both supported and unsupported services at the same time. In this case, create the migration intent now. The services that already support migration intents will detect the intent and complete their migration. The migration intent remains attached to the CRK. When additional services add migration intent support, you only need to run the Sync command from the Key Migration Tool (CRKM) on the same CRKs — there is no need to create new migration intents.

    This means you can start the migration process today and return later to complete it for the remaining services as support becomes available.

  • Target CRKs : Key Protect Dedicated CRKs must already exist. Target CRKs can be generated or imported, with or without customer-supplied key material, via API, CLI or the UI.

  • IAM authorization : Service-to-service IAM authorization policies must allow IBM Cloud services to access the Key Protect Dedicated instance, key ring, or individual key. Refer to the documentation of each service for information about how to establish those service-to-service IAM authorization policies. Note that the Service-to-service IAM authorization policies must be defined in the same account as the target Key Protect Dedicated instance. That account might be different than the account of the service instance. For use cases such as IBM Cloud Databases, Messages for RabbitMQ, Kubernetes and OpenShift services, ensure that delegated authorization is enabled when you create the IAM policy. Most cases of failed migrations occur because this step is not performed or is performed incorrectly.

Migration intents

A migration intent is an optional subresource that is attached to an HPCS CRK. It specifies the target Key Protect Dedicated CRK by CRN.

To initiate migration:

  1. Create a migration intent on the source HPCS CRK.
  2. The intent references the target Key Protect Dedicated CRK.
  3. Migration intents are created by using the Key Migration Tool.

After a migration intent is created, the HPCS service emits synchronization events (one per existing Association) that inform IBM Cloud services that a migration is requested.

For some services (for example, IBM Cloud Databases, Messages for RabbitMQ, Kubernetes and OpenShift services), additional synchronization events must be explicitly triggered a few minutes after intent creation. You can trigger these events by using the Key Migration Tool Sync command.

Migration logic used by IBM Cloud services

When an IBM Cloud service processes a migration intent for an HPCS CRK, it performs the following steps:

  1. Unwrap: The service unwraps the existing Wrapped DEK (WDEK) by calling HPCS to retrieve the plaintext DEK.

  2. Wrap: The DEK is wrapped by using the target Key Protect Dedicated CRK, producing a new WDEK.

  3. Replace: The service replaces the HPCS-wrapped DEK with the Key Protect Dedicated-wrapped DEK.

  4. Association: A new association is created in Key Protect Dedicated, linking the target CRK to the service resource.

  5. Inform: The service notifies HPCS that migration for that resource is complete, which causes HPCS to automatically remove the original association.

This process is performed independently by each service resource that is associated with the HPCS CRK.

Monitoring migration progress

You can monitor migration progress by using several mechanisms:

Associations
The number of Associations that are associated with the HPCS CRK should decrease, ideally to zero if there is no state associations. The number of associations that are associated with the Key Protect Dedicated CRK should increase accordingly.
Key Migration Tool (CRKM)
Reports Association counts for both source and target CRKs. Supports bulk status inspection and retry operations.
Manual synchronization
Synchronization events can be re-triggered at any time through the REST API or Key Migration Tool to retry incomplete migrations.

For Event Streams, after the creation of a migration intent, the migration might take up to one business day. For other services the migration is expected to finish in less than four hours.

Identifying HPCS CRK usage with the Key Usage Reporter (KUR)

To assist with identifying IBM Cloud services that are using HPCS Customer Root Keys (CRKs), IBM provides the Key Usage Reporter (KUR) tool.

KUR is a command-line tool that scans IBM Cloud accounts and generates a report of resources that reference HPCS keys. It helps identify services and resources that are using HPCS keys and might require migration.

The report groups resources by service and includes the CRNs of both the encrypted resources and the associated keys. You can use this information to:

  • Identify candidate services for key migration.
  • Cross-check Associations and activity tracking data.
  • Support migration planning and validation.

KUR is also capable of processing activity tracking audit log files, producing CSV summaries that help identify HPCS utilization patterns.

Important considerations and limitations

  • The migration tooling is provided on a best-effort basis and might not detect every possible usage pattern.
  • Not all IBM Cloud services support migration intent at this time.
  • Some services or specific parts of services (for example, IKS / ROKS persistent volume claims) require specific procedures and are not fully covered by migration intents. See the next sections for more information.
  • You are responsible for validating that all HPCS usage has stopped before you decommission HPCS.

Example migration scenario

The following end-to-end example illustrates how to migrate an HPCS CRK that is used by a Cloud Object Storage instance.

Starting point:

  • An HPCS CRK (HPCS_key_1) protects a DEK used by a Cloud Object Storage instance (COS_1).
  • The objective is for COS_1 to use a Key Protect Dedicated CRK (KP_D_key_1) instead, without moving any data.

Step 1: Identify HPCS CRK usage

Use the Key Usage Reporter (KUR) tool to scan your accounts and identify which services and resources are using HPCS_key_1. Cross-reference the KUR report with activity tracking events to confirm active usage.

Step 2: Create the target CRK in Key Protect Dedicated

Create KP_D_key_1 in your Key Protect Dedicated instance. The target CRK can be generated or imported, with or without customer-supplied key material, through the API, CLI, or the UI.

Step 3: Set up IAM authorization policies

Create service-to-service IAM authorization policies that allow Cloud Object Storage to access the Key Protect Dedicated instance, key ring, or individual key where KP_D_key_1 resides. The IAM policies must be defined in the same account as the target Key Protect Dedicated instance. For services such as IBM Cloud Databases, Messages for RabbitMQ, Kubernetes, and OpenShift, ensure that delegated authorization is enabled when you create the IAM policy.

Most cases of failed migrations occur because IAM authorization policies are not configured or are configured incorrectly.

Before you proceed, use the CRKM tool authz-check command to verify that the required IAM authorization policies are in place. The authz-check command inspects the association on each source HPCS CRK and checks whether a matching IAM authorization policy exists that would allow each registered service to access the target Key Protect Dedicated CRK. For each association, the tool reports whether a matching policy was found or whether a policy is missing, along with a template of the policy that needs to be created. Running this check before you create migration intents helps you identify and fix authorization gaps that would otherwise cause migration failures. For more information, see Key Migration Tool (CRKM).

Step 4: Create the migration intent

Use the Key Migration Tool (CRKM) to create a migration intent on HPCS_key_1 that references the target CRK KP_D_key_1. The CRKM tool accepts a CSV file that contains pairs of source HPCS CRK CRNs and target Key Protect Dedicated CRK CRNs, which makes it possible to create migration intents in bulk.

After the migration intent is created, HPCS emits synchronization events that notify associated services about the migration request.

Step 5: Run Sync

For some services (for example, IBM Cloud Databases, Messages for RabbitMQ, Kubernetes, and OpenShift), additional synchronization events must be explicitly triggered a few minutes after intent creation. Use the CRKM tool Sync command to trigger these events.

You can run the Sync command at any time to retry incomplete migrations.

Step 6: Monitor migration progress

Use the CRKM tool Status command to check the migration progress. The tool reports the association counts for both the source HPCS CRK and the target Key Protect Dedicated CRK. As services complete migration:

  • The number of associations on HPCS_key_1 decreases.
  • The number of associations on KP_D_key_1 increases.

For Event Streams, migration might take up to one business day. For other services, migration is expected to finish in less than four hours.

About the Key Migration Tool (CRKM)

The Key Migration Tool (CRKM) is a CLI tool that supports the following operations:

  • Status — Reports migration progress by showing association counts for source and target CRKs across all CRK pairs.
  • Authz-check — Verifies that the required IAM authorization policies are in place for each registered service before migration. Reports matches and missing policies with actionable templates.
  • Create — Creates migration intents in bulk from a CSV file of source and target CRK CRN pairs.
  • Sync — Triggers synchronization events to prompt services to process the migration intent. Can be run multiple times to retry incomplete migrations.

The CRKM tool is required for automated CRK migration and works with the KUR tool, which handles discovery and reporting.

Standard Key Migration

Standard keys in HPCS store secret material such as API keys, passwords, or encryption keys that are used directly by applications. Unlike CRKs, standard keys do not use the migration intent workflow. Migration of standard keys requires you to retrieve the key material from HPCS and re-provision it in a supported service.

Checking for existence of Standard Keys

Use the following bash script to count the total number of Standard Keys in all valid standard key state, in each HPCS instance.

Make sure that you are logged in to IBM Cloud through the IBM Cloud CLI.

# count the total number of Standard keys in all states 
HPCS_ADDR=https://fadedbee-0000-0000-0000-1234567890ab.api.us-south.hs-crypto.appdomain.cloud
HPCS_INSTANCE_ID=fadedbee-0000-0000-0000-1234567890ab
AUTH_HEADER="${AUTH_TOKEN:-$(jq -r .IAMToken ~/.bluemix/config.json)}"
header="$(curl -i -k -s --head \
  "${HPCS_ADDR}/api/v2/keys?state=1,5&extractable=true" \
  -H "authorization: ${AUTH_HEADER}" \
  -H "bluemix-instance: ${HPCS_INSTANCE_ID}" \
  -H "prefer: return=representation" \
| grep '^Key-Total:' \
| tr -d '\r')"
if [ -n "$header" ]; then
  total="${header#Key-Total: }"
  echo "Total number of Standard keys in all states: $total"
else
  echo "Error: Key-Total header not found. Try logging into IBM Cloud again. Check endpoint, auth token, or permissions." >&2
fi

Replace HPCS_ADDR and HPCS_INSTANCE_ID with valid values for each HPCS instance. You can find the instance endpoint for HPCS and the instance ID in the IBM Cloud UI console for the specific instance.

The output looks similar to the following example:

Total number of Standard keys in all states: 4

If the output is an empty line, log in to IBM Cloud through the IBM Cloud CLI again.

If there are zero Standard Keys in all the HPCS instances, Standard Key migration is not required.

Check the count of standard keys in Destroyed (5) state using the script below.

# count the total number of Standard keys in Destroyed (5) state.
HPCS_ADDR=https://fadedbee-0000-0000-0000-1234567890ab.api.us-south.hs-crypto.appdomain.cloud
HPCS_INSTANCE_ID=fadedbee-0000-0000-0000-1234567890ab
AUTH_HEADER="${AUTH_TOKEN:-$(jq -r .IAMToken ~/.bluemix/config.json)}"
header="$(curl -i -k -s --head \
  "${HPCS_ADDR}/api/v2/keys?state=5&extractable=true" \
  -H "authorization: ${AUTH_HEADER}" \
  -H "bluemix-instance: ${HPCS_INSTANCE_ID}" \
  -H "prefer: return=representation" \
| grep '^Key-Total:' \
| tr -d '\r')"
if [ -n "$header" ]; then
  total="${header#Key-Total: }"
  echo "Total number of Standard keys in Destroyed (5) state: $total"
else
  echo "Error: Key-Total header not found. Try logging into IBM Cloud again. Check endpoint, auth token, or permissions." >&2
fi

If all standard keys are in Destroyed (5) (soft deleted) state, this does not guarantee that there is no usage. An IBM Cloud resource or custom application might still reference the key. In this case, operations are expected to fail the next time key material retrieval is attempted.

Standard keys can exist only in Active (1) or Destroyed (5) states. Other key states apply only to CRKs.

You can obtain the full CRN of HPCS standard keys by using the IBM Cloud CLI kp keys command.

The following example lists standard keys in possible states:

export KP_TARGET_ADDR=https://fadedbee-0000-0000-0000-1234567890ab.api.us-south.hs-crypto.appdomain.cloud
ibmcloud kp keys --instance-id fadedbee-0000-0000-0000-1234567890ab --crn --key-type standard-key --key-states active,destroyed --number-of-keys 5000

Replace KP_TARGET_ADDR with valid values for each HPCS instance. You can find the instance endpoint for HPCS in the IBM Cloud UI console for the specific instance.

  • The command can list up to 5000 standard keys at a time. Pagination might be needed to list all standard keys.

Checking HPCS Usage on AIX

If you have AIX systems (on IBM Cloud or on-premises) and Standard Keys are present in HPCS, run the following commands on the AIX host to verify whether those keys are in use. The TYPE field in the output of the hdcryptmgr commands indicates the HPCS authentication method.

keysvrmgr show -t hpcs
hdcryptmgr showlv <lvname> -v
hdcryptmgr showpv <pvname> -v

If no logical volumes or physical volumes report TYPE=hpcs, the AIX system is not actively using HPCS Standard Keys.

Information about HPCS deprecation and migration to Key Protect Dedicated will be communicated in a future AIX release through official AIX release documentation.

Migration of standard keys

If standard keys exist, besides the Direct Link and AIX usages above, you must migrate them by following these steps:

  1. Retrieve the key material — Use the HPCS API to retrieve the plaintext key material of each standard key.

  2. Re-provision the key material — Store the retrieved key material in a supported service. This can be done either by:

    • Importing the key material into a new Key Protect Dedicated standard key.
    • Storing the secret in IBM Cloud Secrets Manager, which is the recommended solution for general secret material.

  3. Update application references — Update any custom applications, service configurations, or IAM policies that reference the HPCS standard key. Applications must be updated with the new service endpoint, key ID, and any required IAM policies that grant access to the new key in Key Protect Dedicated or Secrets Manager.

  4. Validate — Confirm that all applications and services are functioning correctly with the new key before you decommission the HPCS standard key.

KMIP for VMWare Migration

VMware KMIP support for HPCS will end on 31 December 2026, after which the KMIP for VMware service will no longer work. Detailed instructions on migrating to Key Protect Dedicated is published here.

PKCS #11 (GREP11)

Enterprise PKCS #11 keys used through PKCS #11 or GREP11 interfaces are not supported by Key Protect Dedicated.

To determine whether this feature is being used, check the HPCS activity tracking logs for entries where the action field is hs-crypto.ep11.use or starts with hs-crypto.keystore. The presence of these entries indicates that PKCS #11 (GREP11) is being used.

Please refer to GREP11/PKCS#11 Migration Guide.

Unified Key Orchestrator (UKO)

UKO-managed keys are not supported by Key Protect Dedicated.

Please refer to Refer to UKO Migration Guide.

Terraform

To use Terraform with Key Protect Dedicated, the environment variable IBMCLOUD_KP_API_ENDPOINT must be set to the public or private API endpoint of the specific Key Protect Dedicated instance.

Provisioning a new Key Protect Dedicated instance is available through the IBM Cloud Console UI and the IBM Cloud CLI. Creating new Key Protect Dedicated instances with Terraform is not supported.

For more information see Setting up Terraform for Key Protect

Instance provisioning by using the IBM Cloud CLI

The process for provisioning Hyper Protect Crypto Services instances differs from the process for provisioning Key Protect Dedicated instances when using the IBM Cloud CLI.

See instructions for provisioning Key Protect Dedicated instances by using the IBM Cloud CLI.

Secure import of root key material

Secure import of root key material is not supported by Key Protect Dedicated.

To determine whether this feature is being used, check the HPCS activity tracking logs for entries where the action field is hs-crypto.import-token.create or hs-crypto.import-token.read. The presence of these entries indicates that secure import of root key material is being used.

Key Protect Dedicated supports regular import of root key material, where the key material is encrypted in transit using HTTPS.

Post migration

After you complete the migration to Key Protect Dedicated, you must validate that HPCS instances are no longer in active use and take controlled steps to reduce risk before the HPCS end-of-service date.

Validate that HPCS is no longer in use

After migration, inspect HPCS activity tracking events to confirm that no operations are being performed against HPCS instances.

Review events over the largest available retention window.

If activity tracking events indicate continued usage:

  1. Identify the service or workload that is responsible for the usage.
  2. Verify whether the resource supports CRK migration via migration intent.
  3. Complete or retry migration for that usage before you proceed.

Lack of activity tracking events does not conclusively prove absence of usage. Some services and custom apps use keys infrequently or only during lifecycle events such as restart, restore, or failover.

Gradually disable migrated HPCS CRKs

After you are confident that specific HPCS CRKs are no longer required, you can disable those CRKs.

Disabling CRKs is strongly recommended before deletion because:

  • Any remaining cryptographic operations fail immediately with a clear error.
  • Disabled keys can be re-enabled quickly if unexpected dependencies are discovered.
  • This provides a safe rollback mechanism during validation.

A recommended milestone is to ensure that all HPCS CRKs that were successfully migrated are in the Disabled state.

CRKs in the Disabled state can be re-enabled at any time and do not permanently block remediation.

Final milestones and decommissioning considerations

Deleting HPCS CRKs and Standard Keys is technically possible; however, deletion should be approached with caution:

  • Deleted keys can be recovered only for a limited period after deletion.
  • After the recovery window expires, deletion is permanent.
  • Recovery becomes increasingly difficult as time passes and workloads evolve.

For these reasons, you are not required to delete HPCS keys as part of migration.

A conservative and recommended approach is:

  1. Leave HPCS instances and CRKs disabled but intact.
  2. Do not re-enable or modify them after validation.

This approach minimizes risk while ensuring that cryptographic migration is completed successfully.

Your responsibilities

You are responsible for:

  • Verifying that all HPCS usage has stopped
  • Validating application and service behavior after migration

Proceed with decommissioning activities only when you are confident that HPCS is no longer required by any workload.