Creating import tokens

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://api.<region>.hs-crypto.cloud.ibm.com:<port>/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://api.<region>.hs-crypto.cloud.ibm.com:<port>/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://api.<region>.hs-crypto.cloud.ibm.com:<port>/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://api.<region>.hs-crypto.cloud.ibm.com:<port>/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.