Unwrapping data encryption keys with root keys

Unwrapping keys by using the API

After you make a wrap call to the service, you can unwrap a specified data encryption key (DEK) to access the contents by making a POST call to the following endpoint.

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

Root keys that contain the same key material can unwrap the same data encryption key (WDEK).

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

2. Copy the ID of the root keyA symmetric wrapping key that is used for encrypting and decrypting other keys that are stored in a data service. that you used to perform the initial wrap request.

   You can retrieve the ID for a key by making a GET /v2/keys request, or by viewing your keys in the UI.

3. Copy the ciphertext value that was returned during the initial wrap request.

4. Run the following cURL command to decrypt and authenticate the key material.

   curl -X POST \
     'https://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>?action=unwrap' \
     -H 'accept: application/vnd.ibm.kms.key_action+json' \
     -H 'authorization: Bearer <IAM_token>' \
     -H 'bluemix-instance: <instance_ID>' \
     -H 'content-type: application/vnd.ibm.kms.key_action+json' \
     -H 'x-kms-key-ring: <key_ring_ID>' \
     -H 'correlation-id: <correlation_ID>' \
     -d '{
     "ciphertext": "<encrypted_data_key>"
   }'
   

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

   Table 1. Describes the variables needed to unwrap keys in Hyper Protect Crypto Services

   Variable	Description
   region	Required. The region abbreviation, such as us-south or au-syd, 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 root key that you used for the initial wrap request.
   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 yourHyper 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 searches for the key in every key ring that is associated with the specified instance. 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.
   correlation_ID	Optional. The unique identifier that is used to track and correlate transactions.
   encrypted_data_key	The ciphertext value that was returned during a wrap operation.

   The original key material is returned in the response entity-body. The response body also contains the ID of the key version that was used to unwrap the supplied ciphertext. The following JSON object shows a sample returned value.

   {
     "plaintext": "Rm91ciBzY29yZSBhbmQgc2V2ZW4geWVhcnMgYWdv",
     "keyVersion": {
       "id": "02fd6835-6001-4482-a892-13bd2085f75d"
     }
   }
   

   If Hyper Protect Crypto Services detects that you rotated the root key that is used to unwrap and access your data, the service also returns a newly wrapped data encryption key (ciphertext) in the unwrap response body. The latest key version (rewrappedKeyVersion) that is associated with the new ciphertext is also returned. Store and use the new ciphertext value for future envelope encryption operations so that your data is protected by the latest root key.

Decoding your key material

When you unwrap a data encryption key, the key material is returned in base64 encoding. You need to decode the key before you encrypt it.