IBM Cloud Docs
Creating import tokens

Creating import tokens

You can enable the secure import of root key material to the cloud by first creating an import token for your Key Protect instance.

Import tokens are used to encrypt and securely bring root key material into Key Protect based on the policies that you specify. To learn more about importing your keys securely to the cloud, see Bringing your encryption keys to the cloud.

Creating an import token with the API

Create an import token that's associated with your Key Protect instance by making a POST call to the following endpoint.

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

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

  2. Set a policy for your import token by calling the Key Protect API.

    $ curl -X POST \
    "https://<region>.kms.cloud.ibm.com/api/v2/import_token" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>" \
    -H "content-type: application/json" \
    -d '{
            "expiration": <expiration_time>,
            "maxAllowedRetrievals": <use_count>
        }'

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

Table 1. Describes the variables that are needed to create an import token.
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.
expiration_time The time in seconds from the creation of a import token that determines how long it remains valid. The minimum value is 300 seconds (5 minutes), and the maximum value is 86400 (24 hours). The default value is 600 (10 minutes).
use_count The number of times that an import token can be retrieved within its expiration time before it is no longer accessible. The default value is 1. The maximum value is 500.

A successful POST api/v2/import_token request creates an import token for your Key Protect instance. The response body contains the metadata that is associated with your import token, such as its creation date and policy details. The following snippet shows example output.

You can only have 1 import token associated with your Key Protect instance at any given time. Any subsequent create import token requests will override the previous import token.

{
    "creationDate": "2019-04-08T16:58:29Z",
    "expirationDate": "2019-04-08T17:18:29Z",
    "maxAllowedRetrievals": 1,
    "remainingRetrievals": 1
}

Retrieving an import token with the API

Retrieve the import token that's associated with your Key Protect instance by making a GET call to the following endpoint.

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

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

  2. Retrieve the import token that is associated with your Key Protect instance by calling the Key Protect API.

    $ curl -X GET \
    "https://<region>.kms.cloud.ibm.com/api/v2/import_token" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>"

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

Table 2. Describes the variables that are needed to retrieve an import token 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.

A successful GET api/v2/import_token request retrieves the import token for your Key Protect instance. The response body contains the metadata that is associated with your import token, such as its creation date and policy details.

The retrieved import token can be reused to import one or more keys up until the date that the import token expires.

The following snippet shows example output with truncated values.

{
    "creationDate": "2019-04-08T16:58:29Z",
    "expirationDate": "2019-04-08T17:18:29Z",
    "maxAllowedRetrievals": 1,
    "remainingRetrievals": 0,
    "payload": "Rm91ciBzY29yZSBhbmQgc2V2ZW4geWVhcnMgYWdv",
    "nonce": "8zJE9pKVdXVe/nLb"
}

The response body also contains the public encryption key that you can use to encrypt a root key before you upload the key material to a Key Protect instance.

In the example, the payload value represents the public key that is associated with the import token. This value is base64 encoded. For extra security, Key Protect also provides a nonce value that is used to verify the originality of a key import request to the service. To learn more about how to use these values, check out Tutorial: Creating and importing encryption keys.

What's next