set-dual-auth-policy.md

copyright	lastupdated	keywords	subcollection
years 2017, 2024	2024-07-01	set deletion policy, dual authorization, policy-based, key deletion	hs-crypto

{{site.data.keyword.attribute-definition-list}}

Setting dual authorization policies for keys

{: #set-dual-auth-key-policy}

You can use {{site.data.keyword.cloud}} {{site.data.keyword.hscrypto}} to set dual authorization policies for individual root keys or standard keys. {: shortdesc}

Dual authorization is an extra policy that helps to prevent accidental or malicious deletion of encryption keys in your {{site.data.keyword.hscrypto}} instance. When you enable this policy at the key level, {{site.data.keyword.hscrypto}} 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. {: important}

To enable dual authorization settings at the instance level, check out Managing service settings. {: tip}

Managing dual authorization policies with the key management service API

{: #manage-dual-auth-key-policies-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 {{site.data.keyword.hscrypto}} 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

{: #view-dual-auth-key-policy-api}

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://<instance_ID>.api.<region>.hs-crypto.appdomain.cloud/api/v2/keys/<key_ID>/policies?policy=dualAuthDelete

{: codeblock}

1. 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 {{site.data.keyword.hscrypto}} actions, check out Service access roles. {: note}

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

   curl -X GET \
     'https://<instance_ID>.api.<region>.hs-crypto.appdomain.cloud/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'
   

   {: codeblock}

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

   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 {{site.data.keyword.hscrypto}} instance resides. For more information, see Regional service endpoints.
   IAM_token	Required. Your {{site.data.keyword.cloud_notm}} 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 {{site.data.keyword.hscrypto}} instance. For more information, see Retrieving an instance ID.
   {: caption="Table 1. Describes the variables needed to view a dual authorization policy for a key with the API" caption-side="bottom"}

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

   {: screen}

   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"
     }
   }

   {: screen}

Creating a dual authorization policy for a key

{: #create-dual-auth-key-policy-api}

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

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

{: codeblock}

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

1. 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 {{site.data.keyword.hscrypto}} actions, check out Service access roles. {: note}

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

   curl -X PUT \
     'https://<instance_ID>.api.<region>.hs-crypto.appdomain.cloud/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
           }
         }
       ]
     }'
   

   {: codeblock}

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

   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 {{site.data.keyword.hscrypto}} instance resides. For more information, see Regional service endpoints.
   IAM_token	Required. Your {{site.data.keyword.cloud_notm}} 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 {{site.data.keyword.hscrypto}} instance. For more information, see Retrieving an instance ID.
   {: caption="Table 2. Describes the variables needed to update a dual authorization policy with the API" caption-side="bottom"}

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

   {: screen}

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

   For more information, see Deleting keys using dual authorization.