Wrapping keys

Wrapping a key using the console

If you already have an instance of Key Protect and 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 from the list of your keys that you want to use to wrap your data.

5. Click the ⋯ icon and then click the Envelope encryption option to open the side panel. Make sure the "Wrap key" option is selected.

6. You have a choice of whether to allow Key Protect to wrap your data or whether you want to provide your own base64 encoded plaintext and additional authentication data (AAD), as needed, to wrap the data. Note that if you choose to provide your own plaintext and AAD, you will have to provide it when unwrapping your data. If you do not have experience creating AAD and base 64 encoded plaintext, the recommended practice is to allow Key Protect to wrap your data by leaving the Wrap key for me option selected.

7. Click Wrap Key button.

Wrapping keys by using the API

You can protect a specified data encryption key (DEK) with a root key that you manage in Key Protect.

After you designate a root key in the service, you can wrap a DEK with advanced encryption by making a POST call to the following endpoint.

https://<region>.kms.cloud.ibm.com/api/v2/keys/<keyID_or_alias>/actions/wrap

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

2. Copy the key material of the DEK that you want to manage and protect.

   If you have manager or writer privileges for your Key Protect instance, you can retrieve the key material for a specific key by making a GET /v2/keys/<keyID_or_alias> request.

3. Copy the ID of the root key that you want to use for wrapping.

4. Run the following curl command to protect the key with a wrap operation.

   $ curl -X POST \
       "https://<region>.kms.cloud.ibm.com/api/v2/keys/<keyID_or_alias>/actions/wrap" \
       -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 '{
               "plaintext": "<data_key>",
               "aad": [
                   "<additional_data>",
                   "<additional_data>"
               ]
           }'
   

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

Your wrapped data encryption key, containing the base64 encoded key material, is returned in the response entity-body. The response body also contains the ID of the key version that was used to wrap the supplied plaintext. The following JSON object shows an example returned value.

{
    "ciphertext": "eyJjaXBoZXJ0ZXh0IjoiYmFzZTY0LWtleS1nb2VzLWhlcmUiLCJpdiI6IjRCSDlKREVmYU1RM3NHTGkiLCJ2ZXJzaW9uIjoiNC4wLjAiLCJoYW5kbGUiOiJ1dWlkLWdvZXMtaGVyZSJ9",
    "keyVersion": {
        "id": "02fd6835-6001-4482-a892-13bd2085f75d"
    }
}

If you omit the plaintext attribute when you make the wrap request, the service returns both the generated data encryption key (DEK) and the wrapped DEK in base64 encoded format.

{
    "plaintext": "Rm91ciBzY29yZSBhbmQgc2V2ZW4geWVhcnMgYWdv",
    "ciphertext": "eyJjaXBoZXJ0ZXh0IjoiYmFzZTY0LWtleS1nb2VzLWhlcmUiLCJpdiI6IjRCSDlKREVmYU1RM3NHTGkiLCJ2ZXJzaW9uIjoiNC4wLjAiLCJoYW5kbGUiOiJ1dWlkLWdvZXMtaGVyZSJ9",
    "keyVersion": {
        "id": "12e8c9c2-a162-472d-b7d6-8b9a86b815a6"
    }
}

The plaintext value represents the unwrapped DEK, and the ciphertext value represents the wrapped DEK and are both base64 encoded. The keyVersion.id value represents the version of the root key that was used for wrapping.

If you want Key Protect to generate a new data encryption key (DEK) on your behalf, you can also pass in an empty body on a wrap request. Your generated DEK, containing the base64 encoded key material, is returned in the response entity-body, along with the wrapped DEK.