--- name: hs-crypto-rewrap-keys title: Rewrapping data encryption keys with root keys description: Reencrypt your data encryption keys by using the IBM Cloud® Hyper Protect Crypto Services key management service API. last-updated: 2026-07-01 --- > ## Documentation Index > The table of contents for this documentation set is at https://cloud.ibm.com/docs/hs-crypto?format=markdown > The index for all IBM Cloud docs is at: https://cloud.ibm.com/docs/llms.txt > Use these files to discover more information as needed. # Rewrapping data encryption keys with root keys {: #rewrap-keys} IBM Cloud® Hyper Protect Crypto Services is deprecated. As of 28 March 2026, you can't create new instances, and access to free instances will be removed. Existing premium plan instances are supported until 28 March 2027. Any instances that still exist on that date will be deleted. {: deprecated} Reencrypt your data encryption keys by using the IBM Cloud® Hyper Protect Crypto Services key management service API. {: shortdesc} When you [rotate a root key in Hyper Protect Crypto Services](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-root-key-rotation-intro&format=markdown), new cryptographic key material becomes available for protecting the data encryption keys (DEKs) that are associated with the root key. With the rewrap API, you can reencrypt or rewrap your DEKS without exposing the keys in their plain text form. To learn how envelope encryption helps you control the security of at-rest data in the cloud, see [Protecting data with envelope encryption](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-envelope-encryption&format=markdown). ## Rewrapping keys by using the API {: #rewrap-key-api} You can reencrypt a specified data encryption key (DEK) with a root key that you manage in Hyper Protect Crypto Services, without exposing the DEK in the plain text form. Rewrapping keys works by combining `unwrap` and `wrap` calls to the service. For example, you can emulate a `rewrap` operation by first calling the `unwrap` API to access a DEK, and then calling the `wrap` API to reencrypt the DEK by using the newest root key material. {: note} [After you rotate a root key in the service](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-rotate-keys&format=markdown), rewrap a data encryption key that is associated with the root key by making a `POST` call to the following endpoint. ``` https://.api..hs-crypto.appdomain.cloud/api/v2/keys//actions/rewrap ``` {: codeblock} 1. [Retrieve your service and authentication credentials to work with keys in the service](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-set-up-kms-api&format=markdown). 2. Copy the ID of the rotated root key that you used to perform the initial wrap request. You can retrieve the ID for a key by making a `GET api/v2/keys` request, or by viewing your keys in the UI. 3. Copy the `ciphertext` value that was returned during the latest wrap request. 4. Rewrap the key with the latest root key material by running the following cURL command. ```sh curl -X POST \ 'https://.api..hs-crypto.appdomain.cloud/api/v2/keys//actions/rewrap' \ -H 'accept: application/vnd.ibm.kms.key_action+json' \ -H 'authorization: Bearer ' \ -H 'bluemix-instance: ' \ -H 'content-type: application/vnd.ibm.kms.key_action+json' \ -H "x-kms-key-ring: " \ -H 'correlation-id: ' \ -d '{ "ciphertext": "" }' ``` {: codeblock} Replace the variables in the example request according to the following table. | Variable | Description | | --- | --- | | `region` | **Required.** The region abbreviation, such as `us-south` or `eu-de`, that represents the geographic area where your Hyper Protect Crypto Services service instance resides. For more information, see [Regional service endpoints](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-regions&format=markdown#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](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-retrieve-access-token&format=markdown). | | `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](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-retrieve-instance-ID&format=markdown). | | `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. \n \n 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](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-managing-key-rings&format=markdown). | | `correlation_ID` | The unique identifier that is used to track and correlate transactions. | | `encrypted_data_key` | **Required.** The `ciphertext` value that was returned by the original wrap operation. | {: caption="Describes the variables needed to rewrap keys in Hyper Protect Crypto Services." caption-side="bottom"} The newly wrapped data encryption key, original key version (`keyVersion`) that is associated with the supplied ciphertext and latest key version (`rewrappedKeyVersion`) associated with the new ciphertext is returned in the response entity-body. The following JSON object shows an example returned value. ```json { "ciphertext": "eyJjaX ... h0Ijoi ... c1ZCJ9", "keyVersion": { "id": "02fd6835-6001-4482-a892-13bd2085f75d" }, "rewrappedKeyVersion": { "id": "12e8c9c2-a162-472d-b7d6-8b9a86b815a6" } } ``` {: screen} Store and use the new `ciphertext` value for future envelope encryption operations so that your data is protected by the latest root key.