Managing data encryption

View root key registrations

Block Storage for VPC volumes, snapshots, File Storage for VPC shares, and custom images that are encrypted with your key are registered against the root key in the key management service (Key Protect or Hyper Protect Crypto Services). By viewing the registration, you can map your resources to their associated encryption keys. You can quickly see which resources are protected by a root key. You can also assess the risk that is involved in disabling or deleting a key by viewing which keys are actively protecting data.

For more information, see the following topics.

• Key Protect - Viewing associations between root keys and encrypted IBM Cloud resources
• Hyper Protect Crypto Services - Viewing associations between root keys and encrypted IBM Cloud resources

User actions that impact root key states and resource status

Root keys move to various states as a result of the actions that you take, and different root key states impact resources differently. The following table describes what happens to a resource when you disable, enable, delete, and restore a root key.

For more information about root key states from a KMS perspective, see the following topics.

• Key Protect - Key states and transitions
• Hyper Protect Crypto Services - Key states and transitions

Disable root keys

When you disable a root key, you suspend its encryption and decryption operations. Disabling a root key in your KMS places the key in a suspended state, which makes it unusable for protecting a resource. The resources become unusable for normal operations. Temporarily disabling a root key is good practice if you suspect possible security exposure, compromise, or data breach. You can enable a disabled root key when the security threat is no longer active.

When you disable a root key, workloads continue to run in virtual server instances, and boot volumes remain encrypted. Data volumes remain attached. File share data is encrypted. However, if you stop the virtual server instance, it can't be restarted. You also can't provision a resource by using a disabled key. Before you disable a key, it's best to verify which resources are being protected by it.

To see which root keys are disabled, look in the UI list of resources. The status of volume and snapshot resources are unusable. File shares in a stable state remain so. The UI tooltip displays "key suspended" for the resource. In the API response, you can see an encryption_key_disabled reason code.

You can enable a root key that's in a suspended state, which returns the key to an active state. You can also delete a suspended key or restore the deleted key if necessary.

For more information about disabling root keys, the following topics.

• Key Protect - Disabling root keys
• Hyper Protect Crypto Services - Disabling root keys

Deleting root keys

When you delete a root key, the key is no longer available to decrypt passphrases that are used to protect your resources. Deleting a root key places it in a destroyed or deleted state in the KMS. Volume, snapshot, and image resources that are protected by the deleted root key have an unusable status and can't be used for normal operations. File Storage for VPC shares show a suspended status. The storage system is offline, and data cannot be accessed.

Your data still exists. You have a 30-day grace period to restore the deleted key. Otherwise, your encrypted resources become inaccessible. After 30 days, your root key can't be restored, and your resources are unrecoverable.

By default, the KMS prevents you from deleting a root key that's actively protecting a resource. You can force delete a root key in Key Protect and Hyper Protect Crypto Services. When you force delete a root key, the following actions happen automatically:

• If the deleted root key is protecting boot volumes, the associated virtual server instance is stopped.
• If the deleted root key is protecting data volumes, the associated virtual server instance is stopped.
• If the deleted root key is protecting file shares, the file share is suspended.
• Deleting a root key purges usage of the key for all resources in the VPC.
• Events are logged in the Activity Tracker.

To force the deletion of a root key in Hyper Protect Crypto Services, use the API. Hyper Protect Crypto Services requires that you delete all resources before you delete a root key that is protecting those resources. If you can't delete the key, see troubleshooting key management service.

Block Storage for VPC volumes, snapshots, and custom images with a deleted root key appear in the list of resources with an unusable status. File Storage for VPC shares show a suspended status. The API reason code is encryption_key_deleted.

Deletion of the root key results in the following conditions.

• All instances with an unusable boot volume do not restart.
• You can't attach unusable data volumes to an instance.
• You can't restore a volume from a snapshot.
• You can't access a file share.
• You can't provision instances from unusable images.
• Billing continues for unusable resources until you delete them.

Before you force delete a root key, it's best to review all resources that are associated with that root key. Consider temporarily disabling the key instead of deleting it to suspend the use of that root key. Root keys can be restored within 30 days, but only if they are imported root keys, not KMS generated.

For more information about deleting root keys, see the following topics.

• Key Protect - Deleting keys
• Hyper Protect Crypto Services - Deleting keys

