Restoring keys

You can use IBM Cloud® Hyper Protect Crypto Services to restore a previously deleted key and access the associated data on the cloud.

When a key is deleted, it is moved to a Destroyed state. However, information about the key (such as the 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 deletion where the key still exists but can no longer be used to access the data that is encrypted by the key. This topic describes the process to restore a key and the limitations of the key restoration process.

This soft deletion 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 or access key data?	Can restore?
1–30 days	Destroyed	Yes	Yes
30–90 days	Destroyed	Yes	No
After 90 days	Purged (not a key state technically)	No	No

Because purged keys are inaccessible and destroyed, there is technically no Purged key state. However, it can be useful to think of Purged as being a state because nonexistence is part of the lifecycle of a key.

All root keys and standard keys, whether generated by Hyper Protect Crypto Services or imported by you, can be restored.

How do I know whether a key can be restored?

To see whether a destroyed key can be restored:

Navigate to your Hyper Protect Crypto Services instance in the UI.
In the navigation, make sure you are on the KMS keys page.
Find the key that you want to restore and make sure that the key is in a Destroyed state.
Check whether an Undo icon is displayed next to the Destroyed state. The icon indicates that the key is eligible to be restored. You can restore a key within 30 days after the deletion. The restoration expiration date is displayed when you hover over the icon.

Restoring a deleted key with the UI

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

Complete the following steps to restore the key:

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.
Select the key that you want to restore and click the Actions icon to open a list of options for the key.
From the options menu, click Restore key.
Click Restore key to confirm the action.

Restoring a deleted key with the API

Restore a key by making a POST call to the following endpoint.

https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/restore

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

To restore a key, you must be assigned a Manager access policy for the instance or key. To learn how IAM roles map to Hyper Protect Crypto Services service actions, check out Service access roles.
Retrieve the key management service API endpoint URL.

You can get the API endpoint from your provisioned service instance dashboard through Overview > Connect > Key management endpoint URL. Or, you can dynamically retrieve the API endpoint URL with an API call. Select the public or private key manage endpoint URL based on your needs.
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 API request, or by viewing your keys in the UI.

Run the following curl command to restore the key and regain access to the associated data. 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://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/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 the following table.

Table 1. Describes the variables needed to restore keys with the Hyper Protect Crypto Services API
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 service instance resides. For more information, see Regional service endpoints.
`port`	Required. The port number of the API endpoint.
`key_ID`	Required. The unique identifier 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, see Retrieving an access token.
`instance_ID`	Required. The unique identifier that is assigned to your Hyper Protect Crypto Services service instance. For more information, see Retrieving an instance ID.
`key_ring_ID`	Optional. The unique identifier of the key ring that the key belongs to. If unspecified, Hyper Protect Crypto Services will search for the key in every key ring that is associated with the specified instance. Therefore, it is suggested to specify the key ring ID for a more optimized request. \n \n Note: The key ring ID of keys that are created without an `x-kms-key-ring` header is `default`. For more information, see Managing key rings.

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.

Optional: Verify that the key was restored by retrieving details about the key.

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

Where the <key_id> is the ID 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 moved 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:hs-crypto: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
    }
  ]
}