Wrapping data encryption keys with root keys

Wrapping keys by using the API

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

When you supply a root key for wrapping, ensure that the root key is 128, 192, or 256 bits so that the wrap call can succeed. If you create a root key in the service, Hyper Protect Crypto Services generates a 256-bit key from the HSMs, supported by the AES-CBC algorithm.

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://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/actions/wrap

1. Retrieve your service and 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 Hyper Protect Crypto Services service instance, you can retrieve the key material for a specific key by making a GET /v2/keys/<key_ID> 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://api.<region>.hs-crypto.cloud.ibm.com:<port>/api/v2/keys/<key_ID>/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>"
   }'
   

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

   Table 1. Describes the variables needed to wrap a specified key

   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 want to use for wrapping.
   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 your Hyper 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 will search for the key in every key ring that is associated with the specified instance. Therefore, 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.
   data_key	The key material of the DEK that you want to manage and protect. The plaintext value must be base64 encoded. To generate a new DEK, omit the plaintext attribute. The service generates a random plain text (32 bytes), wraps that value, and then returns both the generated and wrapped values in the response. The generated and wrapped values are base64 encoded and you will need to decode them in order to decrypt the keys.

   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 plain text. 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 Hyper Protect Crypto Services 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.