Deleting keys using a single authorization

Deleting keys in the console

By default, Key Protect requires one authorization to delete a key. If you prefer to delete your encryption keys by using a graphical interface, you can use the IBM Cloud console.

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

1. Log in to the IBM Cloud console.

2. Go to Menu > Resource List to view a list of your resources.

3. From your IBM Cloud resource list, select your provisioned instance of Key Protect.

4. On the application details page, use the Keys table to browse the keys in your service.

5. Click the ⋯ icon to open a list of options for the key that you want to delete.

6. From the options menu, click Delete key and confirm the key deletion in the next screen by ensuring the key has no associated resources. Note that you will not be able to delete the key if it is protecting a registered IBM Cloud resource that's non-erasable due to a retention policy.

After you delete a key, the key transitions to the Destroyed state. Any data encrypted by keys in this state is no longer accessible. Metadata that is associated with the key, such as the key's deletion date, is kept in the Key Protect database. Destroyed keys can be recovered after up to 30 days or their expiration date, whichever is sooner. After 30 days, keys can no longer be recovered, and become eligible to be purged after 90 days, a process that shreds the key material and makes its metadata inaccessible.

If a user has the KeyPurge attribute, they can purge a key after four hours. Check out Purging keys in the console for more information.

Purging keys in the console

If it is important to your use case to purge a key sooner than 90 days (the soonest a key can be purged after a normal deletion), the key can be purged after four hours if a user has the KeyPurge role.

Because a purged key has its key material permanently shredded and metadata inaccessible, a purged key cannot be restored. It is therefore even more important to ensure that the key has no vital associated resources.

To purge a key:

1. Follow the instructions to Delete a key.

2. After waiting at least four hours, once again navigate to the key and click the ⋯ icon.

3. From the options, select Purge from the options below and confirm the key deletion in the next screen by ensuring the key has no associated resources and that you have the necessary KeyPurge user attribute.

Deleting keys with the API

If a user has the KeyPurge role, they can purge a key after four hours.

By default, Key Protect requires one authorization to delete a key. You can delete a key and its contents by making a DELETE call to the following endpoint.

https://<region>.kms.cloud.ibm.com/api/v2/keys/<keyID_or_alias>

This action won't succeed if the key is actively protecting one or more cloud resources. You can review the resources that are associated with the key, or use the force parameter at query time to delete the key.

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

2. Retrieve the ID of the key that you want to delete.

   You can find the ID for a key in your Key Protect instance by retrieving a list of your keys, or by accessing the Key Protect dashboard.

3. Run the following curl command to delete the key and its contents.

   $ curl -X DELETE \
       "https://<region>.kms.cloud.ibm.com/api/v2/keys/<keyID_or_alias>" \
       -H "authorization: Bearer <IAM_token>" \
       -H "bluemix-instance: <instance_ID>" \
       -H "x-kms-key-ring: <key_ring_ID>" \
       -H "prefer: <return_preference>"
   

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

If the return_preference variable is set to return=representation, the details of the DELETE request are returned in the response entity-body.

After you delete a key, it transitions to the Deactivated key state. After 24 hours, if a key is not reinstated, the key transitions to the Destroyed state. Deleted keys are recoverable for up to 30 days or until their expiration date, after which the key contents are shredded and its metadata becomes inaccessible.

The following JSON object shows an example returned value.

{
"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": "test-root-key",
            "aliases": [
                "alias-1",
                "alias-2"
            ],
            "state": 5,
            "extractable": false,
            "crn": "crn:v1:bluemix:public:kms:us-south:a/f047b55a3362ac06afad8a3f2f5586ea:12e8c9c2-a162-472d-b7d6-8b9a86b815a6:key:02fd6835-6001-4482-a892-13bd2085f75d",
            "imported": false,
            "creationDate": "2020-03-10T20:41:27Z",
            "createdBy": "...",
            "algorithmType": "Deprecated",
            "algorithmMetadata": {
                "bitLength": "256",
                "mode": "Deprecated"
            },
            "algorithmBitSize": 256,
            "algorithmMode": "Deprecated",
            "lastUpdateDate": "2020-03-16T20:41:27Z",
            "dualAuthDelete": {
                "enabled": false
            },
            "deleted": true,
            "deletionDate": "2020-03-16T21:46:53Z",
            "deletedBy": "..."
        }
    ]
}

For a detailed description of the available parameters, see the Key Protect REST API reference doc.

https://<region>.kms.cloud.ibm.com/api/v2/keys/<keyID_or_alias>?force=true

{
    "metadata": {
        "collectionType": "application/vnd.ibm.kms.key+json",
        "collectionTotal": 1
    },
    "resources": [
        {
            "id": "2291e4ae-a14c-4af9-88f0-27c0cb2739e2",
            "type": "application/vnd.ibm.kms.key+json",
            "aliases": [
                "alias-1",
                "alias-2"
            ],
            "name": "test-root-key",
            "description": "...",
            "state": 5,
            "expirationDate": "2020-03-15T20:41:27Z",
            "crn": "crn:v1:bluemix:public:kms:us-south:a/f047b55a3362ac06afad8a3f2f5586ea:30372f20-d9f1-40b3-b486-a709e1932c9c:key:2291e4ae-a14c-4af9-88f0-27c0cb2739e2",
            "deleted": true,
            "algorithmType": "AES",
            "createdBy": "...",
            "deletedBy": "...",
            "creationDate": "2020-03-10T20:41:27Z",
            "deletionDate": "2020-03-16T21:46:53Z",
            "lastUpdateDate": "2020-03-16T20:41:27Z",
            "extractable": true
        }
    ]
}

Key purge

When you delete a key, you immediately deactivate its key material and move it to a backstore in the Key Protect service. Four hours after a key is deleted, the key becomes available to be manually purged. Thirty days after a key is deleted, the key becomes non-restorable and the key material is destroyed. After a key has been deleted for 90 days, if not manually purged, the key becomes eligible to be automatically purged and all its associated data will be permanently removed, or "hard deleted", from the Key Protect service.

For more information about deleting and purging keys, check out About deleting and purging keys.

The following table lists which APIs you can use to retrieve data related to a deleted key.