Disabling and enabling root keys

You can use IBM® Key Protect for IBM Cloud® 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 its encrypt and decrypt operations. After confirming 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 Key Protect, your data might not be accessible after disabling a root key. To determine whether an integrated service supports revoking access to data by disabling a Key Protect root key, refer to its service documentation.

Disabling or enabling a root key

Disabling a root key

When you disable a root key that was previously enabled, the key transitions from the Active to the Suspended key state. This action mean the key can no longer be used to cryptographically protect data.

If you're using an integrated Cloud Service that supports revoking access to a disabled root key, the service may take up to a maximum of 4 hours before access to the root key's associated data is revoked.

After access to the associated data is revoked, a corresponding disable event is displayed in the IBM Cloud® Activity Tracker web UI. The disable event indicates the key has been revoked (and is now disabled) and the key can not be used for encrypt and decrypt operations.

Enabling a root key

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

If you're using an integrated Cloud Service that supports restoring access to a disabled root key, the service may take up to a maximum of 4 hours before access to the root key's associated data is restored.

After access to the associated data is restored, a corresponding enable event is displayed in the IBM Cloud Activity Tracker web UI. The enable event indicates the key has been restored (and is now enabled) and the key can be used for encrypt and decrypt operations.

Disabling and enabling root keys in the console

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

Disabling a root key in the console

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

Log in to the IBM Cloud console.
Go to Menu > Resource List to view a list of your resources.
From your IBM Cloud resource list, select your provisioned instance of Key Protect.
On the application details page, use the Keys table to browse the keys in your Key Protect instance.
Click the ⋯ icon to open a list of options for the key that you want to disable.
From the options menu, click Disable key and confirm the key was disabled in the updated Keys table.

Enabling a root key in the console

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

Log in to the IBM Cloud console.
Go to Menu > Resource List to view a list of your resources.
From your IBM Cloud resource list, select your provisioned instance of Key Protect.
On the application details page, use the Keys table to browse the keys in your service.
Click the ⋯ icon to open a list of options for the key that you want to enable.
From the options menu, click Enable key and confirm the key was enabled in the updated Keys table.

Keys cannot be enabled immediately after being disabled. If a key was disabled in error, wait at least 30 seconds before attempting to re-enable it.

Disabling and enabling root keys with the API

Disabling a root key with the API

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

https://<region>.kms.cloud.ibm.com/api/v2/keys/<keyID_or_alias>/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 Key Protect service actions, check out Service access roles.
Retrieve the ID of the root key that you want to disable.

You can retrieve the ID for a specified key by making a GET /v2/keys request, or by viewing your keys in the Key Protect dashboard.

Run the following curl command to disable the root key and suspend its encrypt and decrypt operations.

$ curl -X POST \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys/<keyID_or_alias>/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.

Describes the variables that are needed to disable root keys with the Key Protect API.
Variable	Description
region	**Required. The region abbreviation, such as `us-south` or `eu-gb`, that represents the geographic area where your Key Protect instance resides. For more information, see Regional service endpoints.
keyID_or_alias	Required. The unique identifier or alias 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 Key Protect service instance. For more information, see Retrieving an instance ID.
key_ring_ID	Optional. The unique identifier of the key ring that the key is a part of. If unspecified, Key Protect will search for the key in every key ring associated with the specified instance. It is recommended 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 Grouping keys.

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 key disablement

You can verify that a key has been disabled by issuing a get key metadata request:

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

Where the <keyID_or_alias> is the ID or alias of the key, the <instance_ID> is the name of your instance, and your <IAM_token> is your IAM token.

Review the state field in the response body to verify that the key transitioned 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:kms: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": "Deprecated",
            "algorithmMetadata": {
                "bitLength": "128",
                "mode": "Deprecated"
            },
            "algorithmBitSize": 128,
            "algorithmMode": "Deprecated",
            "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 with the API

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

https://<region>.kms.cloud.ibm.com/api/v2/keys/<keyID_or_alias>/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 Key Protect service actions, check out Service access roles.
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 GET /v2/keys request, or by viewing your keys in the Key Protect dashboard.

Run the following curl command to enable the root key and restore its encrypt and decrypt operations.

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

$ curl -X POST \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys/<keyID_or_alias>/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.

Describes the variables that are needed to enable root keys with the Key Protect API.
Variable	Description
region	Required. The region abbreviation, such as `us-south` or `eu-gb`, that represents the geographic area where your Key Protect instance resides. For more information, see Regional service endpoints.
keyID_or_alias	Required. The unique identifier or alias 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 Key Protect service instance. For more information, see Retrieving an instance ID.
key_ring_ID	Optional. The unique identifier of the key ring that the key is a part of. If unspecified, Key Protect will search for the key in every key ring associated with the specified instance. It is recommended 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 Grouping keys.

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 key enablement

You can verify that a key has been enabled by issuing a get key metadata request:

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

Where the <keyID_or_alias> is the ID or alias of the key, the <instance_ID> is the name of your instance, and your <IAM_token> is your IAM token.

Review the state field in the response body to verify that the root key transitioned 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:kms: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
        }
    ]
}