Managing dual authorization of your service instance

After you set up your IBM Cloud® Hyper Protect Crypto Services instance, you can manage dual authorization by using the key management service API.

This policy only applies to key management service keys and related operations.

Understanding dual authorization of your service instance

Dual authorization for Hyper Protect Crypto Services instances is an extra policy that helps to prevent accidental or malicious deletion of keys. When you enable this policy at the instance level, Hyper Protect Crypto Services requires an authorization from two users to delete any keys that are created after the policy is enabled.

Before you enable dual authorization for your service instance, keep in mind the following considerations:

When you enable dual authorization for your service instance, the policy is applicable only for new keys. By enabling dual authorization at the instance level, any new keys that you add to the instance will automatically inherit a dual authorization policy. Your existing keys are not affected by the policy change and will still require a single authorization for deletion.
You can always disable a dual authorization policy for your service instance. If you want to disable an existing dual authorization policy to allow for single authorization, keep in mind that the change is applicable only for future keys that you add to the instance. Any existing keys that were created under a dual authorization policy will continue to require actions from two users before the keys can be deleted. After a key inherits a dual authorization policy, the policy cannot be reverted.

Enabling dual authorization for your service instance with the UI

As an instance manager, if you prefer to enable a dual authorization policy on your instance by using a graphical interface, you can use the UI.

After creating a service instance, complete the following steps to create a dual authorization policy:

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.
In the UI of the selected service instance, select the Instance policies tab in the side menu.
In the Dual authorization deletion section, check the box for Require two users to approve key deletions, and click Save policy.

Enabling dual authorization for your service instance with the API

As an instance manager, enable a dual authorization policy for a Hyper Protect Crypto Services instance by making a PUT call to the following endpoint.

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

Retrieve your authentication credentials to work with the API.

To enable and disable dual authorization policy, you must be assigned a Manager access policy for your service instance. To learn how IAM roles map to Hyper Protect Crypto Services service actions, check out Service access roles.

Enable a dual authorization policy for your service instance by running the following cURL command.

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

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

Table 1. Describes the variables needed to enable dual authorization at the instance level
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 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 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. 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 request returns an HTTP 204 No Content response, which indicates that your service instance is now enabled for dual authorization. Keys that you create or import to the service now require two authorizations before they can be deleted. For more information, see Deleting keys.

This new policy does not affect existing keys in your instance. If you need to enable dual authorization for an existing key, see Creating a dual authorization policy for a key.

Optional: Verify that the dual authorization policy was created by browsing the policies that are available for your Hyper Protect Crypto Services instance.

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

Disabling dual authorization for your service instance with the UI

As an instance manager, if you prefer to disable a dual authorization policy on your instance by using a graphical interface, you can use the UI.

After creating a service instance, complete the following steps to create a dual authorization policy:

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.
In the UI of the selected service instance, select the Instance policies tab in the side menu.
In the Dual authorization deletion section, clear the box for Require two users to approve key deletions, and click Save policy.

Disabling dual authorization for your service instance with the key management service API

As an instance manager, disable an existing dual authorization policy for a Hyper Protect Crypto Services instance by making a PUT call to the following endpoint.

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

Retrieve your authentication credentials to work with the API.

To enable and disable dual authorization policy, you must be assigned a Manager access policy for your service instance. To learn how IAM roles map to Hyper Protect Crypto Services service actions, check out Service access roles.

Disable an existing dual authorization policy for your service instance by running the following cURL command.

curl -X PUT \
  'https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/instance/policies?policy=dualAuthDelete' \
  -H 'accept: application/vnd.ibm.kms.policy+json' \
  -H 'authorization: Bearer <IAM_token>' \
  -H 'bluemix-instance: <instance_ID>' \
  -H 'x-kms-key-ring: <key_ring_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": false
        }
      }
    ]
  }'

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

Table 1. Describes the variables needed to enable dual authorization at the instance level
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 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 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. 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 request returns an HTTP 204 No Content response, which indicates that the dual authorization policy was updated for your service instance. Keys that you create or import to the service now require only one authorization before they can be deleted. For more information, see Deleting keys.

Optional: Verify that the dual authorization policy was updated by browsing the policies that are available for your Hyper Protect Crypto Services instance.

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