For more information about how to see the list of deleted root keys and possibly restore imported root keys, see Restoring deleted root keys.

Restoring deleted root keys

Restoring an imported root key returns the key to an active state, and reestablishes access to the key. (Root keys that were generated by the KMS can't be restored.) You can restore access to all resources that were previously protected by the root key. You can resume regular actions, such as restarting an instance and attaching data volumes.

To see a list of deleted root keys for a KMS instance, you can filter by key state. For example, to filter a list of deleted root keys in a Key Protect instance in the UI:

1. Go to the IBM Cloud console > Resource List > Security,
2. Locate, and click the KMS instance.
3. On the Keys page, the list of root keys that are stored in this instance is displayed.
4. Click the Filter icon to see more information.
5. Under States, click the down arrow to display all key states.
6. Select Deleted.

The list of root keys is refreshed, and shows all root keys in a deleted key state. The most recently deleted key is at the first of the list.

To restore a root key:

1. Click Actions().
2. Select the Restore key.

To complete the key restoration process, you need the key ID that was associated with the key and the original key material that you imported.

You also need to create volume attachments for your data volumes. The volume attachment IDs are different than before you deleted the root key.

For more information about restoring root keys in a KMS instance, see the following topics.

• Key Protect - Restoring keys
• Hyper Protect Crypto Services - Restoring keys

Removing service authorization to a root key

You can make your data inaccessible but retain it on the cloud by removing IAM authorization to use that root key.

When you authorize use of your root key, you grant permission for IBM to use the key to encrypt your resource. Authorization is done at the key management service level through IAM, when you authorize service between your service (for example, Cloud Block Storage) and the key management service.

You can remove any authorization between services in your account when you have the Administrator role on the target service (in this case, the key management service). If you remove an access policy that was created by the source service for its dependent services, the source service is unable to complete the workflow or access the target service.

Because the root keys are under your control, you don't need to contact IBM to remove authorization.

Do not remove IAM authorization between Cloud Block Storage and the KMS instance, and then delete a Block Storage volume, snapshot, or image resource. Such action causes the root key in the KMS instance to remain registered with the deleted resource. You must delete all BYOK volumes, snapshots, or images before you remove the IAM authorization.

To make your data inaccessible, but retain it on the IBM Cloud:

1. Remove IAM authorization from the source Cloud Block Storage service to your target key management service instance.
2. Stop all virtual server instances with attached encrypted volumes that are secured by that root key.

You can also disable a root key, which suspends the key and temporarily revokes access to it.

Activity tracking events for key rotation

When you initiate an activity in the KMS to rotate and manage your root keys, Activity tracking events are generated. These events are particular to Key Protect, but similar events are generated for Hyper Protect Crypto Services, too.

• When you list keys, a kms.secrets.list event is generated.
• When you rotate a root key, a kms.secrets.rotate event is generated.
• When you manually rewrap a data encryption key (DEK) with new key material, a kms.secrets.rewrap event is generated.
• If you initially imported a root key by using an import token and use the import token to rotate a key, a kms.secrets.ack-rotate event is generated.
• When you retrieve a key, the requestData.keyType field includes the type of key that was retrieved.
• The responseData.keyState field includes the integer that correlates to the state of the key. The integers correlate with these key state values: Pre-activation = 0, Active = 1, Suspended = 2, Deactivated = 3, and Destroyed = 5. For more information about key states, see Key states and transitions.
• When you authorize the deletion of a key, a kms.secrets.setkeyfordeletion event is generated. The responseData.keyState field includes the integer that correlates to the deleted state (5).
• The responseData.totalResources field includes the total number of key versions that are associated with the key.
• The responseData.eventAckData.newKeyVersionId field includes the unique identifier of the latest key version.

For more information about key rotation events that indicate a successful rotation, see these key rotation events. For more information about all Activity tracking events in Key Protect, see IBM Cloud Activity Tracker events.

Example key rotation event

The following JSON example shows a kms.secrets.rotate event when a root key is rotated.

{
   "eventTime":"2020-06-22T15:36:16.7+0000",
   "outcome":"success",
   "message":"Key Protect: rotate secret my-secret-key1",
   "action":"kms.secrets.rotate",
   "initiator":{
      "id":"MYid-111100P9W2",
      "name":"john.doe@mycompany.com",
      "typeURI":"service/security/account/user",
      "credential":{
         "type":"token"
      },
      "host":{
         "address": "192.0.2.0"
      }
   },
   "target":{
      "id":"crn:v1:bluemix:public:kms:us-south:a/a12333e9bd28461a8c92385628efac9f:fd692647-43d0-4699-9f83-f39a54b1327b:key:76c2c9cb-9095-5a24-811b-0ef4b24ac4d5",
      "name":"my-secret-key1",
      "typeURI":"kms/secrets"
   },
   "observer":{
      "name":"ActivityTracker"
   },
   "reason":{
      "reasonCode":204,
      "reasonType":"No Content"
   },
   "severity":"warning",
   "requestData":{
      "requestURI":"/api/v2/keys/76c2c9cb-9095-5a24-811b-0ef4b24ac4d5?action=rotate\u0026include_resource=true",
      "instanceId":"fd692647-43d0-4699-9f83-f39a54b1327b"
   },
   "dataEvent":true,
   "saveServiceCopy":true,
   "correlationId":"ef56e7ed-abf5-4da4-bbf1-ac0d381891fd",
   "logSourceCRN":"crn:v1:bluemix:public:kms:us-south:a/a12333e9bd28461a8c92385628efac9f:fd692647-43d0-4699-9f83-f39a54b1327b::"
}

This event shows the updated volume after a successful key rotation:

{
  "payload": {
    "id": "496cbc9b-3758-4eff-bc7d-f71a51be0e1d",
    "eventTime": "2020-06-10T17:27:24.81+0000",
    "action": "is.volume.volume.update",
    "outcome": "success",
    "message": "Block Storage for VPC: update volume my-encrypted-volume1",
    "initiator": {
      "id": "keyreact",
      "typeURI": "service/security/account/user",
      "name": "",
      "host": {
        "address": "192.0.2.0/24172",
        "agent": "grpc-go/1.22.1"
      },
      "credential": {
        "type": "token"
      }
    },
    "target": {
      "id": "crn:v1:bluemix:public:is:us-south-1:a/82a90f2e-39e1-4a18-a8dc-6ebc17b61d7f::volume:cc6d2924-3cd2-459c-bb5e-9e84287fb530",
      "typeURI": "is.volume/volume",
      "name": "my-at-rewrap-encrypted-volume1",
      "host": {}
    },
    "observer": {
      "name": "ActivityTracker"
    },
    "reason": {
      "reasonCode": 200,
      "reasonType": "OK"
    },
    "severity": "normal",
    "requestData": {
      "account_id": "82a90f2e-39e1-4a18-a8dc-6ebc17b61d7f",
      "action": "is.volume.volume.update",
      "crn": "crn:v1:bluemix:public:is:us-south-1:a/82a90f2e-39e1-4a18-a8dc-6ebc17b61d7f::volume:cc6d2924-3cd2-459c-bb5e-9e84287fb530",
      "generation": "gc",
      "id": "cc6d2924-3cd2-459c-bb5e-9e84287fb530",
      "requestPath": "",
      "resourceGroupID": "696cb88e9039453f86f0802c92446a60"
    },
    "correlationId": "496cbc9b-3758-4eff-bc7d-f71a51be0e1d"
  },
  "logSourceCRN": "crn:v1:bluemix:public:is:us-south-1:a/82a90f2e-39e1-4a18-a8dc-6ebc17b61d7f::volume:cc6d2924-3cd2-459c-bb5e-9e84287fb530",
  "saveServiceCopy": true
}

Activity tracking events for key suspension and deletion

When you initiate activity in the KMS to disable or delete a root key, specific Activity tracking events are generated. These events are particular to Key Protect, but similar events are generated for Hyper Protect Crypto Services.

• When you disable a key (key state changes from active to suspended), a kms.secrets.disable event is generated.
• When you enable a disabled key (key state changes from suspended to active), a kms.secrets.enable event is generated.
• When you delete a key (key state changes to destroyed), a kms.secrets.delete event is generated.
• When you restore a deleted key (key state changes from destroyed to active), a kms.secrets.restore event is generated.

For more information, see all Activity Tracker key events.