unwrap-keys.md

copyright	lastupdated	keywords	subcollection
years 2017, 2019	2019-05-14	unwrap key, decrypt key, decrypt data encryption key, access data encryption key, envelope encryption API examples	key-protect

{:shortdesc: .shortdesc} {:codeblock: .codeblock} {:screen: .screen} {:new_window: target="_blank"} {:pre: .pre} {:tip: .tip} {:note: .note} {:important: .important}

Unwrapping keys

{: #unwrap-keys}

You can unwrap a data encryption key (DEK) to access its contents by using the {{site.data.keyword.keymanagementservicefull}} API, if you are a privileged user. Unwrapping a DEK decrypts and checks the integrity of its contents, returning the original key material to your {{site.data.keyword.cloud_notm}} data service. {: shortdesc}

To learn how key wrapping helps you control the security of at-rest data in the cloud, see Protecting data with envelope encryption.

Unwrapping keys by using the API

{: #unwrap-key-api}

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

https://<region>.kms.cloud.ibm.com/api/v2/keys/<key_id>?action=unwrap

{: codeblock}

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

2. Copy the ID of the root key 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 {{site.data.keyword.keymanagementserviceshort}} GUI.

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://<region>.kms.cloud.ibm.com/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 'correlation-id: <correlation_ID>' \
     -d '{
     "ciphertext": "<encrypted_data_key>",
     "aad": ["<additional_data>", "<additional_data>"]
   }'
   

   {: codeblock}

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

   Table 1. Describes the variables that are needed to unwrap keys in {{site.data.keyword.keymanagementserviceshort}}.

   Variable	Description
   region	Required. The region abbreviation, such as us-south or eu-gb, that represents the geographic area where your {{site.data.keyword.keymanagementserviceshort}} service instance resides. For more information, see Regional service endpoints.
   key_ID	Required. The unique identifier for the root key that you used for the initial wrap request.
   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.keymanagementserviceshort}} service instance. For more information, see Retrieving an instance ID.
   correlation_ID	The unique identifier that is used to track and correlate transactions.
   additional_data	The additional authentication data (AAD) that is used to further secure the key. Each string can hold up to 255 characters. If you supply AAD when you make a wrap call to the service, you must specify the same AAD during the unwrap call.
   encrypted_data_key	Required. The ciphertext value that was returned during a wrap operation.

   The original key material is returned in the response entity-body. The following JSON object shows an example returned value.

   {
     "plaintext": "VGhpcyBpcyBhIHNlY3JldCBtZXNzYWdlLg=="
   }
   

   {:screen}