Disabling root keys

You can use IBM Cloud® Hyper Protect Crypto Services to disable or enable a root key and temporarily revoke access to the key's associated data on the cloud.

As an admin, you might need to temporarily disable a root key if you suspect a possible security exposure, compromise, or breach with your data. When you disable a root key, you suspend the encrypt and decrypt operations. After you confirm that a security risk is no longer active, you can restore access to your data by enabling the disabled root key.

If you are using a cloud service that is integrated with Hyper Protect Crypto Services, your data might not be accessible after you disable a root key. To determine whether an integrated service supports revoking access to data by disabling a Hyper Protect Crypto Services root key, see the service documentation.

When you disable a root key, the key moves to the Suspended state, and it can no longer be used to cryptographically protect data.

When you enable a root key that was previously disabled, the key moves from the Suspended to the Active key state. This action restores the key's encrypt and decrypt operations.

You must wait 30 seconds after you disable a root key before you are able to enable it again.

For an integrated Cloud Service that supports revoking access to a disabled root key, the service can take up to 4 hours to revoke or restore access to the associated data of the root key. After access to the associated data is revoked or restored, a corresponding enable event is displayed in the Activity Tracker web UI.

Disabling and enabling root keys with the UI

If you prefer to enable or disable your root keys by using a graphical interface, you can use the UI.

Disabling a root key

After you create or import your existing keys into the service, complete the following steps to disable a key:

Log in to the UI.
Go to Menu > Resource list to view a list of your resources.
From your IBM Cloud resource list, select your provisioned instance of Hyper Protect Crypto Services.
On the KMS keys page, use the Keys table to browse the keys in your service instance.
Click the Actions icon to open a list of options for the key that you want to disable.
From the options menu, click Disable key, enter the key name to confirm the key to be disabled, and click Disable key.

After the key is disabled, the State of the key is moved to Suspended in the Keys table.

Enabling a root key

If you want to re-enable a root key that is disabled, complete the following steps:

You must wait 30 seconds after you disable a root key before you are able to enable it again.

Log in to the UI.
Go to Menu > Resource list to view a list of your resources.
From your IBM Cloud resource list, select your provisioned instance of Hyper Protect Crypto Services.
On the KMS keys page, use the Keys table to browse the keys in your service.
Click the Actions icon to open a list of options for the key that you want to enable.
From the options menu, click Enable key.

After the key is enabled, the State of the key is transferred to Active in the Keys table.

Disabling and enabling root keys with the API

Disabling a root key

When you disable a root key, the key moves to the Suspended state, and it can no longer be used to encrypt data.

For an integrated cloud service that supports revoking access to a disabled root key, the service can take up to 4 hours to revoke access to the associated data of the root key. After access to the associated data is revoked, a corresponding disable event is displayed in the Activity Tracker web UI.

You can disable a root key that's in the Active key state by making a POST call to the following endpoint.

https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/actions/disable

Retrieve your authentication credentials to work with keys in the service.

To disable a root key, you must be assigned a Manager service access role for the instance or key. To learn how IAM roles map to Hyper Protect Crypto Services service actions, check out Service access roles.
Retrieve the key management service API endpoint URL.

You can get the API endpoint from your provisioned service instance dashboard through Overview > Connect > Key management endpoint URL. Or, you can dynamically retrieve the API endpoint URL with an API call. Select the public or private key manage endpoint URL based on your needs.
Retrieve the ID of the root key that you want to disable.

You can retrieve the ID for a specified key by making a list keys API request, or by viewing your keys in the UI.

Disable the root key and suspend the encrypt and decrypt operations by making the following API call.

curl -X POST \
  "https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/actions/disable" \
  -H "authorization: Bearer <IAM_token>" \
  -H "bluemix-instance: <instance_ID>" \
  -H "x-kms-key-ring: <key_ring_ID>"

Replace the variables in the example request according to the following table.

Table 1. Describes the variables needed to disable root keys with the Hyper Protect Crypto Services API
Variable	Description
`region`	Required. The region abbreviation, such as `us-south` or `eu-de`, that represents the geographic area where your Hyper Protect Crypto Services service instance resides. For more information, see Regional service endpoints.
`port`	Required. The port number of the API endpoint.
`key_ID`	Required. The unique identifier for the root key that you want to disable.
`IAM_token`	Required. Your IBM Cloud access token. Include the full contents of the `IAM` token, including the Bearer value, in the cURL request. For more information, see Retrieving an access token.
`instance_ID`	Required. The unique identifier that is assigned to your Hyper Protect Crypto Services service instance. For more information, see Retrieving an instance ID.
`key_ring_ID`	Optional. The unique identifier of the key ring that the key belongs to. If unspecified, Hyper Protect Crypto Services will search for the key in every key ring that is associated with the specified instance. Therefore, it is suggested to specify the key ring ID for a more optimized request. Note: The key ring ID of keys that are created without an `x-kms-key-ring` header is: default. For more information, see Managing key rings.

A successful disable request returns an HTTP 204 No Content response, which indicates that the root key was disabled for encrypt and decrypt operations.

Optional: Verify that the root key was disabled by retrieving details about the key.

curl -X GET \
  https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_id>/metadata \
  -H 'authorization: Bearer <IAM_token>' \
  -H 'bluemix-instance: <instance_ID>' \
  -H 'accept: application/vnd.ibm.kms.key+json'

Review the state field in the response body to verify that the key moved to the Suspended key state. The following JSON output shows the metadata details for a disabled root key.

The integer mapping for the Suspended key state is 2. Key States are based on NIST SP 800-57.

