--- name: hs-crypto-import-root-keys title: Importing root keys description: You can use IBM Cloud® Hyper Protect Crypto Services to secure your existing root keys by using the UI, or programmatically with the 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. # Importing root keys {: #import-root-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} You can use IBM Cloud® Hyper Protect Crypto Services to secure your existing root keys by using the UI, or programmatically with the Hyper Protect Crypto Services key management service API. {: shortdesc} Root keys are symmetric key-wrapping keys that are used to protect the security of encrypted data in the cloud. For more information about importing root keys, see [Bringing your encryption keys to the cloud](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-importing-keys&format=markdown). Plan ahead for importing keys by [reviewing your options for creating and encrypting key material](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-importing-keys&format=markdown#plan-ahead). For added security, you can enable the secure import of the key material by using an [import token](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-importing-keys&format=markdown#using-import-tokens) to encrypt your key material before you bring it to the cloud. {: note} ## Importing root keys with the UI {: #import-root-key-gui} {: ui} After you [create an instance of the service](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-provision&format=markdown), complete the following steps to add your existing root key with the Hyper Protect Crypto Services GUI. 1. [Log in to the UI](https://cloud.ibm.com/){: external}. 2. Go to **Menu** > **Resource list** to view a list of your resources. 3. From your IBM Cloud resource list, select your provisioned instance of Hyper Protect Crypto Services. 4. To import a key, select the **KMS keys** tab in the side menu. 5. In the **Keys** table, click **Add key** and select **Import a key**. Specify the key's details: | Setting | Description | | --- | --- | | Key type | The type of key that you would like to manage in Hyper Protect Crypto Services. From the list of key types, select **[Root key](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-understand-concepts&format=markdown#root-key-concept)**. | | Key name | A unique, human-readable alias for easy identification of your key. To protect your privacy, ensure that the key name does not contain personally identifiable information (PII), such as your name or location. | | Key alias | (Optional) One or more unique, human-readable aliases that you want to assign to your key for easy recognition. Alias size can be 2 - 90 characters. You can set up to five key aliases for the key, with each separated by a comma. \n \n Note: Each alias must be alphanumeric, case-sensitive, and cannot contain spaces or special characters other than dashes (-) or underscores (_). The alias cannot be a version 4 UUID and must not be a Hyper Protect Crypto Services reserved name: `allowed_ip`, `key`, `keys`, `metadata`, `policy`, `policies`, `registration`, `registrations`, `ring`, `rings`, `rotate`, `wrap`, `unwrap`, `rewrap`, `version`, `versions`. | | Key ring ID | Select a key ring from the list that contains the existing key rings. If you don't assign a key ring, the key will be added to the `default` key ring. For more information about key rings, see [Managing key rings](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-managing-key-rings&format=markdown). | | Key material | The base64 encoded key material, such as an existing key-wrapping key, that you want to store and manage in the service. For more information, see [Base64 encoding your key material](#encode-key-material-root-key). Ensure that the key material meets the following requirements: \n * The key must be 16, 24, or 32 bytes long, corresponding to 128, 192, or 256 bits. \n * The key must be base64-encoded. | | Expiration date | (Optional) Set the date and time when the key gets expired. After the expiration date, the key moves into the Deactivated state. For more information about key state, see [Monitoring the lifecycle of encryption keys](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-key-states&format=markdown). | | Description | (Optional) Add an extended description for your key. It needs to be two to 240 characters in length. | {: caption="Describes the settings for importing a root key" caption-side="bottom"} 6. When you finish filling out the key's details, click **Import key** to confirm. ## Importing root keys with the API {: #import-root-key-api} {: api} Import symmetric keys to Hyper Protect Crypto Services by making a `POST` call to the following endpoint. ``` https://.api..hs-crypto.appdomain.cloud/api/v2/keys ``` {: 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. Call the [Hyper Protect Crypto Services key management service API](https://cloud.ibm.com/apidocs/hs-crypto){: external} with the following cURL command: ```cURL curl -X POST \ https://.api..hs-crypto.appdomain.cloud/api/v2/keys \ -H 'authorization: Bearer ' \ -H 'bluemix-instance: ' \ -H 'content-type: application/vnd.ibm.kms.key+json' \ -d '{ "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "name": "", "description": "", "expirationDate": "", "payload": "", "extractable": } ] }' ``` {: 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 `au-syd`, that represents the geographic area where your Hyper Protect Crypto Services instance is located. 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. | | `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 instance. For more information, see [Retrieving your instance ID](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-retrieve-instance-ID&format=markdown). | | `correlation_ID` | The unique identifier that is used to track and correlate transactions. | | `key_alias` | **Required.** A unique, human-readable name for easy identification of your key. To protect your privacy, do not store your personal data as metadata for your key. | | `key_description` | An extended description of your key. To protect your privacy, do not store your personal data as metadata for your key. | | `YYYY-MM-DD` \n \n `HH:MM:SS.SS` | The date and time that the key expires in the system, in RFC 3339 format. If the `expirationDate` attribute is omitted, the key does not expire. | | `key_material` | The base64 encoded key material, such as an existing key-wrapping key, that you want to store and manage in the service. For more information, see [Base64 encoding your key material](#encode-key-material-root-key). Ensure that the key material meets the following requirements: \n * The key must be 16, 24, or 32 bytes long, corresponding to 128, 192, or 256 bits. \n * The key must be base64-encoded. | | `key_type` | A boolean value that determines whether the key material can leave the service. When you set the `extractable` attribute to `false`, the service designates the key as a root key that you can use for `wrap` or `unwrap` operations. | {: caption="Describes the variables needed to add a root key with the API" caption-side="bottom"} To protect the confidentiality of your personal data, avoid entering personally identifiable information (PII), such as your name or location, when you add keys to the service. For more examples of PII, see section 2.2 of the [NIST Special Publication 800-122](https://www.nist.gov/publications/guide-protecting-confidentiality-personally-identifiable-information-pii){: external}. {: important} A successful `POST api/v2/keys` response returns the ID value for your key, along with other metadata. The ID is a unique identifier that is assigned to your key and is used for subsequent calls to the Hyper Protect Crypto Services key management service API. 3. Optional: Verify that the key was added by running the following call to browse the keys in your Hyper Protect Crypto Services service instance. ```cURL curl -X GET \ https://.api..hs-crypto.appdomain.cloud/api/v2/keys \ -H 'accept: application/vnd.ibm.collection+json' \ -H 'authorization: Bearer ' \ -H 'bluemix-instance: ' ``` {: codeblock} ## Importing root keys with the CLI {: #import-root-key-cli} {: cli} Complete the following steps to import root keys by using the Key Protect CLI, which is integrated in Hyper Protect Crypto Services: 1. [Set up the Key Protect CLI](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-set-up-cli&format=markdown). 2. Import a root key with the following command: ``` ibmcloud kp key create ``` {: pre} You can find more parameters for this command in the [Key Protect CLI reference](https://cloud.ibm.com/docs/key-protect?topic=key-protect-key-protect-cli-reference&format=markdown#kp-key-create). ## Base64 encoding your key material {: #encode-key-material-root-key} When importing an existing root key, it is required to include the encrypted key material that you want to store and manage in the service. ### Using OpenSSL to encode existing key material {: #open-ssl-encoding-root-key} 1. Download and install [OpenSSL](https://github.com/openssl/openssl#for-production-use){: external}. 2. Base64 encode your key material string by running the following command: ``` $ openssl base64 -in -out ``` {: codeblock} Replace the variables in the example request according to the following table. | Variable | Description | | --- | --- | | `infile` | The name of the file where your key material string is located. Ensure that the key is 16, 24, or 32 bytes long, corresponding to 128, 192, or 256 bits. | | `outfile` | The name of the file where your base64-encoded key material will be created when the command has run. | {: caption="Describes the variables needed to base64 encode your key material" caption-side="bottom"} If you want to output the base64 material in the command line directly rather than a file, run the command `openssl enc -base6<<< ''`, where *key_material_string* is the key material input for your imported key. {: note} ### Using OpenSSL to create and encode new key material {: #open-ssl-encoding-new-key-material-root-key} 1. Download and install [OpenSSL](https://github.com/openssl/openssl#for-production-use){: external}. 2. Base64 encode your key material string by running the following command: ``` $ openssl rand -base64 ``` {: codeblock} Replace the `byte_length` variable in the example request with the length of your key, which is measured in bytes. Acceptable byte lengths are 16, 24, or 32 bytes, corresponding to 128, 192, or 256 bits. ## What's next {: #import-root-key-next} - To find out more about protecting keys with envelope encryption, check out [Wrapping keys](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-wrap-keys&format=markdown). - To find out instruction on creating a key, check out [Creating root keys](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-create-root-keys&format=markdown) or [Creating standard keys](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-create-standard-keys&format=markdown). - To find out more about programmatically managing your keys, [check out the Hyper Protect Crypto Services key management service API reference doc](https://cloud.ibm.com/apidocs/hs-crypto){: external}. - To find out more about using the Key Protect CLI, check out the [Key Protect CLI reference doc](https://cloud.ibm.com/docs/key-protect?topic=key-protect-key-protect-cli-reference&format=markdown).