Skip to content

Latest commit

 

History

History
110 lines (88 loc) · 5.55 KB

create-transport-keys.md

File metadata and controls

110 lines (88 loc) · 5.55 KB
copyright lastupdated keywords subcollection
years
2017, 2019
2019-04-03
create transport encryption key, secure import, key-wrapping key, transport key API examples
key-protect

{:shortdesc: .shortdesc} {:codeblock: .codeblock} {:screen: .screen} {:new_window: target="_blank"} {:pre: .pre} {:tip: .tip} {:note: .note} {:important: .important}

Creating a transport key

{: #create-transport-keys}

You can enable the secure import of root key material to the cloud by first creating a transport encryption key for your {{site.data.keyword.keymanagementserviceshort}} service instance. {: shortdesc}

Transport keys are used to encrypt and securely import root key material into {{site.data.keyword.keymanagementserviceshort}} 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.

Transport keys are currently a beta feature. Beta features can change at any time, and future updates might introduce changes that are incompatible with the latest version. {: important}

Creating a transport key with the API

{: #create-transport-key-api}

Create a transport key that's associated with your {{site.data.keyword.keymanagementserviceshort}} service instance by making a POST call to the following endpoint.

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

{: codeblock}

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

  2. Set a policy for your transport key by calling the {{site.data.keyword.keymanagementserviceshort}} API External link icon{: new_window}.

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

    {: codeblock}

    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 {{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.
    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.
    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.
    expiration_time

    The time in seconds from the creation of a transport key that determines how long the key 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 a transport key can be retrieved within its expiration time before it is no longer accessible. The default value is 1.

    A successful POST api/v2/lockers request creates a transport key for your service instance and returns its ID value, along with other metadata. The ID is a unique identifier that is associated to your transport key and is used for subsequent calls to the {{site.data.keyword.keymanagementserviceshort}} API.

  3. Optional: Verify that the transport key was created by running the following call to retrieve metadata about your service instance.

    curl -X GET \
  https://<region>.kms.cloud.ibm.com/api/v2/lockers \
  -H 'accept: application/vnd.ibm.collection+json' \
  -H 'authorization: Bearer <IAM_token>' \
  -H 'bluemix-instance: <instance_ID>'

    {: codeblock}

What's next

{: #create-transport-key-next-steps}