{
    "metadata": {
        "collectionType": "application/vnd.ibm.kms.key+json",
        "collectionTotal": 1
    },
    "resources": [
        {
            "type": "application/vnd.ibm.kms.key+json",
            "id": "02fd6835-6001-4482-a892-13bd2085f75d",
            "name": "...",
            "description": "...",
            "tags": [
                "..."
            ],
            "state": 2,
            "extractable": false,
            "crn": "crn:v1:bluemix:public:hs-crypto:us-south:a/f047b55a3362ac06afad8a3f2f5586ea:12e8c9c2-a162-472d-b7d6-8b9a86b815a6:key:02fd6835-6001-4482-a892-13bd2085f75d",
            "imported": true,
            "creationDate": "2020-03-10T20:41:27Z",
            "createdBy": "...",
            "algorithmType": "AES",
            "algorithmMetadata": {
                "bitLength": "128",
                "mode": "CBC_PAD"
            },
            "algorithmBitSize": 128,
            "algorithmMode": "CBC_PAD",
            "lastUpdateDate": "2020-03-16T20:41:27Z",
            "keyVersion": {
                "id": "30372f20-d9f1-40b3-b486-a709e1932c9c",
                "creationDate": "2020-03-12T03:37:32Z"
            },
            "dualAuthDelete": {
                "enabled": false
            },
            "deleted": false
        }
    ]
}

Enabling a disabled root key

When you enable a root key that was previously disabled, the key moves from the Suspended to the Active key state. This action restores the key's encrypt and decrypt operations.

For an integrated cloud service that supports revoking access to a disabled root key, the service can take up to 4 hours to restore access to the associated data of the root key. After access to the associated data is restored, a corresponding enable event is displayed in the Activity Tracker web UI.

You can enable a root key that's in the Suspended key state by making a POST call to the following endpoint.

https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/actions/enable

Retrieve your authentication credentials to work with keys in the service.

To enable a root key, you must be assigned a Manager service access role for the instance or key. To learn how IAM roles map to Hyper Protect Crypto Services service actions, check out Service access roles.
Retrieve the key management service API endpoint URL.

You can get the API endpoint from your provisioned service instance dashboard by clicking Manage > Key management endpoint URL, or you can dynamically retrieve the API endpoint URL with an API call. Select the public or private key manage endpoint URL based on your needs.
Retrieve the ID of the disabled root key that you want to enable.

You can retrieve the ID for a specified key by making a list keys API request, or by viewing your keys in the Hyper Protect Crypto Services dashboard.

Enable the root key and restore the encrypt and decrypt operations by making the following API call.

You must wait 30 seconds after you disable a root key before you are able to enable it again.

curl -X POST \
  "https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/actions/enable" \
  -H "authorization: Bearer <IAM_token>" \
  -H "bluemix-instance: <instance_ID>" \
  -H "x-kms-key-ring: <key_ring_ID>"

Replace the variables in the example request according to the following table.

Table 2. Describes the variables needed to enable root keys with the Hyper Protect Crypto Services API
Variable	Description
`region`	Required. The region abbreviation, such as `us-south` or `eu-de`, that represents the geographic area where your Hyper Protect Crypto Services service instance resides. For more information, see Regional service endpoints.
`port`	Required. The port number of the API endpoint.
`key_ID`	Required. The unique identifier for the root key that you want to enable.
`IAM_token`	Required. Your IBM Cloud access token. Include the full contents of the `IAM` token, including the Bearer value, in the cURL request. For more information, see Retrieving an access token.
`instance_ID`	Required. The unique identifier that is assigned to your Hyper Protect Crypto Services service instance. For more information, see Retrieving an instance ID.
`key_ring_ID`	Optional. The unique identifier of the key ring that the key belongs to. If unspecified, Hyper Protect Crypto Services will search for the key in every key ring that is associated with the specified instance. Therefore, it is suggested to specify the key ring ID for a more optimized request. Note: The key ring ID of keys that are created without an `x-kms-key-ring` header is: default. For more information, see Managing key rings.

A successful enable request returns an HTTP 204 No Content response, which indicates that the root key was reinstated for encrypt and decrypt operations.

Optional: Verify that the root key was enabled by retrieving details about the key.

curl -X GET \
  https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_id>/metadata \
  -H 'authorization: Bearer <IAM_token>' \
  -H 'bluemix-instance: <instance_ID>' \
  -H 'accept: application/vnd.ibm.kms.key+json'

Review the state field in the response body to verify that the root key moved to the Active key state. The following JSON output shows the metadata details for an active key.

The integer mapping for the Active key state is 1. Key States are based on NIST SP 800-57.

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.key+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "type": "application/vnd.ibm.kms.key+json",
      "id": "02fd6835-6001-4482-a892-13bd2085f75d",
      "name": "...",
      "description": "...",
      "tags": [
        "..."
      ],
      "state": 1,
      "extractable": false,
      "crn": "crn:v1:bluemix:public:hs-crypto:us-south:a/f047b55a3362ac06afad8a3f2f5586ea:12e8c9c2-a162-472d-b7d6-8b9a86b815a6:key:02fd6835-6001-4482-a892-13bd2085f75d",
      "imported": true,
      "creationDate": "2020-03-10T20:41:27Z",
      "createdBy": "...",
      "algorithmType": "AES",
      "algorithmMetadata": {
        "bitLength": "128",
        "mode": "CBC_PAD"
      },
      "algorithmBitSize": 128,
      "algorithmMode": "CBC_PAD",
      "lastUpdateDate": "2020-03-16T20:41:27Z",
      "keyVersion": {
        "id": "30372f20-d9f1-40b3-b486-a709e1932c9c",
        "creationDate": "2020-03-12T03:37:32Z"
      },
      "dualAuthDelete": {
        "enabled": false
      },
      "deleted": false
    }
  ]
}