delete-dual-auth-keys.md

copyright	lastupdated	keywords	subcollection
years 2020, 2024	2024-07-01	delete keys with dual authorization, dual authorization, policy-based, key deletion	hs-crypto

{{site.data.keyword.attribute-definition-list}}

Deleting keys by using dual authorization

{: #delete-dual-auth-keys}

You can use {{site.data.keyword.cloud}} {{site.data.keyword.hscrypto}} to safely delete root keys or standard keys by using a dual authorization process. {: shortdesc}

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

{: #dual-auth-deletion-considerations}

Deleting a key that has a dual authorization policy requires an authorization from two users. With the {{site.data.keyword.hscrypto}} 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 {{site.data.keyword.hscrypto}} 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, {{site.data.keyword.hscrypto}} 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

{: #set-key-deletion-console} {: ui}

Step 1. Authorize deletion for a key

{: #set-dual-auth-key-gui}

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.

1. Log in to the UI{: external}.
2. Go to Menu > Resource list to view a list of your resources.
3. From your {{site.data.keyword.cloud_notm}} resource list, select your provisioned instance of {{site.data.keyword.hscrypto}}.
4. On the KMS keys page, use the Keys table to browse the keys in your service.
5. Click the Actions icon to open a list of options for the key that you want to delete.
6. From the options menu, click Schedule key deletion and review the key's associated resources.
7. Enter the name of the key that is to be deleted, and click Schedule key deletion.
8. Contact the second approver to complete the deletion of the key.

Step 2. Delete the key

{: #delete-dual-auth-key-gui}

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.

1. 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.

2. To delete the key, follow the instructions in Deleting keys with the UI.

{{site.data.keyword.hscrypto}} 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. {: note}

Authorize deletion for a key with the API

{: #set-key-deletion-api} {: api}

Step 1. Authorize deletion for a key

{: #set-dual-auth-key-api}

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

{: codeblock}

1. 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 {{site.data.keyword.hscrypto}} actions, check out Service access roles. {: note}

2. Copy the ID of the key that you want to set or authorize for deletion.

3. 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'
   

   {: codeblock}

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

   Variable	Description
   region	Required. The region abbreviation, such as us-south or eu-de, that represents the geographic area where your {{site.data.keyword.hscrypto}} 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 {{site.data.keyword.cloud_notm}} 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 {{site.data.keyword.hscrypto}} instance. For more information, see Retrieving an instance ID.
   {: caption="Table 1. Describes the variables needed to set a key for deletion" caption-side="bottom"}

   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. {: tip}

Step 2. Delete the key

{: #delete-dual-auth-key-api}

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

{{site.data.keyword.hscrypto}} 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. {: note}

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

{: #unset-key-deletion-api}

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

{: codeblock}

1. 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 {{site.data.keyword.hscrypto}} actions, check out Service access roles. {: note}

2. Copy the ID of the key that you want to unset or deauthorize for deletion.

3. 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'
   

   {: codeblock}

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

   Variable	Description
   region	Required. The region abbreviation, such as us-south or eu-de, that represents the geographic area where your {{site.data.keyword.hscrypto}} 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 {{site.data.keyword.cloud_notm}} 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 {{site.data.keyword.hscrypto}} instance. For more information, see Retrieving an instance ID.
   {: caption="Table 2. Describes the variables needed to unset a key for deletion" caption-side="bottom"}

   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

{: #delete-daul-auth-keys-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 {{site.data.keyword.hscrypto}} key management service API reference doc{: external}.