Skip to content

Latest commit

 

History

History
905 lines (745 loc) · 22.7 KB

cli-reference-039.md

File metadata and controls

905 lines (745 loc) · 22.7 KB
Raw
copyright lastupdated keywords subcollection
years
2017, 2020
2020-05-01
Key Protect CLI plug-in, CLI reference, version 0.3.9
key-protect

{:external: target="_blank" .external} {:important: .important} {:pre: .pre} {:screen: .screen} {:shortdesc: .shortdesc} {:tip: .tip}

CLI reference version 0.3.9

{: #cli-reference-039}

This document is specific to the key-protect plugin, version 0.3.9. {: important}

  • The latest CLI Reference, version 0.4.0, is found here.

Verify the installed plug-in version.

$ ibmcloud plugin list
Listing installed plug-ins...

Plugin Name   Version   Status
key-protect   0.3.9

{: pre}

You can use the {{site.data.keyword.keymanagementserviceshort}} CLI plug-in to manage keys in your instance of {{site.data.keyword.keymanagementserviceshort}}. {: shortdesc}

To install the CLI plug-in, see Setting up the CLI.

When you log in to the {{site.data.keyword.cloud_notm}} CLI{: external}, you're notified when updates are available. Be sure to keep your CLI up-to-date so that you can use the commands and flags that are available for the {{site.data.keyword.keymanagementserviceshort}} CLI plug-in. {: tip}

ibmcloud kp commands

{: #ibmcloud-kp-commands-039}

You can specify one of the following commands.

Command Description
kp create Create a key
kp list Retrieve a list of keys
kp get Retrieve a key
kp wrap Wrap a data encryption key
kp unwrap Unwrap a data encryption key
kp rotate Rotate a root key
kp delete Delete a key
{: caption="Table 1. Commands for managing encryption keys" caption-side="top"}
{: #table-1}
{: tab-title="Keys"}
{: class="comparison-tab-table"}
{: row-headers}
Command Description
kp policy set Create or replace a key policy
kp policy get Retrieve details about a key policy
{: caption="Table 2. Commands for managing key policies" caption-side="top"}
{: #table-2}
{: tab-title="Policies"}
{: class="comparison-tab-table"}
{: row-headers}
Command Description
kp import-token create Create an import token
kp import-token get Retrieve an import token
kp import-token encrypt-nonce Encrypt the nonce that is generated by {{site.data.keyword.keymanagementserviceshort}}
kp import-token encrypt-key Encrypt the key that you want to import to the service
{: caption="Table 3. Commands for managing import tokens" caption-side="top"}
{: #table-3}
{: tab-title="Import tokens"}
{: class="comparison-tab-table"}
{: row-headers}

kp create

{: #kp-create-039}

Create a root key in the {{site.data.keyword.keymanagementserviceshort}} service instance that you specify.

ibmcloud kp create KEY_NAME -i $INSTANCE_ID
                           [-k, --key-material KEY_MATERIAL]
                           [-s, --standard-key]
                           [--output FORMAT]

{: pre}

Required parameters

{: #create-req-params}

KEY_NAME
A unique, human-readable alias to assign to your key.
-i, --instance-id
The {{site.data.keyword.cloud_notm}} instance ID that identifies your {{site.data.keyword.keymanagementserviceshort}} service instance.

Optional parameters

{: #create-opt-params}

-k, --key-material
The base64 encoded key material that you want to store and manage in the service. To import an existing key, provide a 256-bit key. To generate a new key, omit the --key-material parameter.
-n, --encrypted-nonce

Used with import tokens. The encrypted nonce value that verifies your request to import a key to {{site.data.keyword.keymanagementserviceshort}}. This value must be encrypted by using the key material that you want to import to the service.

To retrieve a nonce, use ibmcloud kp import-token get. Then, encrypt the value by running ibmcloud kp import-token encrypt-nonce.

-v, --iv

Used with import tokens. The initialization vector (IV) that is generated when you encrypt a nonce. The IV value is required to decrypt the encrypted nonce value that you provide when you make a key import request to the service.

To generate an IV, encrypt the nonce by running ibmcloud kp import-token encrypt-nonce.

-s, --standard-key
Set the parameter only if you want to create a [standard key](/docs/key-protect?topic=key-protect-envelope-encryption#key-types). To create a root key, omit the --standard-key parameter.
-o, --output
Set the CLI output format. By default, all commands print in table format. To change the output format to JSON, use --output json.

Usage examples

{: #create-examples}

Create a key

{: #create-key-example}

$ ibmcloud kp create my-new-root-key -i $INSTANCE_ID
SUCCESS

Key ID                                 Key Name
3df42bc2-a991-41cb-acc2-3f9eab64a63f   my-new-root-key

{: screen}

Import a key that you generate on-premises

{: #import-key-example}

$ ibmcloud kp create my-imported-root-key -i $INSTANCE_ID -k $KEY_MATERIAL
SUCCESS

Key ID                                 Key Name
3df42bc2-a991-41cb-acc2-3f9eab64a63f   my-imported-root-key

{: screen}

Import a key by using an import token

{: #import-key-with-import-token-example}

$ ibmcloud kp create my-imported-root-key -i $INSTANCE_ID -k $ENCRYPTED_KEY -n $NONCE -iv $IV
SUCCESS

Key ID                                 Key Name
3df42bc2-a991-41cb-acc2-3f9eab64a63f   my-encrypted-root-key

{: screen}

See the ibmcloud kp import-token subcommands for information about using an import token to upload a key to {{site.data.keyword.keymanagementserviceshort}}. {: tip}

kp list

{: #kp-list-039}

List the last 200 keys that are available in your {{site.data.keyword.keymanagementserviceshort}} service instance.

ibmcloud kp list -i $INSTANCE_ID

{: pre}

$ ibmcloud kp list -i $KP_INSTANCE_ID
Retrieving keys...

SUCCESS

Key ID                                 Key Name
3df42bc2-a991-41cb-acc2-3f9eab64a63f   sample-root-key
92e5fab3-00e8-40e9-8a2d-864de334b043   sample-imported-root-key

{: screen}

Required parameters

{: #list-req-params}

-i, --instance-id
The {{site.data.keyword.cloud_notm}} instance ID that identifies your {{site.data.keyword.keymanagementserviceshort}} service instance.

Optional parameters

{: #list-opt-params}

-o, --output
Set the CLI output format. By default, all commands print in table format. To change the output format to JSON, use --output json.

kp get

{: #kp-get-039}

Retrieve details about a key, such as the key metadata and key material.

If the key was designated as a root key, the system cannot return the key material for that key.

ibmcloud kp get KEY_ID -i $INSTANCE_ID

{: pre}

$ ibmcloud kp get 3df42bc2-a991-41cb-acc2-3f9eab64a63f -i $KP_INSTANCE_ID
Grabbing info for key id: 3df42bc2-a991-41cb-acc2-3f9eab64a63f...

SUCCESS

Key ID                                 Key Name          Description     Creation Date                   Expiration Date
3df42bc2-a991-41cb-acc2-3f9eab64a63f   sample-root-key   A sample key.   2019-04-02 16:42:47 +0000 UTC   Key does not expire

{: screen}

Required parameters

{: #get-req-params}

KEY_ID
The ID of the key that you want to retrieve. To retrieve a list of your available keys, run the [kp list](#kp-list-039) command.
-i, --instance-id
The {{site.data.keyword.cloud_notm}} instance ID that identifies your {{site.data.keyword.keymanagementserviceshort}} service instance.

Optional parameters

{: #get-opt-params}

-o, --output
Set the CLI output format. By default, all commands print in table format. To change the output format to JSON, use --output json.

kp wrap

{: #kp-wrap-039}

Wrap a data encryption key by using a root key that is stored in the {{site.data.keyword.keymanagementserviceshort}} service instance that you specify.

ibmcloud kp wrap KEY_ID -i $INSTANCE_ID
                       [-a, --aad ADDITIONAL_DATA]
                       [-p, --plaintext DATA_KEY]

{: pre}

Required parameters

{: #wrap-req-params}

KEY_ID
The ID of the root key that you want to use for wrapping.
-i, --instance-id
The {{site.data.keyword.cloud_notm}} instance ID that identifies your {{site.data.keyword.keymanagementserviceshort}} service instance.

Optional parameters

{: #wrap-opt-params}

-a, --aad
The additional authentication data (AAD) that is used to further secure a key. If provided on wrap must be provided on unwrap.
-p, --plaintext
The base64 encoded data encryption key (DEK) that you want to manage and protect. To import an existing key, provide a 256-bit key. To generate and wrap a new DEK, omit the --plaintext parameter.
-o, --output
Set the CLI output format. By default, all commands print in table format. To change the output format to JSON, use --output json.

kp unwrap

{: #kp-unwrap-039}

Unwrap a data encryption key by using a root key that is stored in your {{site.data.keyword.keymanagementserviceshort}} service instance.

ibmcloud kp unwrap KEY_ID CIPHERTEXT_FROM_WRAP -i $INSTANCE_ID
                          [-a, --aad ADDITIONAL_DATA, ..]

{: pre}

Required parameters

{: #unwrap-req-params}

KEY_ID
The ID of the root key that you used for the initial wrap request.
CIPHERTEXT_FROM_WRAP
The encrypted data key that was returned during the initial wrap operation.
-i, --instance-id
The {{site.data.keyword.cloud_notm}} instance ID that identifies your {{site.data.keyword.keymanagementserviceshort}} service instance.

Optional parameters

{: #unwrap-opt-params}

-a, --aad

The additional authentication data (AAD) that was used to further secure a key. You can provide up to 255 strings, each delimited by a comma. If you supplied AAD on wrap, you must specify the same AAD on unwrap.

Important: The {{site.data.keyword.keymanagementserviceshort}} service does not save additional authentication data. If you supply AAD, save the data to a secure location to ensure that you can access and provide the same AAD during subsequent unwrap requests.

-o, --output
Set the CLI output format. By default, all commands print in table format. To change the output format to JSON, use --output json.

kp rotate

{: #kp-rotate-039}

Rotate a root key that is stored in your {{site.data.keyword.keymanagementserviceshort}} service.

ibmcloud kp rotate KEY_ID -i $INSTANCE_ID
                         [-k, --key-material KEY_MATERIAL]

{: pre}

$ ibmcloud kp rotate 3df42bc2-a991-41cb-acc2-3f9eab64a63f -i $KP_INSTANCE_ID
Rotating root key...

SUCCESS

{: screen}

Required parameters

{: #rotate-req-params}

KEY_ID
The ID of the root key that you want to rotate.
-i, --instance-id
The {{site.data.keyword.cloud_notm}} instance ID that identifies your {{site.data.keyword.keymanagementserviceshort}} service instance.

Optional parameters

{: #rotate-opt-params}

-k, --key-material
The base64 encoded key material that you want to use for rotating an existing root key. To rotate a key that was initially imported into the service, provide a new 256-bit key. To rotate a key that was initially generated in {{site.data.keyword.keymanagementserviceshort}}, omit the --key-material parameter.
-o, --output
Set the CLI output format. By default, all commands print in table format. To change the output format to JSON, use --output json.

kp delete

{: #kp-delete-039}

Delete a key that is stored in your {{site.data.keyword.keymanagementserviceshort}} service.

ibmcloud kp delete KEY_ID -i $INSTANCE_ID

{: pre}

$ ibmcloud kp delete 584fb0d9-dec2-47b8-bde5-50f05fd66261 -i $KP_INSTANCE_ID
Deleting key: 584fb0d9-dec2-47b8-bde5-50f05fd66261, from instance: 98d39ab8-cf44-4517-9583-2ad05c7e9bd5...

SUCCESS

Deleted Key
584fb0d9-dec2-47b8-bde5-50f05fd66261

{: screen}

Required parameters

{: #delete-req-params}

KEY_ID
The ID of the key that you want to delete. To retrieve a list of your available keys, run the [kp list](#kp-list-039) command.
-i, --instance-id
The {{site.data.keyword.cloud_notm}} instance ID that identifies your {{site.data.keyword.keymanagementserviceshort}} service instance.

kp policy set

{: #kp-policy-set-039}

Create or replace the policy that is associated with the root key that you specify.

ibmcloud kp policy set KEY_ID -i $INSTANCE_ID --set-type POLICY_TYPE
                             [-p --policy INTERVAL]

{: pre}

Required parameters

{: #policy-set-req-params}

KEY_ID
The ID of the key that you want to query. To retrieve a list of your available keys, run the [kp list](#kp-list-039) command.
--set-type
Specify the type of policy that you want to set. To set a rotation policy, use --set-type rotation.
-i, --instance-id
The {{site.data.keyword.cloud_notm}} instance ID that identifies your {{site.data.keyword.keymanagementserviceshort}} service instance.

Optional parameters

{: #policy-set-opt-params}

-p, --policy
Specify the rotation time interval (in months) for a key. The default value is 1.
-o, --output
Set the CLI output format. By default, all commands print in table format. To change the output format to JSON, use --output json.

kp policy get

{: #kp-policy-get-039}

Retrieve details about a key policy, such as the key's automatic rotation interval.

ibmcloud kp policy get KEY_ID -i $INSTANCE_ID

{: pre}

Required parameters

{: #policy-get-req-params}

KEY_ID
The ID of the key that you want to query. To retrieve a list of your available keys, run the [kp list](#kp-list-039) command.
-i, --instance-id
The {{site.data.keyword.cloud_notm}} instance ID that identifies your {{site.data.keyword.keymanagementserviceshort}} service instance.

Optional parameters

{: #policy-get-opt-params}

-o, --output
Set the CLI output format. By default, all commands print in table format. To change the output format to JSON, use --output json.

kp import-token create

{: #kp-import-token-create-039}

Create an import token in the {{site.data.keyword.keymanagementserviceshort}} service instance that you specify.

ibmcloud kp import-token create -i $INSTANCE_ID
                               [-e, --expiration=TIME_IN_SECONDS]
                               [-m, --max-retrievals=USE_COUNT]

{: pre}

$ ibmcloud kp import-token create -i $INSTANCE_ID --expiration=300 --max-retrievals=3
SUCCESS

Created                         Expires                         Max Retrievals   Remaining Retrievals
2019-08-05 19:56:11 +0000 UTC   2019-08-05 20:01:11 +0000 UTC   3                3

{: screen}

Required parameters

{: #import-token-create-req-params}

-i, --instance-id
The {{site.data.keyword.cloud_notm}} instance ID that identifies your {{site.data.keyword.keymanagementserviceshort}} service instance.

Optional parameters

{: #import-token-create-opt-params}

-e, --expiration

Specify an expiration time (in seconds) for an import token. This value determines how long the import token and its associated public key remain valid for operations.

The minimum value is 300 seconds (5 minutes), and the maximum value is 86400 seconds (24 hours). The default value is 600 seconds (10 minutes).

-m, --max-retrievals
Set the use count for the import token. This value determines the number of times that the import token can be retrieved within its expiration time before it is no longer accessible. The default value is 1.

kp import-token get

{: #kp-import-token-get-039}

Retrieve the import token that is associated with your service instance.

The import token contains a public encryption key and a nonce. Provide the retrieved public key and nonce as arguments for ibmcloud kp import-token encrypt-nonce and ibmcloud kp import-token encrypt-key.

ibmcloud kp import-token get -i $INSTANCE_ID

{: pre}

$ ibmcloud kp import-token get -i $INSTANCE_ID
SUCCESS

{
  "nonce": "EE1sUNE4BZCTU3q/",
  "payload": "Rm91ciBzY29yZSBhbmQgc2V2ZW4geWVhcnMgYWdv"
}

{: screen}

Required parameters

{: #import-token-get-req-params}

-i, --instance-id
The {{site.data.keyword.cloud_notm}} instance ID that identifies your {{site.data.keyword.keymanagementserviceshort}} service instance.

kp import-token encrypt-nonce

{: #kp-import-token-encrypt-nonce-039}

Encrypt the nonce that is distributed by {{site.data.keyword.keymanagementserviceshort}} with the key material that you want to import to the service. Then, provide the retrieved encrypted nonce and IV values when you run ibmcloud kp create to import the key.

ibmcloud kp import-token encrypt-nonce -i $INSTANCE_ID

{: pre}

$ ibmcloud kp import-token encrypt-nonce -i $INSTANCE_ID
                                        [-k --key $KEY_MATERIAL]
                                        [-n --nonce $NONCE]
SUCCESS

Encrypted Nonce                            IV
sw2Bdq2NT9yEjkf6H+4JHtDhciZMJKhxoH9jeA==   OLro3ZmEbaFTCpT+

{: screen}

Required parameters

{: #encrypt-nonce-req-params}

-i, --instance-id
The {{site.data.keyword.cloud_notm}} instance ID that identifies your {{site.data.keyword.keymanagementserviceshort}} service instance.

Optional parameters

{: #encrypt-nonce-opt-params}

-k, --key
The base64 encoded key material that you want to store and manage in the service.
-n, --nonce
The nonce that was distributed by {{site.data.keyword.keymanagementserviceshort}}. The value is base64 encoded. To retrieve a nonce, use ibmcloud kp import-token get.

kp import-token encrypt-key

{: #kp-import-token-encrypt-key-039}

Encrypt the key material that you want to import to {{site.data.keyword.keymanagementserviceshort}} by using the public key that's associated with your service instance. Then, provide the retrieved encrypted key when you run ibmcloud kp create to import the key to the service.

ibmcloud kp import-token encrypt-key -i $INSTANCE_ID

{: pre}

$ ibmcloud kp import-token encrypt-key -i $INSTANCE_ID
                                      [-k --key $KEY_MATERIAL]
                                      [-p --pubkey $PUBLIC_KEY]
SUCCESS

Encrypted Key
Ic6OH8dhjnqoMzBvItxS3wlyiziIs2C9U+...

{: screen}

Required parameters

{: #encrypt-key-req-params}

-i, --instance-id
The {{site.data.keyword.cloud_notm}} instance ID that identifies your {{site.data.keyword.keymanagementserviceshort}} service instance.

Optional parameters

{: #encrypt-key-opt-params}

-k, --key
The base64 encoded key material that you want to store and manage in the service.
-p, --pubkey
The base64 encoded public encryption key that was distributed by {{site.data.keyword.keymanagementserviceshort}}. To retrieve a public key, use ibmcloud kp import-token get.