Restoring keys

When a key is deleted, it is moved to a "destroyed" state. However, information about the key (such as its metadata) can still be viewed and you have 30 days to restore the key to an active state. For this reason, a key deletion is considered a "soft delete" in that the key still exists but can no longer be used to access the data it has encrypted. This topic describes the process to restore a key and the limitations of the key restoration process.

As part of a testing and development process, it is normal to regularly create and delete keys. These keys are not gone forever; rather they are "soft deleted" and moved to a destroyed state, meaning that the key cannot be used as part of any key actions such as encrypting or decrypting data. The key data can only be looked at, and, if the key was deleted in error, it might be possible to restore the key to an active state.

All keys, whether created in Key Protect or imported, and whether a root or standard key, can be restored.

This intermediate period, in which a key has been deleted but can still be restored, lasts for 30 days. Between 30 days and 90 days, the key data can still be accessed, but the key can no longer be restored. After 90 days, the key becomes eligible to be automatically purged, which can occur at any time after 90 days. Purged keys, unlike destroyed keys, are gone forever.

Table 1. Ties key states to the time from a key's deletion to what actions are possible with the key.
Time from key deletion	Name of key state	Can view/access key data?	Can restore?
One-30 days	Destroyed	Yes	Yes
30-90 days	Destroyed	Yes	No
After 90 days	Purged`*`	No	No

*Note: because purged keys are completely inaccessible and "destroyed" in the common usage of the word, there is technically no "purged" key state. Purged keys are simply gone and therefore don't have a "state" one way or another. However, it can be useful to think of "purged" as being a state because nonexistence is part of the lifecycle of a key. If you need to purge a key sooner than 90 days, it requires a special key purging role. For more information, check out Deleting keys.

For more information about key states, check out Monitoring the lifecycle of encryption keys.

Because Key Protect does not allow instances that have keys in them to be deleted, it is required that any keys in an instance be deleted before the instance itself can be deleted. However, because of the "soft" deletion of keys, it is possible that a user might delete a key and then soon after delete an instance. This deletion of the instance also permanently deletes the key, even if the deletion of the key is recent enough to have made it eligible to be restored. For this reason, Key Protect allows an instance to be reclaimed for a short time after it has been deleted. To see if your instance can be reclaimed, check out Listing reclaimed resources by using the CLI. For the commands on reclaiming the resource (the instance in this case), check out Restoring a resource by using the CLI.

How do I know whether a key can be restored?

To see whether a destroyed key can be restored:

Navigate to your Key Protect instance in the IBM Cloud console.
In the left navigation, make sure you are on the Keys screen.
Find the key you want to restore. Note: only keys in a Destroyed state can be restored.
Under the Last updated column, note the date. Then refer to Table 1, which can be found above. If the key has been deleted within the last 30 days, it can be restored. If it has been more then 30 days, you will not be able to restore the key. If you attempt to restore a key that is no longer eligible to be restored, you will receive an error when trying to restore the key.

Restoring a deleted key with the console

If you prefer to restore your key by using a graphical interface, you can use the IBM Cloud console.

After you import your existing keys into the service and delete a key, complete the following steps to restore 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.
Click Keys to open the keys panel and find the key in the destroyed state you want to restore. One way to achieve this is to click the Key states drop-down list and select the Destroyed state. This will limit the results to only keys that have been deleted.
Click the ⋯ icon to open a list of options for the key that you want to restore. Note that if the key has just been moved to a Destroyed state you must wait 30 seconds before attempting to restore it.
Click the Restore Key button to open the restore side panel.
Click Restore Key button.
Confirm the key was restored in the updated Keys table.

Restoring a deleted key with the API

Restore a previously imported key by making a POST call to the following endpoint:

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

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

To restore a key, you must have the Manager 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 key that you want to restore.

You can retrieve the ID for a specified key by making a list keys request request, or by viewing your keys in the Key Protect dashboard. For more information, check out Viewing a list of keys.
Run the following curl command to restore the key and regain access to its associated data. Note that you must wait 30 seconds after deleting a key before you are able to restore it.

You cannot restore a key that has an expiration date that is current or in the past.
```
$ curl -X POST \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys/<keyID_or_alias>/restore" \
    -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 Table 2.

Table 2. Describes the variables that are needed to restore 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, check out Regional service endpoints.
keyID_or_alias	Required. The unique identifier or alias for the key that you want to restore.
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, check out Retrieving an access token.
instance_ID	Required. The unique identifier that is assigned to your Key Protect service instance. For more information, check out 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 therefore 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, check out Grouping keys.

A successful restore request returns an HTTP `201 Created` response, which indicates that the key was restored to the _Active_ key state and is now available for encrypt and decrypt operations. All attributes and policies that were previously associated with the key are also restored.

You will have access to data associated with the key as soon as the key is restored.
{: note}

Optional: Verify key restoration

You can verify that the key has been restored by getting details about the key by issuing:

$ 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 Active key state. The following JSON output shows example metadata details for an Active key.

{
    "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": "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
        }
    ]
}

The integer mapping for the Active key state is 1.