create-standard-keys.md

copyright	lastupdated	keywords	subcollection
years 2017, 2020	2020-03-19	create standard encryption key, create secret, persist secret, create encryption key, standard encryption key API examples	key-protect

{:shortdesc: .shortdesc} {:screen: .screen} {:pre: .pre} {:table: .aria-labeledby="caption"} {:external: target="_blank" .external} {:codeblock: .codeblock} {:tip: .tip} {:note: .note} {:important: .important} {:term: .term}

Creating standard keys

{: #create-standard-keys}

You can create a standard encryption key with the {{site.data.keyword.keymanagementserviceshort}} GUI, or programmatically with the {{site.data.keyword.keymanagementserviceshort}} API. {: shortdesc}

Creating standard keys in the console

{: #create-standard-key-gui}

After you create an instance of the service, complete the following steps to create a standard key in the {{site.data.keyword.cloud_notm}} console.

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

1. Log in to the {{site.data.keyword.cloud_notm}} console{: external}.

2. Go to Menu > Resource List to view a list of your resources.

3. From your {{site.data.keyword.cloud_notm}} resource list, select your provisioned instance of {{site.data.keyword.keymanagementserviceshort}}.

4. To create a new key, click Add key and select the Create a key window.

   Specify the key's details:

   Table 1. Describes the Create a key settings

   Setting	Description
   Name	A human-readable alias for easy identification of your key. Length must be within 2 - 90 characters. To protect your privacy, ensure that the key name does not contain personally identifiable information (PII), such as your name or location.
   Key type	The [type of key](/docs/key-protect?topic=key-protect-envelope-encryption#key-types) that you would like to manage in {{site.data.keyword.keymanagementserviceshort}}. From the list of key types, select Standard key.

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

Creating standard keys with the API

{: #create-standard-key-api}

Create a standard key by making a POST call to the following endpoint.

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

{: codeblock}

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

2. Call the {{site.data.keyword.keymanagementserviceshort}} API{: external} 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' \
     -H 'correlation-id: <correlation_ID>' \
     -H 'prefer: <return_preference>' \
     -d '{
       "metadata": {
         "collectionType": "application/vnd.ibm.kms.key+json",
         "collectionTotal": 1
       },
       "resources": [
         {
           "type": "application/vnd.ibm.kms.key+json",
           "name": "<key_alias>",
           "description": "<key_description>",
           "expirationDate": "<YYYY-MM-DDTHH:MM:SS.SSZ>",
           "extractable": <key_type>
         }
       ]
     }'
   

   {: codeblock}

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

   Table 2. Describes the variables that are needed to add a standard 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](/docs/key-protect?topic=key-protect-regions#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](/docs/key-protect?topic=key-protect-retrieve-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](/docs/key-protect?topic=key-protect-retrieve-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_alias	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.
   key_description	An extended description of your key. To protect your privacy, do not store your personal data as metadata for your key.
   YYYY-MM-DD HH:MM:SS.SS	The date and time that the key expires in the system, in RFC 3339 format. If the expirationDate attribute is omitted, the key does not expire.
   key_type	A boolean value that determines whether the key material can leave the service. When you set the extractable attribute to true, the service creates a standard key that you can store in your apps or services.

   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.For more examples of PII, see section 2.2 of the NIST Special Publication 800-122{: external}. {: important}

   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 {{site.data.keyword.keymanagementserviceshort}} API.

3. Optional: Verify that the key was created by running the following call to get the keys in your {{site.data.keyword.keymanagementserviceshort}} service instance.

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

   {: codeblock}

What's next

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

• To find out more about programmatically managing your keys, check out the {{site.data.keyword.keymanagementserviceshort}} API reference doc{: external}.