create-root-keys.md

copyright	years 2018, 2026
lastupdated	2026-07-01
keywords	root key, create root key, add key, root key api, api key, symmetric key, key material, key management, create key-wrapping key, create crk, create customer key, key-wrapping key
subcollection	hs-crypto

{{site.data.keyword.attribute-definition-list}}

Creating root keys

{: #create-root-keys}

{{site.data.keyword.cloud}} {{site.data.keyword.hscrypto}} 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 {{site.data.keyword.cloud}} {{site.data.keyword.hscrypto}} to create root keys{: term} by using the UI, or programmatically with the {{site.data.keyword.hscrypto}} 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 root keys, see Envelope encryption.

Creating root keys with the UI

{: #root-key-gui} {: ui}

After you create an instance of the service, complete the following steps to create a root key with the UI.

If you enable dual authorization settings for your {{site.data.keyword.hscrypto}} instance, keep in mind that any keys that you add to the service require an authorization from two users to delete keys. {: note}

1. Log in to the UI{: external}.

2. Go to Menu > Resource list to view a list of your resources.

3. From your {{site.data.keyword.cloud_notm}} resource list, select your provisioned instance of {{site.data.keyword.hscrypto}}.

4. To create a new key, select the KMS keys tab in the side menu.

5. In the Keys table, click Add key, and select Create a key.

   Specify the key's details:

   Setting	Description
   Key type	The type of key that you would like to manage in {{site.data.keyword.hscrypto}}. From the list of key types, select Root key.
   Key name	A unique, human-readable name for easy identification of your key. Length must be within 2 - 90 characters. 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 {{site.data.keyword.hscrypto}} 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 is added to the default key ring. For more information about key rings, see Managing key rings.
   Expiration date	Optional. The date and time that the key expires in the system, in RFC 3339 format (YYYY-MM-DD HH:MM:SS.SS, for example 2019-10-12T07:20:50.52Z). Use caution when setting an expiration date, as keys created with an expiration date automatically transition to the Deactivated state within one hour after expiration. In this state, the only allowed actions on the key are unwrap, rewrap, rotate, and delete. Deactivated keys cannot be used to encrypt (wrap) new data, even if rotated while deactivated. Rotation does not reset or extend the expiration date, nor does it allow the date to be changed. It is recommended that any data encrypted with an expiring or expired key be re-encrypted using a new customer root key (CRK) before the original CRK expires, to prevent service disruptions. Deleting and restoring a deactivated key does not move it back to the Active state. If the expiration_date attribute is omitted, the key does not expire.
   Description	(Optional) Add an extended description for your key. It can be two to 240 characters in length.
   {: caption="Describes the settings to create a key" caption-side="bottom"}

6. When you finish filling out the key's details, click Create key to confirm.

Keys that are created in the service are symmetric 256-bit keys, supported by the AES-CBC algorithm. For added security, keys are generated by FIPS 140-2 Level 4 certified hardware security modules (HSMs){: term} that are located in secure {{site.data.keyword.cloud_notm}} data centers.

Creating root keys with the API

{: #root-key-api} {: api}

Create a root key by making a POST call to the following endpoint.

https://<instance_ID>.api.<region>.hs-crypto.appdomain.cloud/api/v2/keys

{: codeblock}

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

2. Call the {{site.data.keyword.hscrypto}} key management service API{: external} with the following curl command.

   curl -X POST \
     "https://<instance_ID>.api.<region>.hs-crypto.appdomain.cloud/api/v2/keys" \
     -H "authorization: Bearer <IAM_token>" \
     -H "bluemix-instance: <instance_ID>" \
     -H "content-type: application/vnd.ibm.kms.key+json" \
     -H "x-kms-key-ring: <key_ring_ID>" \
     -H "correlation-id: <correlation_ID>" \
     -d '{
             "metadata": {
                 "collectionType": "application/vnd.ibm.kms.key+json",
                 "collectionTotal": 1
             },
             "resources": [
                 {
                     "type": "application/vnd.ibm.kms.key+json",
                      "name": "<key_name>",
                      "aliases": [alias_list],
                      "description": "<key_description>",
                      "expirationDate": "<YYYY-MM-DDTHH:MM:SS.SSZ>",
                      "extractable": <key_type>
                 }
             ]
         }'

   {: 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 {{site.data.keyword.hscrypto}} service instance resides. For more information, see Regional service endpoints.
   port	Required. The port number of the API endpoint.
   IAM_token	Required. Your {{site.data.keyword.cloud_notm}} 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 {{site.data.keyword.hscrypto}} service instance. For more information, see Retrieving an instance ID.
   key_ring_ID	Optional. The unique identifier of the target key ring that you want to assign the key to. If unspecified, the header is automatically set to default and the key belongs to the default key ring in the specified {{site.data.keyword.hscrypto}} instance. \n \n For more information, see Managing key rings.
   correlation_ID	The unique identifier that is used to track and correlate transactions.
   key_name	Required. A unique, human-readable name for easy identification of your key. \n \n Important: To protect your privacy, do not store your personal data as metadata for your key.
   alias_list	Optional. One or more unique, human-readable aliases assigned to your key. \n \n Important: To protect your privacy, do not store your personal data as metadata for your key. \n \n 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 {{site.data.keyword.hscrypto}} reserved name: allowed_ip, key, keys, metadata, policy, policies, registration, registrations, ring, rings, rotate, wrap, unwrap, rewrap, version, versions. Alias size can be 2 - 90 characters (inclusive).
   key_description	Optional: An extended description of your key. \n \n Important: To protect your privacy, do not store your personal data as metadata for your key.
   expiration_date	Optional. The date and time that the key expires in the system, in RFC 3339 format (YYYY-MM-DD HH:MM:SS.SS, for example 2019-10-12T07:20:50.52Z). Use caution when setting an expiration date, as keys created with an expiration date automatically transition to the Deactivated state within one hour after expiration. In this state, the only allowed actions on the key are unwrap, rewrap, rotate, and delete. Deactivated keys cannot be used to encrypt (wrap) new data, even if rotated while deactivated. Rotation does not reset or extend the expiration date, nor does it allow the date to be changed. It is recommended that any data encrypted with an expiring or expired key be re-encrypted using a new customer root key (CRK) before the original CRK expires, to prevent service disruptions. Deleting and restoring a deactivated key does not move it back to the Active state. If the expiration_date attribute is omitted, the key does not expire.
   key_type	A boolean value that determines whether the key material can leave the service. \n \n When you set the extractable attribute to false, the service creates 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"}

   If you set the expirationDate in your request, the key is moved to the deactivated state within 1 hour past the key's expiration date. The date and time that the key expires in the system, in RFC 3339 format (YYYY-MM-DD HH:MM:SS.SS, for example 2019-10-12T07:20:50.52Z). Use caution when setting an expiration date, as keys created with an expiration date automatically transition to the Deactivated state within one hour after expiration. In this state, the only allowed actions on the key are unwrap, rewrap, rotate, and delete. Deactivated keys cannot be used to encrypt (wrap) new data, even if rotated while deactivated. Rotation does not reset or extend the expiration date, nor does it allow the date to be changed. It is recommended that any data encrypted with an expiring or expired key be re-encrypted using a new customer root key (CRK) before the original CRK expires, to prevent service disruptions. Deleting and restoring a deactivated key does not move it back to the Active state. If the expirationDate attribute is omitted, the key does not expire. {: important}

   You can monitor the usage of keys with expiration dates using IBM Cloud Logs. The logs indicate the expiration date and the number of days remaining using the JSON properties responseData.expirationDate and responseData.daysToKeyExpire for keys that have expiration date and for the following action values: kms.secrets.wrap, kms.secrets.unwrap, kms.secrets.rewrap, kms.secrets.read, kms.secrets.readmetadata, kms.secrets.create, kms.secrets-with-policy-overrides.create and kms.secrets.expire. In addition, a successful REST call to GET /api/v2/keys returns the expirationDate property for each key that has an expiration date.

   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{: external}. {: note}

   A successful POST /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 {{site.data.keyword.hscrypto}} key management service API.

   {
       "metadata": {
           "collectionType": "application/vnd.ibm.kms.key+json",
           "collectionTotal": 1
       },
       "resources": [
           {
               "type": "application/vnd.ibm.kms.key+json",
               "id": "02fd6835-6001-4482-a892-13bd2085f75d",
               "name": "test-root-key",
               "aliases": [
                   "alias-1",
                   "alias-2"
                 ],
               "description": "A test root key",
               "state": 1,
               "extractable": false,
               "crn": "crn:v1:bluemix:public:hs-crypto:us-south:a/f047b55a3362ac06afad8a3f2f5586ea:12e8c9c2-a162-472d-b7d6-8b9a86b815a6:key:02fd6835-6001-4482-a892-13bd2085f75d",
               "imported": false,
               "creationDate": "2020-03-12T03:37:32Z",
               "createdBy": "...",
               "algorithmType": "AES",
               "algorithmMetadata": {
                   "bitLength": "256",
                   "mode": "CBC_PAD"
               },
               "algorithmBitSize": 256,
               "algorithmMode": "CBC_PAD",
               "lastUpdateDate": "2020-03-12T03:37:32Z",
               "keyVersion": {
                   "id": "2291e4ae-a14c-4af9-88f0-27c0cb2739e2",
                   "creationDate": "2020-03-12T03:37:32Z"
               },
               "dualAuthDelete": {
                   "enabled": false
               },
               "deleted": false
           }
       ]
   }

   {: screen}

   For a detailed description of the response parameters, see the {{site.data.keyword.hscrypto}} REST API reference doc{: external}. {: tip}

3. Optional: Verify that the key was created by running the following call to browse the keys in your {{site.data.keyword.hscrypto}} service instance.

   curl -X GET \
     https://<instance_ID>.api.<region>.hs-crypto.appdomain.cloud/api/v2/keys \
     -H 'accept: application/vnd.ibm.collection+json' \
     -H 'authorization: Bearer <IAM_token>' \
     -H 'bluemix-instance: <instance_ID>' \
     -H 'correlation-id: <correlation_ID>' \
   

   {: codeblock}

After you create a root key with the service, the key stays within the bounds of {{site.data.keyword.hscrypto}}, and the key material cannot be retrieved. {: note}

What's next

{: #root-key-next}

• To find out more about protecting keys with envelope encryption, check out Wrapping keys.
• To find out instruction on importing your own key, check out Importing root keys or Importing standard keys.
• To find out more about programmatically managing your keys, check out the {{site.data.keyword.hscrypto}} key management service API reference doc{: external}.