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 IBM Cloud® Hyper Protect Crypto Services service instance.

Import tokens are used to encrypt and securely bring root key material into Hyper Protect Crypto Services 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 Hyper Protect Crypto Services service instance by making a POST call to the following endpoint.

https://<instance_ID>.api.<region>.hs-crypto.appdomain.cloud/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 management service API.

    curl -X POST \
      https://<instance_ID>.api.<region>.hs-crypto.appdomain.cloud/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 needed to create an import token with the API
    Variable Description
    region Required. The region abbreviation, such as us-south or au-syd, that represents the geographic area where your Hyper Protect Crypto Services service instance resides. For more information, see Regional service endpoints.
    port Required. The port number of the API endpoint.
    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 Hyper Protect Crypto Services service instance. For more information, see Retrieving an instance ID.
    expiration_time The time in seconds from the creation of an 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 the expiration time before it is no longer accessible. The default value is 1.

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

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

Creating an import token with the CLI

Complete the following steps to create an import token by using the Key Protect CLI, which is integrated in Hyper Protect Crypto Services:

  1. Set up the Key Protect CLI.

  2. Create an import token with the following command:

    ibmcloud kp import-token create
    

    You can find more parameters for this command in the Key Protect CLI reference.

Retrieving an import token with the API

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

https://<instance_ID>.api.<region>.hs-crypto.appdomain.cloud/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 service instance by calling the key management service API.

    curl -X GET \
      https://<instance_ID>.api.<region>.hs-crypto.appdomain.cloud/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 1. Describes the variables needed to retrieve an import token with the key management service API
    Variable Description
    region Required. The region abbreviation, such as us-south or au-syd, that represents the geographic area where your Hyper Protect Crypto Services service instance resides. For more information, see Regional service endpoints.
    port Required. The port number of the API endpoint.
    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 Hyper Protect Crypto Services service instance. For more information, see Retrieving an instance ID.

    A successful GET api/v2/import_token request retrieves the import token for your service instance. The response body contains the metadata that is associated with your import token, such as the creation date and policy details. The following snippet shows an example output with truncated values.

    {
      "creationDate": "2019-04-08T16:58:29Z",
      "expirationDate": "2019-04-08T17:18:29Z",
      "maxAllowedRetrievals": 1,
      "remainingRetrievals": 0,
      "payload": "MIICIjANBgkqhkiG...",
      "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 Hyper Protect Crypto Services service 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, Hyper Protect Crypto Services 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.

Retrieving an import token with the CLI

Complete the following steps to retrieve an import token by using the Key Protect CLI, which is integrated in Hyper Protect Crypto Services:

  1. Set up the Key Protect CLI.

  2. Retrieve an import token with the following command:

    ibmcloud kp import-token show
    

    You can find more parameters for this command in the Key Protect CLI reference.

What's next