Unwrapping keys

Unwrapping a key using the console

If you already have an instance of Key Protect and you wish to encrypt your DEK by using a graphical interface, you can use the IBM Cloud console.

After you import or create your own keys, complete the following steps to wrap your data using the key:

1. Log in to the IBM Cloud console.

2. From the Menu, choose the Resource List to view a list of your resources.

3. From your IBM Cloud resource list, select your provisioned instance of Key Protect.

4. Choose the Root key that you used to originally wrap your data from the list of your keys.

5. Click the ⋯ icon to open a list of options for the DEK that you want to unwrap.

6. Click the Envelope encryption option to open the side panel. Choose the "Unwrap key" tab if it is not already highlighted.

7. Supply any required text for the above in the appropriate fields, including the ciphertext and any additional data you stored locally for the purpose of unwrapping the DEK.

8. Click Unwrap Key button.

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 its contents by making a POST call to the following endpoint.

https://<region>.kms.cloud.ibm.com/api/v2/keys/<keyID_or_alias>/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 key that you used to perform the initial wrap request.

   You can find the ID for a key in your Key Protect instance by retrieving a list of your keys, or by accessing the Key Protect dashboard.

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/<keyID_or_alias>/actions/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>",
               "aad": [
                   "<additional_data>",
                   "<additional_data>"
               ]
           }'
   

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

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 plaintext that is returned is base64 encoded. For more information on how to decode your key material, see Decoding your key material. The following JSON object shows an example returned value.

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

If Key Protect 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.