Setting dual authorization policies for keys

You can use IBM Cloud® Hyper Protect Crypto Services to set dual authorization policies for individual root keys or standard keys.

Dual authorization is an extra policy that helps to prevent accidental or malicious deletion of encryption keys in your Hyper Protect Crypto Services instance. When you enable this policy at the key level, Hyper Protect Crypto Services requires an authorization from two users to delete an encryption key.

After you enable dual authorization at the key level, the policy that is associated with the key can no longer be changed to allow a single authorization to delete the encryption key.

To enable dual authorization settings at the instance level, check out Managing service settings.

Managing dual authorization policies with the key management service API

Consider the following items before you enable dual authorization for a key:

Determine whether a dual authorization policy is required for the key. As a security admin, assess the sensitivity of your workload to determine whether a key requires a dual authorization policy based on your requirements. After you enable dual authorization for a key, the policy can no longer be changed to allow a single authorization to delete the key.
Determine who can authorize deletion of your Hyper Protect Crypto Services resources. After you create a dual authorization policy for a key, the key will require an action from two users before it can be deleted. Be sure to identify two distinct users with the appropriate levels of access to the instance or key.

To learn how to delete a key that has a dual authorization policy, see Deleting keys using dual authorization.

Viewing a dual authorization policy for a key

For a high-level view, you can retrieve the dual authorization policy for a single key by making a GET call to the following endpoint.

https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/policies?policy=dualAuthDelete

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

To work with dual authorization policies, you must be assigned a Manager access policy for the instance or key. To learn how IAM roles map to Hyper Protect Crypto Services actions, check out Service access roles.

Retrieve the dual authorization policy for a specified key by running the following cURL command.

curl -X GET \
  'https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/policies?policy=dualAuthDelete' \
  -H 'authorization: Bearer <IAM_token>' \
  -H 'bluemix-instance: <instance_ID>' \
  -H 'accept: application/vnd.ibm.kms.policy+json'

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

Table 1. Describes the variables needed to view a dual authorization policy for a key with the API
Variable	Description
`key_ID`	Required. The unique identifier for the key that has an existing rotation policy.
`region`	Required. The region abbreviation, such as `us-south` or `eu-de`, that represents the geographic area where your Hyper Protect Crypto Services instance resides. For more information, see Regional service endpoints.
`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 instance. For more information, see Retrieving an instance ID.

A successful request returns dual authorization policy details that are associated with your key. The following JSON object shows an example response for a key that has an existing dual authorization policy.

{
  "metadata": {
    "collectionTotal": 1,
    "collectionType": "application/vnd.ibm.kms.policy+json"
  },
  "resources": [
    {
      "id": "02fd6835-6001-4482-a892-13bd2085f75d",
      "crn": "crn:v1:bluemix:public:hs-crypto:us-south:a/f047b55a3362ac06afad8a3f2f5586ea:12e8c9c2-a162-472d-b7d6-8b9a86b815a6:key:02fd6835-6001-4482-a892-13bd2085f75d",
      "dualAuthDelete": {
        "enabled": true
      },
      "createdBy": "...",
      "creationDate": "2020-03-10T20:41:27Z",
      "updatedBy": "...",
      "lastUpdateDate": "2020-03-16T20:41:27Z"
    }
  ]
}

For keys that do not have an existing dual authorization policy, the following JSON shows an example response.

{
  "metadata": {
    "collectionTotal": 0,
    "collectionType": "application/vnd.ibm.kms.policy+json"
  }
}

Creating a dual authorization policy for a key

Create a dual authorization policy for single key by making a PUT call to the following endpoint.

https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/policies?policy=dualAuthDelete

After you enable a dual authorization policy for a single key, the policy cannot be reverted.

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

To work with dual authorization policies, you must be assigned a Manager access policy for the instance or key. To learn how IAM roles map to Hyper Protect Crypto Services actions, check out Service access roles.

Enable dual authorization for a specified key by running the following cURL command.

curl -X PUT \
  'https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/policies?policy=dualAuthDelete' \
  -H 'authorization: Bearer <IAM_token>' \
  -H 'bluemix-instance: <instance_ID>' \
  -H 'content-type: application/vnd.ibm.kms.policy+json' \
  -d '{
    "metadata": {
      "collectionType": "application/vnd.ibm.kms.policy+json",
      "collectionTotal": 1
    },
    "resources": [
      {
        "type": "application/vnd.ibm.kms.policy+json",
        "dualAuthDelete": {
          "enabled": true
        }
      }
    ]
  }'

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

Table 2. Describes the variables needed to update a dual authorization policy with the API
Variable	Description
`key_ID`	Required. The unique identifier for the key that you want to create a dual authorization policy for.
`region`	Required. The region abbreviation, such as `us-south` or `eu-de`, that represents the geographic area where your Hyper Protect Crypto Services instance resides. For more information, see Regional service endpoints.
`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 instance. For more information, see Retrieving an instance ID.

A successful request returns a 200 OK response with dual authorization policy details for your key. The following JSON object shows an example response.

{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.policy+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "id": "2291e4ae-a14c-4af9-88f0-27c0cb2739e2",
      "crn": "crn:v1:bluemix:public:hs-crypto:us-south:a/f047b55a3362ac06afad8a3f2f5586ea:30372f20-d9f1-40b3-b486-a709e1932c9c:key:2291e4ae-a14c-4af9-88f0-27c0cb2739e2",
      "dualAuthDelete": {
        "enabled": true
      },
      "createdBy": "...",
      "creationDate": "2020-03-10T20:41:27Z",
      "updatedBy": "...",
      "lastUpdateDate": "2020-03-16T20:41:27Z"
    }
  ]
}

The key now requires an authorization from two users before it can be deleted.

For more information, see Deleting keys using dual authorization.