Deleting keys by using dual authorization

You can use IBM Cloud® Hyper Protect Crypto Services to safely delete root keys or standard keys by using a dual authorization process.

Before you delete keys, make sure you understand the concept of deleting and purging keys and review the considerations.

Considerations for deleting a key using dual authorization

Deleting a key that has a dual authorization policy requires an authorization from two users. With the Hyper Protect Crypto Services key management service API, you can provide the first authorization by setting the key for deletion. Then, a different user provides a second authorization by using the UI or key management service API to delete the key.

Before you delete a key by using dual authorization:

Determine who can authorize deletion of your Hyper Protect Crypto Services resources. To use dual authorization, be sure to identify a user who can set the key for deletion, and another user who can delete the key. Users with a Writer or Manager access policy can set keys for deletion. Users with a Manager access policy can delete keys.
Plan to delete the key within a 7-day waiting period. When the first user authorizes a key for deletion, Hyper Protect Crypto Services sets a 7-day waiting period on the key. During this period, the key remains in the Active state and all key operations are allowed on the key. To complete the deletion, the second user with a Manager access policy can use the UI or API to delete the key.
The key and its associated data become inaccessible 90 days after the key is deleted. When you delete a key, the key can be restored within 30 days after the deletion. You are able to retrieve associated data such as key metadata, registrations, and policies for up to 90 days. After 90 days, the key becomes eligible to be automatically purged and its associated data will be permanently removed from your instance.

Authorize deletion for a key with the UI

Step 1. Authorize deletion for a key

After you enable dual authorization for an instance or for a key, you can provide the first authorization to delete a key by using the UI.

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 delete.
From the options menu, click Schedule key deletion and review the key's associated resources.
Enter the name of the key that is to be deleted, and click Schedule key deletion.
Contact the second approver to complete the deletion of the key.

Step 2. Delete the key

To delete the key, the second approver must have Manager access policy for the instance or key in order to authorize the key for deletion.

In the Keys table of the KMS keys page, you can find keys that are authorized for deletion with the following indicators:
- The Set for deletion column has a value of True. The authorization expiration time is displayed in the Deletion expiration column.
- A Clock icon is displayed in the State column. Hover over the icon to view the deletion expiration date.
To delete the key, follow the instructions in Deleting keys with the UI.

Hyper Protect Crypto Services sets a 7-day waiting period that starts after you provide the first authorization to delete the key. During this 7-day period, the key remains in the Active state and all key operations are allowed on the key. If no action is taken by the second user and the 7-day period expires, you must restart the dual authorization process to delete the key.

Authorize deletion for a key with the API

Step 1. Authorize deletion for a key

After you enable dual authorization for an instance or for a key, you can provide the first authorization to delete a key by making a POST call to the following endpoint.

https://<instance_ID>.api.<region>.hs-crypto.appdomain.cloud/api/v2/keys/<key_ID>/actions/setKeyForDeletion

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

To set a key for deletion, you must be assigned a Manager or Writer access policy for the instance or key. To learn how IAM roles map to Hyper Protect Crypto Services actions, check out Service access roles.
Copy the ID of the key that you want to set or authorize for deletion.

Provide the first authorization to delete the key.

curl -X POST \
  'https://<instance_ID>.api.<region>.hs-crypto.appdomain.cloud/api/v2/keys/<key_ID>/actions/setKeyForDeletion' \
  -H 'accept: application/vnd.ibm.kms.key_action+json' \
  -H 'authorization: Bearer <IAM_token>' \
  -H 'bluemix-instance: <instance_ID>' \
  -H 'content-type: application/vnd.ibm.kms.key_action+json'

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

Table 1. Describes the variables needed to set a key for deletion
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 instance resides. For more information, see Regional service endpoints.
`key_ID`	Required. The unique identifier for the root key that you want to delete.
`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 instance. For more information, see Retrieving an instance ID.

A successful request returns an HTTP 204 No Content response, which indicates that your key was authorized for deletion. Another user with a Manager access policy can now delete the key by using the UI or key management service API.

If you need to prevent the deletion of a key that is already authorized for deletion, you can remove the existing authorization by calling POST /api/v2/keys/<key_ID>/actions/unsetKeyForDeletion.

Step 2. Delete the key

After you set a key for deletion, a second user with a Manager access policy can safely delete the key.

To delete a key and the contents, make a DELETE call to the service endpoint by following instructions in Deleting keys with the API.

Removing an existing authorization

If you need to cancel an authorization for a key before the 7-day waiting period expires, you can remove the existing authorization by making a POST call to the following endpoint.

https://<instance_ID>.api.<region>.hs-crypto.appdomain.cloud/api/v2/keys/<key_ID>/actions/unsetKeyForDeletion

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

To remove an authorization to delete a key, you must be assigned a Manager or Writer access policy for the instance or key. To learn how IAM roles map to Hyper Protect Crypto Services actions, check out Service access roles.
Copy the ID of the key that you want to unset or deauthorize for deletion.

Remove an existing authorization to delete the key.

curl -X POST \
  'https://<instance_ID>.api.<region>.hs-crypto.appdomain.cloud/api/v2/keys/<key_ID>/actions/setKeyForDeletion' \
  -H 'accept: application/vnd.ibm.kms.key_action+json' \
  -H 'authorization: Bearer <IAM_token>' \
  -H 'bluemix-instance: <instance_ID>' \
  -H 'content-type: application/vnd.ibm.kms.key_action+json'

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

Table 2. Describes the variables needed to unset a key for deletion
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 instance resides. For more information, see Regional service endpoints.
`key_ID`	Required. The unique identifier for the root key that you want to delete.
`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 instance. For more information, see Retrieving an instance ID.

A successful request returns an HTTP 204 No Content response, which indicates that your key is no longer authorized for deletion. If you need to restart the dual authorization process, you can issue another authorization to set the key for deletion.

What's next

To restore a previously deleted key, check out Restoring keys.
To create another root key, check out Creating root keys.
To delete the service instance, check out Deleting service instances
To find out more about programmatically managing your keys, check out the Hyper Protect Crypto Services key management service API reference doc.