create-root-keys.md

copyright	lastupdated	keywords	subcollection
years 2017, 2019	2019-05-14	create root key, create key-wrapping key, create CRK, create CMK, create customer key, create root key in Key Protect, create key-wrapping key in Key Protect, create customer key in Key Protect, key-wrapping key, root key API examples	key-protect

{:shortdesc: .shortdesc} {:codeblock: .codeblock} {:screen: .screen} {:new_window: target="_blank"} {:pre: .pre} {:tip: .tip} {:note: .note} {:important: .important}

Creating root keys

{: #create-root-keys}

You can use {{site.data.keyword.keymanagementservicefull}} to create root keys by using the {{site.data.keyword.keymanagementserviceshort}} GUI, or programmatically with the {{site.data.keyword.keymanagementserviceshort}} 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 Protecting data with envelope encryption.

Creating root keys with the GUI

{: #create-root-key-gui}

After you create an instance of the service, complete the following steps to create a root key with the {{site.data.keyword.keymanagementserviceshort}} GUI.

1. Log in to the {{site.data.keyword.cloud_notm}} console {: new_window}.

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.keymanagementserviceshort}}.

4. To create a new key, click Add key and select the Create a key window.

   Specify the key's details:

   Table 1. Describes the Create a key settings

   Setting	Description
   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 type	The type of key that you would like to manage in {{site.data.keyword.keymanagementserviceshort}}. From the list of key types, select Root key.

5. When you are finished 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-GCM algorithm. For added security, keys are generated by FIPS 140-2 Level 2 certified hardware security modules (HSMs) that are located in secure {{site.data.keyword.cloud_notm}} data centers.

Creating root keys with the API

{: #create-root-key-api}

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

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

{: codeblock}

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

2. Call the {{site.data.keyword.keymanagementserviceshort}} API {: new_window} with the following cURL command.

   curl -X POST \
     https://<region>.kms.cloud.ibm.com/api/v2/keys \
     -H 'authorization: Bearer <IAM_token>' \
     -H 'bluemix-instance: <instance_ID>' \
     -H 'content-type: application/vnd.ibm.kms.key+json' \
     -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_alias>",
      "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.

   Table 1. Describes the variables that are needed to add a root key with the {{site.data.keyword.keymanagementserviceshort}} API

   Variable	Description
   region	Required. The region abbreviation, such as us-south or eu-gb, that represents the geographic area where your {{site.data.keyword.keymanagementserviceshort}} service instance resides. For more information, see Regional service endpoints.
   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.keymanagementserviceshort}} service instance. For more information, see Retrieving an instance ID.
   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. Important: To protect your privacy, do not store your personal data as metadata for your key.
   key_description	An extended description of your key. Important: To protect your privacy, do not store your personal data as metadata for your key.
   YYYY-MM-DD 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_type	A boolean value that determines whether the key material can leave the service. When you set the extractable attribute to false, the service creates a root key that you can use for wrap or unwrap operations.

   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 {: new_window}. {: 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 {{site.data.keyword.keymanagementserviceshort}} API.

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

   curl -X GET \
     https://<region>.kms.cloud.ibm.com/api/v2/keys \
     -H 'accept: application/vnd.ibm.collection+json' \
     -H 'authorization: Bearer <IAM_token>' \
     -H 'bluemix-instance: <instance_ID>'
   

   {: codeblock}

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

What's next

{: #create-root-key-next-steps}

• To find out more about protecting keys with envelope encryption, check out Wrapping keys.
• To find out more about programmatically managing your keys, check out the {{site.data.keyword.keymanagementserviceshort}} API reference doc {: new_window}.