import-root-keys.md

copyright	lastupdated	keywords	subcollection
years 2017, 2020	2020-07-07	import symmetric key, upload symmetric key, import root key, upload root key, import key-wrapping key, upload key-wrapping key, import CRK, import CMK, upload CRK, upload CMK, import customer key, upload customer key, key-wrapping key, root key API examples	key-protect

{:shortdesc: .shortdesc} {:screen: .screen} {:pre: .pre} {:table: .aria-labeledby="caption"} {:external: target="_blank" .external} {:codeblock: .codeblock} {:tip: .tip} {:note: .note} {:important: .important} {:term: .term}

Importing root keys

{: #import-root-keys}

You can use {{site.data.keyword.keymanagementservicefull}} to secure your existing 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 importing root keys into {{site.data.keyword.keymanagementserviceshort}}, see Bringing your encryption keys to the cloud.

Plan ahead for importing keys by reviewing your options for creating and encrypting key material. For added security, you can enable the secure import of the key material by using an import token to encrypt your key material before you bring it to the cloud. {: note}

Importing root keys in the console

{: #import-root-key-gui}

After you create an instance of the service, complete the following steps to import a key with the {{site.data.keyword.cloud_notm}} console.

If you enable dual authorization settings for your service 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 {{site.data.keyword.cloud_notm}} console{: 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.keymanagementserviceshort}}.

4. To import a key, click Add key and select the Import your own key window.

   Specify the key's details:

   Table 1. Describes the Import your own key settings

   Setting	Description
   Name	A human-readable alias 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 type	The [type of key](/docs/key-protect?topic=key-protect-envelope-encryption#key-types) that you would like to manage in {{site.data.keyword.keymanagementserviceshort}}. From the list of key types, select Root key.
   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, check out [Base64 encoding your key material](#how-to-encode-root-key-material). </p> <p> Ensure that the key material meets the following requirements: </p> <p> <ul> <li> The key must be 128, 192, or 256 bits. </li> <li> The bytes of data, for example 32 bytes for 256 bits, must be encoded by using base64 encoding. </li> </ul> </p> </td>

5. When you are finished filling out the key's details, click Import key to confirm.

Importing root keys with the API

{: #import-root-key-api}

Import symmetric keys to {{site.data.keyword.keymanagementserviceshort}} 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{: external} 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' \
     -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>",
           "payload": "<key_material>",
           "extractable": <key_type>
         }
       ]
     }'
   

   {: codeblock}

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

   Table 4. 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](/docs/key-protect?topic=key-protect-regions#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](/docs/key-protect?topic=key-protect-retrieve-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](/docs/key-protect?topic=key-protect-retrieve-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. 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 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, check out [Base64 encoding your key material](#how-to-encode-root-key-material). Ensure that the key material meets the following requirements: The key must be 128, 192, or 256 bits. The bytes of data, for example 32 bytes for 256 bits, must be encoded by using base64 encoding.
   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.

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

Base64 encoding your key material

{: #how-to-encode-root-key-material}

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 encrypt existing key material

{: #open-ssl-encoding-root-import}

1. Download and install OpenSSL{: external}.

2. Base64 encode your key material string by running the following command:

   $ openssl base64 -in <infile> -out <outfile>
   

   {: codeblock}

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

   Table 3. Describes the variables that are needed to base64 encode your key material.

   Variable	Description
   infile	The name of the file where your key material string resides.
   outfile	The name of the file where your base64 encoded key material will be be outputted once the command has ran. Ensure that the key is 128, 192, or 256 bits in length.

If you want to output the base64 material in the command line directly rather than a file, run the command openssl enc -base64 <<< '<key_material_string>', 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-root-new-key-material}

1. Download and install OpenSSL{: external}.

2. Base64 encode your key material string by running the following command:

   $ openssl rand <bit_length> -base64
   

   {: codeblock}

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

   Table 4. Describes the variable that is needed to create and encode new key material.

   Variable	Description
   bit_length	The length of the key, measured in bits. Acceptable bit lengths: 128, 192, 256

What's next

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