Importing root keys

You can use IBM® Key Protect for IBM Cloud® to secure and manage your existing root keys by importing them.

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 Key Protect, 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.

Importing root keys with the console

After you create an instance of the service, complete the following steps to import a key with the IBM Cloud console.

If you enable dual authorization settings for your Key Protect instance, keep in mind that any keys that you add to the service require an authorization from two users to delete keys.

Log in to the IBM Cloud console.
Go to Menu > Resource List to view a list of your resources.
From your IBM Cloud resource list, select your provisioned instance of Key Protect.
To import a key, click Add and select the Import your own key window.

Specify the key's details:

Table 1. Describes the Import your own key settings.
Setting	Description
Key type	The type of key that you would like to manage in Key Protect. Select the Root key button.
Name	A human-readable alias for easy identification of your key. Length must be within 2 - 90 characters (inclusive). To protect your privacy, ensure that the key name does not contain personally identifiable information (PII), such as your name or location. Note that key names do not need to be unique.
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. Ensure that the key material is 16, 24, or 32 bytes long, and corresponds to 128, 192, or 256 bits in length. The key must also be base64-encoded.
Key description	Optional. Descriptions are a useful way to add information about a key (for example, a phrase describing its purpose) in a way that isn't possible to do using an alias or its name. This description must be at least two characters and no more than 240, and cannot be changed later. To protect your privacy, do not use personal data, such as your name or location, as a description for your key.
Key alias	Optional. Key aliases are ways to describe a key that allow them to be identified and grouped beyond the limits of a display name. Keys can have up to five aliases.
Key ring	Optional. Key rings are groupings of keys that allow those groupings to be managed independently as needed. Every key must be a part of a key ring. If no key ring is selected, keys are placed in the `default` key ring. Note that to place the key you're creating in a key ring, you must have the Manager role over that key ring. For more information about roles, check out Managing user access.

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

If you know which key ring you want a key to be placed in, and you are a Manager of that key ring, you can also navigate to the Key rings panel, select ⋯ and click Add key to key ring. This will open the same panel you see by clicking Add on the Keys page with the Key rings variable filled in with the name of the key ring.

Importing root keys with the API

Import symmetric keys to Key Protect by making a POST call to the following endpoint.

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

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

Call the Key Protect API 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_name>",
                    "aliases": [alias_list],
                    "description": "<key_description>",
                    "expirationDate": "<expiration_date>",
                    "payload": "<key_material>",
                    "extractable": <key_type>
                }
            ]
        }'

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 Key Protect API
Variable	Description
region	Required. The region abbreviation, such as `us-south` or `eu-gb`, that represents the geographic area where your Key Protect instance resides. For more information, see Regional service endpoints.
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.
instance_ID	Required. The unique identifier that is assigned to your Key Protect service instance. For more information, see Retrieving an instance ID.
correlation_ID	The unique identifier that is used to track and correlate transactions.
return_preference	A header that alters server behavior for POST and DELETE operations. When you set the return_preference variable to return=minimal, the service returns only the key metadata, such as the key name and ID value, in the response entity-body. When you set the variable to return=representation, the service returns both the key material and the key metadata.
key_name	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.
alias_list	Optional. One or more unique, human-readable aliases assigned to your key. Important: To protect your privacy, do not store your personal data as metadata for your key. Each alias must be alphanumeric, case sensitive, and cannot contain spaces or special characters other than - or _. The alias cannot be a UUID and must not be a Key Protect reserved name: allowed_ip, key, keys, metadata, policy, policies. registration, registrations, ring, rings, rotate, wrap, unwrap, rewrap, version, versions.
key_description	Optional. An extended description of your key. 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`). The key will transition to the deactivated state within one hour past the key's expiration date. If the expirationDate attribute is omitted, the key does not expire.
key_material	Required. The base64-encoded key material, 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. Ensure that the key material meets the following requirements: A standard key can be up to 7,500 bytes in size. 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.

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.

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 Key Protect API.

Optional: Verify that the key was added by running the following call to browse the keys in your Key Protect 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>"

Base64-encoding your 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

Use this process to encrypt the contents of a key material in a file.

Download and install OpenSSL.
Base64-encode your key material string by running the following command:
```
openssl base64 -in <infile> -out <outfile>
```
Replace the variables in the example request according to the following table.

Table 2. 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. Ensure that the key is 16, 24, or 32 bytes long, corresponding to 128, 192, or 256 bits in length. The key must be base64-encoded.
outfile	The name of the file where your base64-encoded key material will be created once the command has run.

If you want to output the base64 material in the command line directly rather than a file, issue openssl enc -base64 <<< '<key_material_string>', where key_material_string is the key material input for your imported key.

Using OpenSSL to create and encode new key material

Use this process to create a random base64-encoded key material with a specific byte length. 32 bytes (256 bits) is recommended.

Download and install OpenSSL.
Base64-encode your key material string by running the following command:
```
openssl rand -base64 <byte_length>
```
Replace the variable in the example request according to the following table.

Table 3. Describes the variable that is needed to create and encode new key material.
Variable	Description
byte_length	The length of the key, measured in bytes. Acceptable byte lengths are 16, 24, or 32 bytes, corresponding to 128, 192, or 256 bits in length. The key must be base64-encoded.

Key Material Creation Examples

openssl rand -base64 16 will generate a 128-bit key material.
openssl rand -base64 24 will generate a 192-bit key material.
openssl rand -base64 32 will generate a 256-bit key material.

What's next

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 Key Protect API reference doc.