Key Protect CLI Reference

Example 1

This example enables the dual authorization delete policy.

# enable the instance dual authorization policy
$ ibmcloud kp instance policy-update dual-auth-delete --enable

Updating instance policy...
OK

# list the instance policies
$ ibmcloud kp instance policies --output json

[
  {
    "createdBy": "user id ...<redacted>...",
    "creationDate": "2020-06-22T18:45:14Z",
    "lastUpdated": "2020-06-22T18:45:14Z",
    "updatedBy": "user id ...<redacted>...",
    "policy_type": "dualAuthDelete",
    "policy_data": { "enabled": true
    }
  }
]

# disable the instance dual authorization policy
$ ibmcloud kp instance policy-update dual-auth-delete --disable

Updating instance policy...
OK

# list the instance policies
$ ibmcloud kp instance policies --output json

[
  {
    "createdBy": "user id ...<redacted>...",
    "creationDate": "2020-06-22T18:45:14Z",
    "lastUpdated": "2020-06-22T18:51:33Z",
    "updatedBy": "user id ...<redacted>...",
    "policy_type": "dualAuthDelete",
    "policy_data": { "enabled": false
    }
  }
]

Example 2

This example enables the dual authorization delete policy and creates a new key to show how a new key inherits the instance policy.

Disabling the dual authorization policy for an instance does not change the policy for existing keys. The instance policy applies to new keys created after the policy is updated.

# enable the instance dual authorization policy
$ ibmcloud kp instance policy-update dual-auth-delete --enable

Updating instance policy...
OK

# create a new key
$ ibmcloud kp key create my-protected-key

Creating key: 'my-protected-key', in instance: 'a192d603-0b8d-452f-aac3-f9e1f95e7411'...
OK
Key ID                                 Key Name
6a8a129b-0cd4-4667-ba57-b355a125a7ca   my-protected-key

# list the policies for the key - dual-auth-delete is
# enabled because the key inherits the instance policy
$ ibmcloud kp key policies 6a8a129b-0cd4-4667-ba57-b355a125a7ca --output json

[
  {
    "createdBy": "user id ...<redacted>...",
    "creationDate": "2020-06-22T19:13:00Z",
    "crn": "crn:v1:bluemix:public:kms:us-south:a/ea998d3389c3473aa0987652b46fb146:a192d603-0b8d-452f-aac3-f9e1f95e7411:policy:2427dbde-6cff-41eb-8b5a-ff26b038cafc",
    "lastUpdateDate": "2020-06-22T19:13:00Z",
    "updatedBy": "user id ...<redacted>...",
    "dualAuthDelete": { "enabled": true
    }
  }
]

# attempt to delete the key - this fails
$ ibmcloud kp key delete 6a8a129b-0cd4-4667-ba57-b355a125a7ca

Deleting key: 6a8a129b-0cd4-4667-ba57-b355a125a7ca, from instance: a192d603-0b8d-452f-aac3-f9e1f95e7411...
FAILED
kp.Error:
    correlation_id='8ad33eb2-7bbf-4b7a-a02e-221959920342',
    msg='Conflict: 1 prior authorization(s) are required for deletion: Key could not be deleted. Please see "reasons" for more details.',
    reasons='[AUTHORIZATIONS_NOT_MET: Number of authorizations required to delete is not met -
        FOR_MORE_INFO_REFER: https://cloud.ibm.com/apidocs/key-protect]'

# disable the instance dual authorization policy
$ ibmcloud kp instance policy-update dual-auth-delete --disable

Updating instance policy...
OK

# attempt to delete the key - this fails because the key policy
# does not change when the instance policy is updated
$ ibmcloud kp key delete 6a8a129b-0cd4-4667-ba57-b355a125a7ca

Deleting key: 6a8a129b-0cd4-4667-ba57-b355a125a7ca, from instance: a192d603-0b8d-452f-aac3-f9e1f95e7411...
FAILED
kp.Error:
    correlation_id='cbc0d18b-a816-45ab-af6a-b8e18dc3e628',
    msg='Conflict: 1 prior authorization(s) are required for deletion: Key could not be deleted. Please see "reasons" for more details.',
    reasons='[AUTHORIZATIONS_NOT_MET: Number of authorizations required to delete is not met -
    FOR_MORE_INFO_REFER: https://cloud.ibm.com/apidocs/key-protect]'

Example

Create a key alias.

# create a key alias
$ ibmcloud kp key alias-create 24203f96-b134-440e-981a-a24f2d432256 my-alias

Creating key: 'my-root-key', in instance: '390086ac-76fa-4094-8cf3-c0829bd69526'...
OK
Key ID                                 Key Alias
24203f96-b134-440e-981a-a24f2d432256   my-alias

Example 1

Create a root key.

# create a root key
$ ibmcloud kp key create my-root-key

Creating key: 'my-root-key', in instance: '390086ac-76fa-4094-8cf3-c0829bd69526'...
OK
Key ID                                 Key Name
24203f96-b134-440e-981a-a24f2d432256   my-root-key

Example 2

Create a root key and show the JSON output.

# create a root key
$ ibmcloud kp key create my-root-key --output json

{
    "id": "24203f96-b134-440e-981a-a24f2d432256",
    "name": "my-root-key",
    "type": "application/vnd.ibm.kms.key+json",
    "extractable": false,
    "state": 1,
    "crn": "crn:v1:bluemix:public:kms:us-south:a/ea998d3389c3473aa0987652b46fb146:390086ac-76fa-4094-8cf3-c0829bd69526:key:24203f96-b134-440e-981a-a24f2d432256"
}

Example 3

Create a root key from a base64-encoded value.

# create a random, base64-encoded, 32-byte key material
$ KEY_MATERIAL=$(openssl rand -base64 32)

# create a root key from a base64-encoded value
$ ibmcloud kp key create my-base64-root-key -k $KEY_MATERIAL

Creating key: 'my-base64-root-key', in instance: '390086ac-76fa-4094-8cf3-c0829bd69526'...
OK
Key ID                                 Key Name
5f9eef2d-53b4-42e8-8b56-c2970255210a   my-base64-root-key

Example 4

Create a root key using an import token.

# create an import token that expires in 5 minutes and allows 10 retrievals
$ ibmcloud kp import-token create -e 300 -m 10

# create a random, base64-encoded, 32-byte key material
$ KEY_MATERIAL=$(openssl rand -base64 32)

# extract the nonce that was created by the "kp import-token create" command
$ NONCE=$(ibmcloud kp import-token show | jq -r '.["nonce"]')

# extract the public key that was created by the "kp import-token create" command
$ PUBLIC_KEY=$(ibmcloud kp import-token show | jq -r '.["payload"]')

# encrypt the key material using the public key
$ ibmcloud kp import-token key-encrypt -k $KEY_MATERIAL -p $PUBLIC_KEY

Encrypted Key
qT1pyiS1Sivbmmt4doTtfZC4XuLazk7u ...<redacted>... +a/6EqeAamo/9vo=

# capture the encrypted key material
$ ENCRYPTED_KEY=qT1pyiS1Sivbmmt4doTtfZC4XuLazk7u ...<redacted>... +a/6EqeAamo/9vo=

# encrypt the nonce
$ ibmcloud kp import-token nonce-encrypt -k $KEY_MATERIAL -n $NONCE

Encrypted Nonce                            IV
fR8uRvbrKIm9y/LCq9p6pwFBXbF864q/bw5meQ==   efQgA8xBeyuBy39D

# capture the encrypted nonce and the initialization vector (IV)
$ ENCRYPTED_NONCE=fR8uRvbrKIm9y/LCq9p6pwFBXbF864q/bw5meQ==
$ IV=efQgA8xBeyuBy39D

# create a root key using an import token, provide an encrypted key, nonce, and initialization vector (IV)
$ ibmcloud kp key create my-imported-root-key -k $ENCRYPTED_KEY -n $ENCRYPTED_NONCE -v $IV

Creating key: 'my-imported-root-key', in instance: '390086ac-76fa-4094-8cf3-c0829bd69526'...
OK
Key ID                                 Key Name
4241a9b3-0ee0-4cfd-b0f3-fd80505fb675   my-imported-root-key

Example 5

Create a standard key.

# create a standard key
$ ibmcloud kp key create my-standard-key -s

Creating key: 'my-standard-key', in instance: '390086ac-76fa-4094-8cf3-c0829bd69526'...
OK
Key ID                                 Key Name
12d3f3a4-aea5-4832-8339-fa14dbffd935   my-standard-key

Example 6

Create a standard key, which is used as a vault for credentials.

Any base64-encoded string can be imported as a standard key. This example shows how to store credentials, not just encryption keys, in Key Protect.

Standard keys can be up to 7,500 bytes in size before base64-encoding.

# create a file with your credentials
$ cat credentials.json

{
    "host": "localhost",
    "database": "dev-backup",
    "username": "my-username",
    "password": "my-password"
}

# encode the credentials (or any string) to a base64 string
$ ENCODED=$(base64 -i credentials.json)

$ echo $ENCODED

ewoJImhvc3QiOiAibG9jYWxob3N0IiwK...<redacted>...cGFzc3dvcmQiCn0K

# create a new key that contains the base64-encoded credentials
$ ibmcloud kp key create credentials-key -i $KP_INSTANCE_ID --key-material $ENCODED --standard-key --output json

# OR... CAPTURE THE KEY_ID
$ KEY_ID=$(ibmcloud kp key create credentials-key -i $KP_INSTANCE_ID --key-material $ENCODED --standard-key --output json | jq -r '.["id"]')

{
    "id": "8480e26f-3add-4fff-bca7-8cf908894b7c",
    "name": "credentials-key",
    "type": "application/vnd.ibm.kms.key+json",
    "extractable": true,
    "state": 1,
    "crn": "crn:v1:bluemix:public:kms:us-south:a/ea998d3389c3473aa0987652b46fb146:a192d603-0b8d-452f-aac3-f9e1f95e7411:key:8480e26f-3add-4fff-bca7-8cf908894b7c",
    "deleted": false
}

# retrieve the base64-encoded payload
$ ibmcloud kp key show $KEY_ID --output json

# OR... CAPTURE THE PAYLOAD
$ PAYLOAD=$(ibmcloud kp key show $KEY_ID --output json | jq -r '.["payload"]')

{
    "id": "8480e26f-3add-4fff-bca7-8cf908894b7c",
    "name": "credentials-key",
    "type": "application/vnd.ibm.kms.key+json",
    "algorithmType": "AES",
    "createdBy": "user id ...<redacted>...",
    "creationDate": "2020-08-18T16:13:08Z",
    "lastUpdateDate": "2020-08-18T16:13:08Z",
    "extractable": true,
    "payload": "ewoJImhvc3QiOiAibG9jYWxob3N0IiwKCSJkYXRhYmFzZSI6ICJkZXYtYmFja3VwIiwKCSJ1c2VybmFtZSI6ICJteS11c2VybmFtZSIsCgkicGFzc3dvcmQiOiAibXktcGFzc3dvcmQiCn0=",
    "state": 1,
    "crn": "crn:v1:bluemix:public:kms:us-south:a/ea998d3389c3473aa0987652b46fb146:a192d603-0b8d-452f-aac3-f9e1f95e7411:key:8480e26f-3add-4fff-bca7-8cf908894b7c",
    "deleted": false,
    "dualAuthDelete": {
        "enabled": false
      }
}

# decode the payload to get the original string (credentials)
$ echo $PAYLOAD | base64 -d

{
    "host": "localhost",
    "database": "dev-backup",
    "username": "my-username",
    "password": "my-password"
}

Example 7

Create a root key with an alias, then use that alias to identify the key to show the key details.

# create a root key with an alias
$ ibmcloud kp key create root-key-with-alias -a example-alias --output json

{
    "id": "b3660416-4186-4587-b528-484886a4731b",
    "name": "root-key-with-alias",
    "type": "application/vnd.ibm.kms.key+json",
    "extractable": false,
    "state": 1,
    "aliases": [
        "example-alias"
    ],
    "keyRingID": "default",
    "crn": "crn:v1:bluemix:public:kms:us-south:a/ea998d3389c3473aa0987652b46fb146:390086ac-76fa-4094-8cf3-c0829bd69526:key:b3660416-4186-4587-b528-484886a4731b",
    "deleted": false
}

# show key details using the alias as identifier
$ ibmcloud kp key show example-alias --output json

{
    "id": "b3660416-4186-4587-b528-484886a4731b",
    "name": "root-key-with-alias",
    "type": "application/vnd.ibm.kms.key+json",
    "algorithmType": "AES",
    "createdBy": "user id ...<redacted>...",
    "creationDate": "2022-06-09T21:21:55Z",
    "lastUpdateDate": "2022-06-09T21:21:55Z",
    "keyVersion": {
        "id": "264fadc3-7667-4b25-916e-5825fe70de0b",
    "creationDate": "2022-06-09T21:21:55Z"
    },
    "aliases": [
        "example-alias"
    ],
    "keyRingID": "default",
    "extractable": false,
    "state": 1,
    "crn": "crn:v1:bluemix:public:kms:us-south:a/ea998d3389c3473aa0987652b46fb146:390086ac-76fa-4094-8cf3-c0829bd69526:key:b3660416-4186-4587-b528-484886a4731b",
    "deleted": false,
    "dualAuthDelete": {
        "enabled": false
    }
}

Example 8

Add a description to a key. For example, a short phrase used to describe the intended purpose of the key.

ibmcloud kp key create KEY_NAME -i 40f2a13c-780e-4641-bea5-e166e5bb5a9f -D ""description of the key""

Example 1

Delete a root key.

# create a root key
$ ibmcloud kp key create my-root-key

Creating key: 'my-root-key', in instance: '390086ac-76fa-4094-8cf3-c0829bd69526'...
OK
Key ID                                 Key Name
8635b804-9966-4918-a16b-d561fdbf181f   my-root-key

# show key details
$ ibmcloud kp key show 8635b804-9966-4918-a16b-d561fdbf181f

Grabbing info for key id: 8635b804-9966-4918-a16b-d561fdbf181f...
OK
Key ID                                 Key Name      Description   Creation Date                   Expiration Date
8635b804-9966-4918-a16b-d561fdbf181f   my-root-key                 2020-05-05 19:58:02 +0000 UTC   Key does not expire

# delete the key
$ ibmcloud kp key delete 8635b804-9966-4918-a16b-d561fdbf181f

Deleting key: 8635b804-9966-4918-a16b-d561fdbf181f, from instance: 390086ac-76fa-4094-8cf3-c0829bd69526...
OK
Deleted Key
8635b804-9966-4918-a16b-d561fdbf181f

Example 2

Delete a root key and show the JSON output.

# create a root key
$ ibmcloud kp key create my-root-key --output json

{
    "id": "9cca88c9-019e-4f0a-9e76-8e657c6b9720",
    "name": "my-root-key",
    "type": "application/vnd.ibm.kms.key+json",
    "extractable": false,
    "state": 1,
    "crn": "crn:v1:bluemix:public:kms:us-south:a/ea998d3389c3473aa0987652b46fb145:390086ac-76fa-4094-8cf3-c0829bd69526:key:9cca88c9-019e-4f0a-9e76-8e657c6b9720"
}

# show key details
$ ibmcloud kp key show 9cca88c9-019e-4f0a-9e76-8e657c6b9720 --output json

{
    "id": "9cca88c9-019e-4f0a-9e76-8e657c6b9720",
    "name": "my-root-key",
    "type": "application/vnd.ibm.kms.key+json",
    "algorithmType": "AES",
    "createdBy": "user id ...<redacted>...",
    "creationDate": "2020-05-05T20:03:00Z",
    "lastUpdateDate": "2020-05-05T20:03:00Z",
    "extractable": false,
    "state": 1,
    "crn": "crn:v1:bluemix:public:kms:us-south:a/ea998d3389c3473aa0987652b46fb145:390086ac-76fa-4094-8cf3-c0829bd69526:key:9cca88c9-019e-4f0a-9e76-8e657c6b9720"
}

# delete the key
$ ibmcloud kp key delete 9cca88c9-019e-4f0a-9e76-8e657c6b9720 --output json

{
    "id": "9cca88c9-019e-4f0a-9e76-8e657c6b9720"
}

Example 3

Delete a root key that is registered with another cloud resource.

# create a Cloud Object Storage (COS) instance
# "lite" is the pricing plan and "global" is the region
$ COS_NAME=my-cos-1

$ ibmcloud resource service-instance-create $COS_NAME cloud-object-storage lite global

# capture the COS instance id (GUID)
$ COS_INSTANCE_ID=9d4353d8-6b85-4689-90dd-1ccfb4a275ab

# create a Key Management Service (KMS) instance
# "tiered-pricing" is the pricing plan and "us-south" is the region
$ KMS_NAME=my-kms-1

$ ibmcloud resource service-instance-create $KMS_NAME kms tiered-pricing us-south

# capture the Key Protect (KP) instance id (GUID)
$ KP_INSTANCE_ID=b0d84b32-09d0-4314-8049-da78e3b9ab6f

# create a policy for COS to read KMS; source is COS, target is KMS (Key Protect)
$ ibmcloud iam authorization-policy-create cloud-object-storage kms Reader \
  --source-service-instance-id $COS_INSTANCE_ID \
  --target-service-instance-id $KP_INSTANCE_ID

# capture the COS-to-KMS authorization policy id
$ COS_KMS_AUTHORIZATION=79375168-2d74-49df-98aa-3e727410fa71

# create a KP root key that COS uses to encrypt data
$ ibmcloud kp key create my-cos-key --output json

{
    "id": "52a9d772-8982-4620-bfb4-b070dd812a0c",
    "name": "my-cos-key",
    "type": "application/vnd.ibm.kms.key+json",
    "extractable": false,
    "state": 1,
    "crn": "crn:v1:bluemix:public:kms:us-south:a/ea998d3389c3473aa0987652b46fb146:b0d84b32-09d0-4314-8049-da78e3b9ab6f:key:52a9d772-8982-4620-bfb4-b070dd812a0c"
}

# capture the KP root key id
$ MY_COS_KEY_ID=52a9d772-8982-4620-bfb4-b070dd812a0c

# create a COS bucket and set KP encryption
#   must be done in the console user interface (UI) because
#   there is no API or CLI support at this time

# capture the name of the COS bucket that was created
$ COS_BUCKET=my-cos-kms-bucket

# view the KP registration; it's a result of creating the COS bucket
$ ibmcloud kp registrations --output json

[
  {
    "keyId": "52a9d772-8982-4620-bfb4-b070dd812a0c",
    "resourceCrn": "crn:v1:bluemix:public:cloud-object-storage:global:a/ea998d3389c3473aa0987652b46fb146:9d4353d8-6b85-4689-90dd-1ccfb4a275ab:bucket:my-cos-kms-bucket",
    "createdBy": "crn-crn:v1:bluemix:public:cloud-object-storage:global:a/ea998d3389c3473aa0987652b46fb146:9d4353d8-6b85-4689-90dd-1ccfb4a275ab::",
    "creationDate": "2020-06-15T20:41:23Z",
    "lastUpdated": "2020-06-15T20:41:23Z",
    "keyVersion": { "id": "52a9d772-8982-4620-bfb4-b070dd812a0c", "creationDate": "2020-06-15T20:36:46Z"
    }
  }
]

# delete the authorization policy between COS AND KMS - this breaks everything
$ ibmcloud iam authorization-policy-delete $COS_KMS_AUTHORIZATION --force

# delete the KP root key - this fails because the registration was not deleted
$ ibmcloud kp key delete $MY_COS_KEY_ID

Deleting key: 52a9d772-8982-4620-bfb4-b070dd812a0c, from instance: b0d84b32-09d0-4314-8049-da78e3b9ab6f...
FAILED
kp.Error:
    correlation_id='c27b7948-4a1f-4cbd-8770-cb3616888e27',
    msg='Conflict: Key could not be deleted. Please see "reasons" for more details.',
    reasons='[PROTECTED_RESOURCE_ERR: Key is protecting one or more cloud resources -
        FOR_MORE_INFO_REFER: https://cloud.ibm.com/docs/key-protect?topic=key-protect-troubleshooting#unable-to-delete-keys]'

# delete the KP root key; use --force because the registration between COS and KMS still exists
$ ibmcloud kp key delete $MY_COS_KEY_ID --force --output json

{
    "id": "52a9d772-8982-4620-bfb4-b070dd812a0c"
}

# delete the KMS instance
$ ibmcloud resource service-instance-delete $KMS_NAME --force

# delete the COS instance
$ ibmcloud resource service-instance-delete $COS_NAME --force

# view resources (COS and KMS should no longer exist)
$ ibmcloud resource service-instances

Retrieving instances with type service_instance in resource group Default in all locations under account <account name> as <email address>...
OK
No service instance found.

Example 1

Create a root key, disable it, verify the key state (suspended), enable the root key, and verify the key state (active).

# create a root key
$ ibmcloud kp key create my-root-key --output json

{
    "id": "264fadc3-7667-4b25-916e-5825fe70de0b",
    "name": "my-root-key",
    "type": "application/vnd.ibm.kms.key+json",
    "extractable": false,
    "state": 1,
    "crn": "crn:v1:bluemix:public:kms:us-south:a/ea998d3389c3473aa0987652b46fb146:390086ac-76fa-4094-8cf3-c0829bd69526:key:264fadc3-7667-4b25-916e-5825fe70de0b"
}

# show key details - a state of "1" is "active"
$ ibmcloud kp key show 264fadc3-7667-4b25-916e-5825fe70de0b --output json

{
    "id": "264fadc3-7667-4b25-916e-5825fe70de0b",
    "name": "my-root-key",
    "type": "application/vnd.ibm.kms.key+json",
    "algorithmType": "AES",
    "createdBy": "user id ...<redacted>...",
    "creationDate": "2020-06-09T21:21:55Z",
    "lastUpdateDate": "2020-06-09T21:21:55Z",
    "keyVersion": {
        "id": "264fadc3-7667-4b25-916e-5825fe70de0b",
    "creationDate": "2020-06-09T21:21:55Z"
    },
    "extractable": false,
    "state": 1,
    "crn": "crn:v1:bluemix:public:kms:us-south:a/ea998d3389c3473aa0987652b46fb146:390086ac-76fa-4094-8cf3-c0829bd69526:key:264fadc3-7667-4b25-916e-5825fe70de0b"
}

# disable the root key
$ ibmcloud kp key disable 264fadc3-7667-4b25-916e-5825fe70de0b

Disabling key: '264fadc3-7667-4b25-916e-5825fe70de0b', in instance: '390086ac-76fa-4094-8cf3-c0829bd69526'...
OK

# show key details - a state of "2" is "suspended"
$ ibmcloud kp key show 264fadc3-7667-4b25-916e-5825fe70de0b --output json

{
    "id": "264fadc3-7667-4b25-916e-5825fe70de0b",
    "name": "my-root-key",
    "type": "application/vnd.ibm.kms.key+json",
    "algorithmType": "AES",
    "createdBy": "user id ...<redacted>...",
    "creationDate": "2020-06-09T21:21:55Z",
    "lastUpdateDate": "2020-06-09T21:23:26Z",
    "keyVersion": {
        "id": "264fadc3-7667-4b25-916e-5825fe70de0b",
    "creationDate": "2020-06-09T21:21:55Z"
    },
    "extractable": false,
    "state": 2,
    "crn": "crn:v1:bluemix:public:kms:us-south:a/ea998d3389c3473aa0987652b46fb146:390086ac-76fa-4094-8cf3-c0829bd69526:key:264fadc3-7667-4b25-916e-5825fe70de0b"
}

Example 2

Create a root key, disable it, and attempt to use the root key to wrap another key.

# create a root key
$ KEY_ID=$(ibmcloud kp key create my-root-key --output json | jq -r '.["id"]')

$ echo $KEY_ID

63d044d9-b38b-4803-85ef-ed9a1e5087c2

# disable the root key
$ ibmcloud kp key disable $KEY_ID

Disabling key: '63d044d9-b38b-4803-85ef-ed9a1e5087c2', in instance: '390086ac-76fa-4094-8cf3-c0829bd69526'...
OK

# create a random, base64-encoded, 32-byte data encryption key (DEK)
$ PLAINTEXT=$(openssl rand -base64 32)

$ echo $PLAINTEXT

BNxtU9B4kXOZA45Cnyz3wOh4J77TakTXI1n2rj0ZiMc=

# wrap the plaintext key with the root key, creating a DEK (this is the ciphertext)
# this should fail (the root key is disables)
$ ibmcloud kp key wrap $KEY_ID -p $PLAINTEXT --output json

FAILED
kp.Error:
    correlation_id='c2edbdad-7e62-4690-8fcc-10515ade9913',
    msg='Conflict: Action could not be performed on key. Please see "reasons" for more details.',
    reasons='[KEY_ACTION_INVALID_STATE_ERR: Key is not in a valid state -
        FOR_MORE_INFO_REFER: https://cloud.ibm.com/apidocs/key-protect]'

Example 3

Create a root key with an alias, use that alias to identify the key to be disabled, verify the key state (suspended), then enable the root key and verify the new key state (active).

# create a root key
$ ibmcloud kp key create root-key-with-alias -a example-alias-1 --output json

{
    "id": "264fadc3-7667-4b25-916e-5825fe70de0b",
    "name": "root-key-with-alias",
    "type": "application/vnd.ibm.kms.key+json",
    "extractable": false,
    "state": 1,
    "aliases": [
        "example-alias"
    ],
    "deleted": false,
    "crn": "crn:v1:bluemix:public:kms:us-south:a/ea998d3389c3473aa0987652b46fb146:390086ac-76fa-4094-8cf3-c0829bd69526:key:264fadc3-7667-4b25-916e-5825fe70de0b"
}

# show key details using the alias as identifier - a state of "1" is "active"
$ ibmcloud kp key show example-alias-1 --output json

{
    "id": "264fadc3-7667-4b25-916e-5825fe70de0b",
    "name": "root-key-with-alias",
    "type": "application/vnd.ibm.kms.key+json",
    "algorithmType": "AES",
    "createdBy": "user id ...<redacted>...",
    "creationDate": "2020-06-09T21:21:55Z",
    "lastUpdateDate": "2020-06-09T21:21:55Z",
    "keyVersion": {
        "id": "264fadc3-7667-4b25-916e-5825fe70de0b",
    "creationDate": "2020-06-09T21:21:55Z"
    },
    "extractable": false,
    "state": 1,
    ...
    "crn": "crn:v1:bluemix:public:kms:us-south:a/ea998d3389c3473aa0987652b46fb146:390086ac-76fa-4094-8cf3-c0829bd69526:key:264fadc3-7667-4b25-916e-5825fe70de0b"
}

# disable the root key identified by alias
$ ibmcloud kp key disable example-alias-1

Disabling key: '264fadc3-7667-4b25-916e-5825fe70de0b', in instance: '390086ac-76fa-4094-8cf3-c0829bd69526'...
OK

# show key details - a state of "2" is "suspended"
$ ibmcloud kp key show example-alias-1 --output json

{
    "id": "264fadc3-7667-4b25-916e-5825fe70de0b",
    "name": "root-key-with-alias",
    "type": "application/vnd.ibm.kms.key+json",
    "algorithmType": "AES",
    "createdBy": "user id ...<redacted>...",
    "creationDate": "2020-06-09T21:21:55Z",
    "lastUpdateDate": "2020-06-09T21:23:26Z",
    "keyVersion": {
        "id": "264fadc3-7667-4b25-916e-5825fe70de0b",
    "creationDate": "2020-06-09T21:21:55Z"
    },
    "extractable": false,
    "state": 2,
    "crn": "crn:v1:bluemix:public:kms:us-south:a/ea998d3389c3473aa0987652b46fb146:390086ac-76fa-4094-8cf3-c0829bd69526:key:264fadc3-7667-4b25-916e-5825fe70de0b"
}

Example 1

This example creates a root key using a key material, deletes the key, then restores the key.

# create a random, base64-encoded, 32-byte key material
$ KEY_MATERIAL=$(openssl rand -base64 32)

$ echo $KEY_MATERIAL

4EZBMBMkZ87z4nvYsQH21DC5+wslgWhHRiU8bmqJ4CY=

# create a root key from a base64-encoded value
$ KEY_ID=$(ibmcloud kp key create my-base64-root-key -k $KEY_MATERIAL --output json | jq -r '.["id"]')

$ echo $KEY_ID

62ad0cd5-70a4-4c4d-9d87-5f4db620b120

# delete the root key
$ ibmcloud kp key delete $KEY_ID

Deleting key: 62ad0cd5-70a4-4c4d-9d87-5f4db620b120, from instance: a192d603-0b8d-452f-aac3-f9e1f95e7411...
OK
Deleted Key
62ad0cd5-70a4-4c4d-9d87-5f4db620b120

# list keys - verify the key was deleted
$ ibmcloud kp keys

Retrieving keys...
OK
Key ID   Key Name

# restore the deleted key
$ ibmcloud kp key restore $KEY_ID -k $KEY_MATERIAL --output json

{
    "id": "62ad0cd5-70a4-4c4d-9d87-5f4db620b120",
    "name": "my-base64-root-key",
    "type": "application/vnd.ibm.kms.key+json",
    "extractable": false,
    "state": 1,
    "crn": "crn:v1:bluemix:public:kms:us-south:a/ea998d3389c3473aa0987652b46fb146:a192d603-0b8d-452f-aac3-f9e1f95e7411:key:62ad0cd5-70a4-4c4d-9d87-5f4db620b120"
}

# list keys - verify the key was restored
$ ibmcloud kp keys

Retrieving keys...
OK
Key ID                                 Key Name
62ad0cd5-70a4-4c4d-9d87-5f4db620b120   my-base64-root-key

Example 2

This workflow creates a root key using an import token, deletes the key, then restores the key.

This is a two-step process.

1. Create a root key using an import token and then delete the key

2. Create an import token, which is required to restore the key, and restore the key

Creating a root key using an import token has a time limit (the -e, --expiration option). When you restore a key you need an import token. Which is why you need to go through an import token process to restore a key.

Step 1 - create a root key using an import token and then delete the key

# create an import token that expires in 5 minutes and allows 10 retrievals
$ ibmcloud kp import-token create -e 300 -m 10

Created                         Expires                         Max Retrievals   Remaining Retrievals
2020-06-18 12:21:59 +0000 UTC   2020-06-18 12:26:59 +0000 UTC   10               10

# create a random, base64-encoded, 32-byte key material
$ KEY_MATERIAL=$(openssl rand -base64 32)

$ echo $KEY_MATERIAL

sADDNDE3pcJlbYXu2z5QFORvsxV1PosRiAPERrhYJdk=

# extract the nonce that was created by the "kp import-token create" command
$ NONCE=$(ibmcloud kp import-token show | jq -r '.["nonce"]')

$ echo $NONCE

/QhqOsqlVPC+ZPWz

# extract the public key that was created by the "kp import-token create" command
$ PUBLIC_KEY=$(ibmcloud kp import-token show | jq -r '.["payload"]')

$ echo $PUBLIC_KEY

LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0t ...<redacted>... QyBLRVktLS0tLQo=

# encrypt the key material using the public key
$ ibmcloud kp import-token key-encrypt -k $KEY_MATERIAL -p $PUBLIC_KEY

Encrypted Key
C+/puHn1v5p7aohitM4r6N4ohiVkCecP ...<redacted>... eWmJRuvsSxDg/OY=

# capture the encrypted key material
$ ENCRYPTED_KEY=C+/puHn1v5p7aohitM4r6N4ohiVkCecP ...<redacted>... eWmJRuvsSxDg/OY=

# encrypt the nonce
$ ibmcloud kp import-token nonce-encrypt -k $KEY_MATERIAL -n $NONCE

Encrypted Nonce                            IV
TxrgdayWnM5OB3JoYuQR97oulxvREptk8TzciQ==   7BiIpcbGxXBzuXZP

# capture the encrypted nonce and the initialization vector (IV)
$ ENCRYPTED_NONCE=TxrgdayWnM5OB3JoYuQR97oulxvREptk8TzciQ==
$ IV=7BiIpcbGxXBzuXZP

# create a root key using an import token, provide an encrypted key, nonce, and initialization vector (IV)
$ KEY_ID=$(ibmcloud kp key create my-imported-root-key -k $ENCRYPTED_KEY -n $ENCRYPTED_NONCE -v $IV --output json | jq -r '.["id"]')

$ echo $KEY_ID

c42c6f2c-8b67-4016-b2c3-99fba9490f5d

# list keys - verify the key was created
$ ibmcloud kp keys

Retrieving keys...
OK
Key ID                                 Key Name
c42c6f2c-8b67-4016-b2c3-99fba9490f5d   my-imported-root-key

# delete the root key
$ ibmcloud kp key delete $KEY_ID

Deleting key: c42c6f2c-8b67-4016-b2c3-99fba9490f5d, from instance: a192d603-0b8d-452f-aac3-f9e1f95e7411...
OK
Deleted Key
c42c6f2c-8b67-4016-b2c3-99fba9490f5d

# list keys - verify the key was deleted
$ ibmcloud kp keys

Retrieving keys...
OK
Key ID   Key Name

Step 2 - create an import token, which is required to restore the key, and restore the key

# NOTE: "kp key restore" requires an import token to complete the process,
# if you follow this example, the previously created import token may still
# exist and the example works; otherwise, if the import token has expired then
# you need to create a new import token prior to restoring the key

# create an import token that expires in 5 minutes and allows 10 retrievals
$ ibmcloud kp import-token create -e 300 -m 10

Created                         Expires                         Max Retrievals   Remaining Retrievals
2020-06-18 12:30:54 +0000 UTC   2020-06-18 12:35:54 +0000 UTC   10               10

# extract the nonce that was created by the "kp import-token create" command
$ NONCE=$(ibmcloud kp import-token show | jq -r '.["nonce"]')

$ echo $NONCE

N3x8F0ihAZ51nj6M

# extract the public key that was created by the "kp import-token create" command
$ PUBLIC_KEY=$(ibmcloud kp import-token show | jq -r '.["payload"]')

$ echo $PUBLIC_KEY

LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0t ...<redacted>... QyBLRVktLS0tLQo=

# encrypt the key material using the public key
$ ibmcloud kp import-token key-encrypt -k $KEY_MATERIAL -p $PUBLIC_KEY

Encrypted Key
Ch7hcsT1EOfSdghjOHKAemBZuzDoqJoH ...<redacted>... F4p/mkGT/EQJS5o=

# capture the encrypted key material
$ ENCRYPTED_KEY=Ch7hcsT1EOfSdghjOHKAemBZuzDoqJoH ...<redacted>... F4p/mkGT/EQJS5o=

# encrypt the nonce
$ ibmcloud kp import-token nonce-encrypt -k $KEY_MATERIAL -n $NONCE

Encrypted Nonce                            IV
nrrCczvYXvc6T7J2G+EOLjHZO1cpPyu/nhsIlA==   N6oLJnUqaKF3v5Sd

# capture the encrypted nonce and the initialization vector (IV)
$ ENCRYPTED_NONCE=nrrCczvYXvc6T7J2G+EOLjHZO1cpPyu/nhsIlA==
$ IV=N6oLJnUqaKF3v5Sd

# restore the deleted key
$ ibmcloud kp key restore $KEY_ID -k $ENCRYPTED_KEY -n $ENCRYPTED_NONCE -v $IV --output json

{
    "id": "c42c6f2c-8b67-4016-b2c3-99fba9490f5d",
    "name": "my-imported-root-key",
    "type": "application/vnd.ibm.kms.key+json",
    "extractable": false,
    "state": 1,
    "crn": "crn:v1:bluemix:public:kms:us-south:a/ea998d3389c3473aa0987652b46fb146:a192d603-0b8d-452f-aac3-f9e1f95e7411:key:c42c6f2c-8b67-4016-b2c3-99fba9490f5d"
}

# list keys - verify the key was restored
$ ibmcloud kp keys

Retrieving keys...
OK
Key ID                                 Key Name
c42c6f2c-8b67-4016-b2c3-99fba9490f5d   my-imported-root-key

Example 1

Rotate a root key.

# create a root key
$ ibmcloud kp key create my-root-key

Creating key: 'my-root-key', in instance: '390086ac-76fa-4094-8cf3-c0829bd69526'...
OK
Key ID                                 Key Name
1a6d5be8-287c-4eb3-9c44-cf0c2b0d67ad   my-root-key

# rotate the key
$ ibmcloud kp key rotate 1a6d5be8-287c-4eb3-9c44-cf0c2b0d67ad

Rotating root key...
OK

# show key details
$ ibmcloud kp key show 1a6d5be8-287c-4eb3-9c44-cf0c2b0d67ad

Grabbing info for key id: 1a6d5be8-287c-4eb3-9c44-cf0c2b0d67ad...
OK
Key ID                                 Key Name      Description   Creation Date                   Expiration Date
1a6d5be8-287c-4eb3-9c44-cf0c2b0d67ad   my-root-key                 2020-05-06 17:25:22 +0000 UTC   Key does not expire

# create a new key material
$ NEW_KEY_MATERIAL=$(openssl rand -base64 32)

# Key Protect created the root key, providing a new key material will fail
$ ibmcloud kp key rotate 1a6d5be8-287c-4eb3-9c44-cf0c2b0d67ad -k $NEW_KEY_MATERIAL

Rotating root key...
FAILED

Example 2

Rotate a base64-encoded or an imported token key.

First, create a root key from a base64 value or an imported token.

# create a random, base64-encoded, 32-byte key material
$ KEY_MATERIAL=$(openssl rand -base64 32)

# create a root key from a base64-encoded value
$ ibmcloud kp key create my-base64-root-key -k $KEY_MATERIAL

Creating key: 'my-base64-root-key', in instance: '390086ac-76fa-4094-8cf3-c0829bd69526'...
OK
Key ID                                 Key Name
e55f86ab-6984-4594-ad23-3024f6440a58   my-base64-root-key

# create a new key material
$ NEW_KEY_MATERIAL=$(openssl rand -base64 32)

# rotate the key
$ ibmcloud kp key rotate e55f86ab-6984-4594-ad23-3024f6440a58 -k $NEW_KEY_MATERIAL

Rotating root key...
OK

# the key was created from a key material, NOT providing a new key material will fail
$ ibmcloud kp key rotate e55f86ab-6984-4594-ad23-3024f6440a58

Rotating root key...
FAILED

Example 3

This examples shows how to...

1. Create a root key

2. Create a data encryption key (DEK), this is the plaintext

3. Wrap the DEK with the root key, this creates a ciphertext

4. Rotate the root key

5. Unwrap the ciphertext to reveal the original DEK (plaintext) and a new ciphertext (the new ciphertext is the plaintext wrapped with the new rotated root key)

6. Unwrap the new ciphertext to reveal the original DEK (plaintext)

# create a root key
$ KEY_ID=$(ibmcloud kp key create my-root-key --output json | jq -r '.["id"]')

$ echo $KEY_ID

5b976173-7804-4f82-acfa-bb98098bc528

# create a random, base64-encoded, 32-byte data encryption key (DEK)
$ PLAINTEXT=$(openssl rand -base64 32)

$ echo $PLAINTEXT

UPJ4YDwbQMjQG/aqlHsPhHV1CBkpIXngLHFS5+i4UZ4=

# wrap the plaintext key with the root key, creating a DEK (this is the ciphertext)
$ CIPHERTEXT=$(ibmcloud kp key wrap $KEY_ID -p $PLAINTEXT --output json | jq -r '.["Ciphertext"]')

$ echo $CIPHERTEXT

eyJjaXBoZXJ0ZXh0IjoiQkFrTlJrS2Q0 ...<redacted>... ODA5OGJjNTI4In0=

# rotate the root key
$ ibmcloud kp key rotate $KEY_ID

Rotating root key...
OK

# show key details
$ ibmcloud kp key show $KEY_ID --output json

{
    "id": "5b976173-7804-4f82-acfa-bb98098bc528",
    "name": "my-root-key",
    "type": "application/vnd.ibm.kms.key+json",
    "algorithmType": "AES",
    "createdBy": "user id ...<redacted>...",
    "creationDate": "2020-06-10T18:09:27Z",
    "lastUpdateDate": "2020-06-10T18:13:31Z",
    "lastRotateDate": "2020-06-10T18:13:31Z",
    "keyVersion": {
        "id": "4330715a-918b-4718-b5ca-9475a214067e",
    "creationDate": "2020-06-10T18:13:31Z"
    },
    "extractable": false,
    "state": 1,
    "crn": "crn:v1:bluemix:public:kms:us-south:a/ea998d3389c3473aa0987652b46fb146:390086ac-76fa-4094-8cf3-c0829bd69526:key:5b976173-7804-4f82-acfa-bb98098bc528"
}

# unwrap the ciphertext, reveal the original DEK (plaintext),
# and see the new ciphertext (the plaintext wrapped with the rotated root key)
$ ibmcloud kp key unwrap $KEY_ID $CIPHERTEXT --output json

{
    "Plaintext": "UPJ4YDwbQMjQG/aqlHsPhHV1CBkpIXngLHFS5+i4UZ4=",
    "Rewrapped Plaintext": "eyJjaXBoZXJ0ZXh0IjoiS0FITEFRWjdh ...<redacted>... NWEyMTQwNjdlIn0="
}

# capture the new (rewrapped) plaintext
$ NEWCIPHERTEXT=eyJjaXBoZXJ0ZXh0IjoiS0FITEFRWjdh ...<redacted>... NWEyMTQwNjdlIn0=

# unwrap the ciphertext and reveal the original DEK (plaintext)
$ ibmcloud kp key unwrap $KEY_ID $NEWCIPHERTEXT --output json

{
    "Plaintext": "UPJ4YDwbQMjQG/aqlHsPhHV1CBkpIXngLHFS5+i4UZ4=",
    "Rewrapped Plaintext": ""
}

Example 1

Create a root key and show the details.

# create a root key
$ ibmcloud kp key create my-root-key

Creating key: 'my-root-key', in instance: '390086ac-76fa-4094-8cf3-c0829bd69526'...
OK
Key ID                                 Key Name
8635b804-9966-4918-a16b-d561fdbf181f   my-root-key

# show key details
$ ibmcloud kp key show 8635b804-9966-4918-a16b-d561fdbf181f

Grabbing info for key id: 8635b804-9966-4918-a16b-d561fdbf181f...
OK
Key ID                                 Key Name      Description   Creation Date                   Expiration Date
8635b804-9966-4918-a16b-d561fdbf181f   my-root-key                 2020-05-05 19:58:02 +0000 UTC   Key does not expire

Example 2

This is an explanation of the JSON keys and values from the kp key show command. In this example the key was rotated to ensure all JSON key/value pairs are shown.

$ ibmcloud kp key show 8635b804-9966-4918-a16b-d561fdbf181f --output json

{
    "id": "8635b804-9966-4918-a16b-d561fdbf181f",
    "name": "my-root-key",
    "type": "application/vnd.ibm.kms.key+json",
    "algorithmType": "AES",
    "createdBy": "user id ...<redacted>...",
    "creationDate": "2020-05-05T19:58:02Z",
    "lastUpdateDate": "2020-05-05T19:58:24Z",
    "lastRotateDate": "2020-05-05T19:58:24Z",
    "keyVersion": {
        "id": "85b65b20-4165-4da3-8ba9-880e72390461",
        "creationDate": "2020-05-05T19:58:24Z"
    },
    "extractable": false,
    "state": 1,
    "crn": "crn:v1:bluemix:public:kms:us-south:a/ea998d3389c3473aa0987652b46fb146:390086ac-76fa-4094-8cf3-c0829bd69526:key:8635b804-9966-4918-a16b-d561fdbf181f"
}

Example

Synchronize a key and show the results.

# synchronize the associated resources for a given key
$ ibmcloud kp key sync 94c06f9c-a07a-4961-8548-553cf7431f18

Synchronizing key...
OK
Key's associated resources are synchronized successfully

Example 1

Unwrap a ciphertext to reveal the plaintext data encryption key (DEK).

# create a root key
$ ibmcloud kp key create my-root-key

Creating key: 'my-root-key', in instance: '390086ac-76fa-4094-8cf3-c0829bd69526'...
OK
Key ID                                 Key Name
807eb0a6-cc10-4bfe-8331-41a6f712c4ea   my-root-key

# create a data encryption key (DEK), wrapped with the root key
$ ibmcloud kp key wrap 807eb0a6-cc10-4bfe-8331-41a6f712c4ea

Wrapping key...
OK
Ciphertext
eyJjaXBoZXJ0ZXh0IjoiKzhjbHVqcUNP ...<redacted>... NmY3MTJjNGViIn0=

# capture the ciphertext
$ CIPHERTEXT=eyJjaXBoZXJ0ZXh0IjoiKzhjbHVqcUNP ...<redacted>... NmY3MTJjNGViIn0=

# unwrap the ciphertext to reveal the plaintext data encryption key (DEK)
$ ibmcloud kp key unwrap 807eb0a6-cc10-4bfe-8331-41a6f712c4ea $CIPHERTEXT

Unwrapping key...
OK
Plaintext                                      Rewrapped Plaintext
mXW4GmBhkRG1+Dzkx1D6dMX99a4KyYwtwbghaaLEQZ0=

Example 2

Unwrap a ciphertext and provide AAD information.

One use case for supplying additional authentication data (AAD) is to "password protect" the ciphertext to make it more difficult to unwrap.

The ciphertext and the AAD is required to unwrap the ciphertext and reveal the plaintext data encryption key (DEK).

# create a root key
$ KEY_ID=$(ibmcloud kp key create my-root-key --output json | jq -r '.["id"]')

$ echo $KEY_ID

5f2cc155-fe16-492c-845c-4d1f0688c7ba

# create a random, base64-encoded, 32-byte data encryption key (DEK)
$ PLAINTEXT=$(openssl rand -base64 32)

$ echo $PLAINTEXT

H4ZfQe66aKcxirfCdNZ/3Na0JECP6HsAM3yclKmIfPQ=

# set the additional authentication data (AAD)
$ AAD1=My-Secret-Password
$ AAD2=My-Verification-Phrase

# wrap the plaintext with the root key and AAD
$ CIPHERTEXT=$(ibmcloud kp key wrap $KEY_ID -a "$AAD1,$AAD2" -p $PLAINTEXT --output json | jq -r '.["Ciphertext"]')

$ echo $CIPHERTEXT

eyJjaXBoZXJ0ZXh0IjoiL1pQUzRLbUxQ ...<redacted>... ZjA2ODhjN2JiIn0=

# unwrap the ciphertext and reveal the original plaintext DEK
$ ibmcloud kp key unwrap $KEY_ID $CIPHERTEXT -a $AAD1,$AAD2

Unwrapping key...
OK
Plaintext                                      Rewrapped Plaintext
H4ZfQe66aKcxirfCdNZ/3Na0JECP6HsAM3yclKmIfPQ=

# this should fail (missing some of the AAD)
$ ibmcloud kp key unwrap $KEY_ID $CIPHERTEXT -a $AAD1

Unwrapping key...
FAILED

# this should fail (AAD is in a different order)
$ ibmcloud kp key unwrap $KEY_ID $CIPHERTEXT -a $AAD2,$AAD1

Unwrapping key...
FAILED

Example 1

One use case is auditing the rotation history of a root key as a security admin, by viewing its key version history.

# create a root key
$ ibmcloud kp key create my-root-key

Creating key: 'my-root-key', in instance: '390086ac-76fa-4094-8cf3-c0829bd69526'...
OK
Key ID                                 Key Name
807eb0a6-cc10-4bfe-8331-41a6f712c4ea   my-root-key

# rotate the root key
$ ibmcloud kp key rotate 807eb0a6-cc10-4bfe-8331-41a6f712c4ea

Rotating root key...
OK

# Inspect the versions
$ ibmcloud kp key versions 807eb0a6-cc10-4bfe-8331-41a6f712c4ea

Retrieving key Versions...
OK
Key Version ID                         Creation Date   
21562e93-8882-420e-90a7-912c70023373   2022-07-08T17:02:10Z
390086ac-76fa-4094-8cf3-c0829bd69526   2022-07-08T17:02:40Z

Example 2

The same use case for auditing a root key as a security admin and viewing the history, with its total count in JSON output.

# create a root key
$ ibmcloud kp key create my-root-key

Creating key: 'my-root-key', in instance: '390086ac-76fa-4094-8cf3-c0829bd69526'...
OK
Key ID                                 Key Name
807eb0a6-cc10-4bfe-8331-41a6f712c4ea   my-root-key

# rotate the root key
$ ibmcloud kp key rotate 807eb0a6-cc10-4bfe-8331-41a6f712c4ea

Rotating root key...
OK

# Inspect the versions
$ ibmcloud kp key versions 807eb0a6-cc10-4bfe-8331-41a6f712c4ea -t -o json
{
        "metadata": {
                "collectionType": "application/vnd.ibm.kms.key.version+json",
                "collectionTotal": 2,
                "totalCount": 2
        },
        "resources": [
                {
                        "id": "21562e93-8882-420e-90a7-912c70023373",
                        "creationDate": "2022-07-08T17:02:10Z"
                },
                {
                        "id": "390086ac-76fa-4094-8cf3-c0829bd69526",
                        "creationDate": "2022-07-08T17:02:40Z"
                }
        ]
}

Example 3

Another use case lists the first 12 key versions for a key set on a monthly rotation for the past year.

# create a root key
$ ibmcloud kp key create my-root-key

Creating key: 'my-root-key', in instance: '390086ac-76fa-4094-8cf3-c0829bd69526'...
OK
Key ID                                 Key Name
807eb0a6-cc10-4bfe-8331-41a6f712c4ea   my-root-key

# rotate the root key
$ ibmcloud kp key rotate 807eb0a6-cc10-4bfe-8331-41a6f712c4ea

Rotating root key...
OK

# Inspect the versions
$ ibmcloud kp key versions 807eb0a6-cc10-4bfe-8331-41a6f712c4ea -n 12 -o json
{
        "metadata": {
                "collectionType": "application/vnd.ibm.kms.key.version+json",
                "collectionTotal": 12
        },
        "resources": [
                {
                        "id": "21562e93-8882-420e-90a7-912c70023373",
                        "creationDate": "2021-07-08T17:02:10Z"
                },
                {
                        "id": "390086ac-76fa-4094-8cf3-c0829bd69526",
                        "creationDate": "2021-08-08T17:02:40Z"
                },[...10x]
        ]
}

Example 4

Another use case lists the second 12 key versions for a key set on a monthly rotation for the past two years.

ibmcloud kp key versions $KEY_ID_OR_ALIAS -n 12 -s 12

# create a root key
$ ibmcloud kp key create my-root-key

Creating key: 'my-root-key', in instance: '390086ac-76fa-4094-8cf3-c0829bd69526'...
OK
Key ID                                 Key Name
807eb0a6-cc10-4bfe-8331-41a6f712c4ea   my-root-key

# rotate the root key
$ ibmcloud kp key rotate 807eb0a6-cc10-4bfe-8331-41a6f712c4ea

Rotating root key...
OK

# Inspect the versions
$ ibmcloud kp key versions 807eb0a6-cc10-4bfe-8331-41a6f712c4ea -n 12 -s 12 -o json
{
        "metadata": {
                "collectionType": "application/vnd.ibm.kms.key.version+json",
                "collectionTotal": 12
        },
        "resources": [
                {
                        "id": "21562e93-8882-420e-90a7-912c70023373",
                        "creationDate": "2021-07-08T17:02:10Z"
                },
                {
                        "id": "390086ac-76fa-4094-8cf3-c0829bd69526",
                        "creationDate": "2021-08-08T17:02:40Z"
                },[...10x]
        ]
}

Example 5

An optional flag to return the number of versions of a key that is not currently active. Previously, the command would have failed, as in the following example:

# Attempt to show version count
$ ibmcloud kp key versions af61298c-d75d-42a8-aa76-e04178cf4685 -i 99980ccc-d482-4cd0-bb41-deb4f7f1eb92 -t

Retrieving key Versions...
FAILED
KEY_ACTION_INVALID_STATE_ERR
Key is not in a valid state
Correlation-ID:a494bf49-be82-426f-88d8-17b58cc8634d

With CLI version 0.8.0 and higher, the command succeeds when adding the -a flag, as in the following example:

# Attempt to show version count
$ ibmcloud kp key versions af61298c-d75d-42a8-aa76-e04178cf4685 -i 99980ccc-d482-4cd0-bb41-deb4f7f1eb92 -t -a

Retrieving key Versions...
OK
TotalCount: 2
Key Version ID                         Creation Date
14dfde20-a751-4c3e-b6b0-e8d00a17d8d1   2023-06-22T15:16:09Z
af61298c-d75d-42a8-aa76-e04178cf4685   2023-06-22T15:10:28Z

Note that if the -a flag is not given, the KEY_ACTION_INVALID_STATE_ERR is still returned for a key in a state other than active.

Example 1

Key Protect creates a new base64-encoded data encryption key (DEK) and wraps it with the root key.

# create a root key
$ ibmcloud kp key create my-root-key

Creating key: 'my-root-key', in instance: '390086ac-76fa-4094-8cf3-c0829bd69526'...
OK
Key ID                                 Key Name
807eb0a6-cc10-4bfe-8331-41a6f712c4ea   my-root-key

# create a new key and wrap it with the root key, creating a DEK (this is the ciphertext)
$ ibmcloud kp key wrap 807eb0a6-cc10-4bfe-8331-41a6f712c4ea

Wrapping key...
OK
Ciphertext
eyJjaXBoZXJ0ZXh0IjoiKzhjbHVqcUNP ...<redacted>... NmY3MTJjNGViIn0=

# capture the ciphertext
$ CIPHERTEXT=eyJjaXBoZXJ0ZXh0IjoiKzhjbHVqcUNP ...<redacted>... NmY3MTJjNGViIn0=

# unwrap the ciphertext to reveal the plaintext (DEK)
$ ibmcloud kp key unwrap 807eb0a6-cc10-4bfe-8331-41a6f712c4ea $CIPHERTEXT

Unwrapping key...
OK
Plaintext                                      Rewrapped Plaintext
mXW4GmBhkRG1+Dzkx1D6dMX99a4KyYwtwbghaaLEQZ0=

Example 2

Generate a base64-encoded data encryption key (DEK) and wrap it with the root key.

# create a root key
$ KEY_ID=$(ibmcloud kp key create my-root-key --output json | jq -r '.["id"]')

$ echo $KEY_ID

9052d914-bebe-4177-90e9-6073a167b507

# create a random, base64-encoded, 32-byte data encryption key (DEK)
$ PLAINTEXT=$(openssl rand -base64 32)

$ echo $PLAINTEXT

tEqoiCu9CeUsbqRe6yBUkrJg80QKKG/z46OkX0YQMV8=

# wrap the plaintext key with the root key, creating a DEK (this is the ciphertext)
$ CIPHERTEXT=$(ibmcloud kp key wrap $KEY_ID -p $PLAINTEXT --output json | jq -r '.["Ciphertext"]')

$ echo $CIPHERTEXT

eyJjaXBoZXJ0ZXh0IjoiTkdQRlhCb1dT ...<redacted>... M2ExNjdiNTA3In0=

# unwrap the ciphertext and reveal the original DEK
$ ibmcloud kp key unwrap $KEY_ID $CIPHERTEXT

tEqoiCu9CeUsbqRe6yBUkrJg80QKKG/z46OkX0YQMV8=

Example 3

Wrap a root key and provide AAD information.

One use case for supplying additional authentication data (AAD) is to "password protect" and add a "verification phrase" to the ciphertext, which makes it more difficult to unwrap.

The ciphertext and the AAD is required to unwrap the ciphertext and reveal the plaintext DEK.

# create a root key
$ KEY_ID=$(ibmcloud kp key create my-root-key --output json | jq -r '.["id"]')

$ echo $KEY_ID

5f2cc155-fe16-492c-845c-4d1f0688c7ba

# set the additional authentication data (AAD)
$ AAD1=My-Secret-Password
$ AAD2=My-Verification-Phrase

# wrap the plaintext DEK with the root key and AAD
$ CIPHERTEXT=$(ibmcloud kp key wrap $KEY_ID -a "$AAD1,$AAD2" --output json | jq -r '.["Ciphertext"]')

$ echo $CIPHERTEXT

eyJjaXBoZXJ0ZXh0IjoiL1pQUzRLbUxQ ...<redacted>... ZjA2ODhjN2JiIn0=

# unwrap the ciphertext and reveal the original DEK
$ ibmcloud kp key unwrap $KEY_ID $CIPHERTEXT -a $AAD1,$AAD2

Unwrapping key...
OK
Plaintext                                      Rewrapped Plaintext
H4ZfQe66aKcxirfCdNZ/3Na0JECP6HsAM3yclKmIfPQ=

# this should fail (missing some of the AAD)
$ ibmcloud kp key unwrap $KEY_ID $CIPHERTEXT -a $AAD1

Unwrapping key...
FAILED

# this should fail (AAD is in a different order)
$ ibmcloud kp key unwrap $KEY_ID $CIPHERTEXT -a $AAD2,$AAD1

Unwrapping key...
FAILED

Example 1

List keys. Note that this will only list the first 200 keys in your instance by default. To show a greater or fewer number of keys, provide a value for the --number-of-keys parameter.

# list keys
$ ibmcloud kp keys

Retrieving keys...
OK
Key ID                                 Key Name
5f2cc155-fe16-492c-845c-4d1f0688c7ba   my-root-key
c36e9f3a-feaf-4033-8603-687784dc7e51   my-root-key

Example 2

List keys and show the cloud resource name (CRN) using the --crn parameter.

# list keys and show the cloud resource name (CRN)
$ ibmcloud kp keys -c

Retrieving keys...
OK
Key ID                                 Key Name      CRN
5f2cc155-fe16-492c-845c-4d1f0688c7ba   my-root-key   crn:v1:bluemix:public:kms:us-south:a/ea998d3389c3473aa0987652b46fb146:390086ac-76fa-4094-8cf3-c0829bd69526:key:5f2cc155-fe16-492c-845c-4d1f0688c7ba
c36e9f3a-feaf-4033-8603-687784dc7e51   my-root-key   crn:v1:bluemix:public:kms:us-south:a/ea998d3389c3473aa0987652b46fb146:390086ac-76fa-4094-8cf3-c0829bd69526:key:c36e9f3a-feaf-4033-8603-687784dc7e51

Example 3

List keys in JSON format.

The --output json parameter implies the --crn (cloud resource name) parameter.

# list keys
$ ibmcloud kp keys --output json

[
  {
    "id": "5f2cc155-fe16-492c-845c-4d1f0688c7ba",
    "name": "my-root-key",
    "type": "application/vnd.ibm.kms.key+json",
    "algorithmType": "AES",
    "createdBy": "user id ...<redacted>...",
    "creationDate": "2020-05-10T18:04:01Z",
    "lastUpdateDate": "2020-05-10T18:04:01Z",
    "extractable": false,
    "state": 1,
    "crn": "crn:v1:bluemix:public:kms:us-south:a/ea998d3389c3473aa0987652b46fb146:390086ac-76fa-4094-8cf3-c0829bd69526:key:5f2cc155-fe16-492c-845c-4d1f0688c7ba"
    },
    {
        "id": "c36e9f3a-feaf-4033-8603-687784dc7e51",
    "name": "my-root-key",
    "type": "application/vnd.ibm.kms.key+json",
    "algorithmType": "AES",
    "createdBy": "user id ...<redacted>...",
    "creationDate": "2020-05-10T17:56:37Z",
    "lastUpdateDate": "2020-05-10T17:56:37Z",
    "extractable": false,
    "state": 1,
    "crn": "crn:v1:bluemix:public:kms:us-south:a/ea998d3389c3473aa0987652b46fb146:390086ac-76fa-4094-8cf3-c0829bd69526:key:c36e9f3a-feaf-4033-8603-687784dc7e51"
  }
]

Example 4

List keys and iterate over them, showing details.

# list keys and convert to a list
$ KEYS=$(ibmcloud kp keys --output json | jq -r '.[] | .id')

$ for key in $(echo "${KEYS}"); do
    ibmcloud kp key show ${key}
done

Grabbing info for key id: 5f2cc155-fe16-492c-845c-4d1f0688c7ba...
OK
Key ID                                 Key Name      Description   Creation Date                   Expiration Date
5f2cc155-fe16-492c-845c-4d1f0688c7ba   my-root-key                 2020-05-10 18:04:01 +0000 UTC   Key does not expire

Grabbing info for key id: c36e9f3a-feaf-4033-8603-687784dc7e51...
OK
Key ID                                 Key Name      Description   Creation Date                   Expiration Date
c36e9f3a-feaf-4033-8603-687784dc7e51   my-root-key                 2020-05-10 17:56:37 +0000 UTC   Key does not expire

Example 5

Create 20 keys and show them in groups of 5 using the kp keys -n -s options.

# create 20 test keys
$ for I in {1..20}; do
    KEY_ID=$(ibmcloud kp key create my-test-key-$I --output json | jq -r '.["id"]')
    KEY_NAME=$(ibmcloud kp key show $KEY_ID --output json | jq -r '.["name"]')
    echo $KEY_ID $KEY_NAME
done

b70f62a1-4d52-4526-91a9-ce47bf14c2a5 my-test-key-1
215f592c-3e42-47b6-867c-3cc1cce8a8fd my-test-key-2
df530c55-39c0-44e8-b7db-397593f70d90 my-test-key-3
768c9ceb-368b-46f7-9b1d-be211e036fe1 my-test-key-4
f141be88-5a34-4290-8513-4f01d934e75a my-test-key-5
b8794334-eea6-4c0d-8fe1-8086300b13f7 my-test-key-6
87679194-52d0-42af-81e1-bffd64f87315 my-test-key-7
cc7faf46-43cf-43b2-be98-7d1815371639 my-test-key-8
e9b08526-3227-406c-b83f-c28844bd952b my-test-key-9
3ee0d859-2968-4444-8e4d-3d28614f055c my-test-key-10
bc459a2f-56cb-445e-b4ee-9d1866b57560 my-test-key-11
62090ba8-7363-408e-9edc-aa9fb69c09be my-test-key-12
3b4b0511-00df-48e6-ad65-fad35bb6ce17 my-test-key-13
16276369-ba81-4eb5-be92-f13512147ad4 my-test-key-14
3d683d56-d340-40cb-b8b6-605dcfded01f my-test-key-15
10954149-0217-472d-8137-42fc330dbd03 my-test-key-16
54dd2745-7718-487f-85e6-a67e758dd945 my-test-key-17
3a5a3b52-6942-463d-9f7a-5b216bbf5123 my-test-key-18
90138be5-1dd1-4eea-b7c1-73cc8609e7f7 my-test-key-19
cf0a3d8b-4856-4aa5-be6a-88cca465eab0 my-test-key-20

# this is the same list sorted in KEY_ID order
# this is the order we expect when listing keys

10954149-0217-472d-8137-42fc330dbd03 my-test-key-16
16276369-ba81-4eb5-be92-f13512147ad4 my-test-key-14
215f592c-3e42-47b6-867c-3cc1cce8a8fd my-test-key-2
3a5a3b52-6942-463d-9f7a-5b216bbf5123 my-test-key-18
3b4b0511-00df-48e6-ad65-fad35bb6ce17 my-test-key-13

3d683d56-d340-40cb-b8b6-605dcfded01f my-test-key-15
3ee0d859-2968-4444-8e4d-3d28614f055c my-test-key-10
54dd2745-7718-487f-85e6-a67e758dd945 my-test-key-17
62090ba8-7363-408e-9edc-aa9fb69c09be my-test-key-12
768c9ceb-368b-46f7-9b1d-be211e036fe1 my-test-key-4

87679194-52d0-42af-81e1-bffd64f87315 my-test-key-7
90138be5-1dd1-4eea-b7c1-73cc8609e7f7 my-test-key-19
b70f62a1-4d52-4526-91a9-ce47bf14c2a5 my-test-key-1
b8794334-eea6-4c0d-8fe1-8086300b13f7 my-test-key-6
bc459a2f-56cb-445e-b4ee-9d1866b57560 my-test-key-11

cc7faf46-43cf-43b2-be98-7d1815371639 my-test-key-8
cf0a3d8b-4856-4aa5-be6a-88cca465eab0 my-test-key-20
df530c55-39c0-44e8-b7db-397593f70d90 my-test-key-3
e9b08526-3227-406c-b83f-c28844bd952b my-test-key-9
f141be88-5a34-4290-8513-4f01d934e75a my-test-key-5

# define a function for listing keys
$ list_keys () {
    N=$1
    S=$2
    KEYS=$(ibmcloud kp keys --number-of-keys $N --starting-offset $S --output json | jq -r '.[] | .id')
    for KEY_ID in $(echo "${KEYS}"); do
        KEY_ID=$(ibmcloud kp key show $KEY_ID --output json | jq -r '.["id"]')
    KEY_NAME=$(ibmcloud kp key show $KEY_ID --output json | jq -r '.["name"]')
    echo $KEY_ID $KEY_NAME
    done
}

# list the first group of keys
$ list_keys 5 0

10954149-0217-472d-8137-42fc330dbd03 my-test-key-16
16276369-ba81-4eb5-be92-f13512147ad4 my-test-key-14
215f592c-3e42-47b6-867c-3cc1cce8a8fd my-test-key-2
3a5a3b52-6942-463d-9f7a-5b216bbf5123 my-test-key-18
3b4b0511-00df-48e6-ad65-fad35bb6ce17 my-test-key-13

# list the second group of keys
$ list_keys 5 5

3d683d56-d340-40cb-b8b6-605dcfded01f my-test-key-15
3ee0d859-2968-4444-8e4d-3d28614f055c my-test-key-10
54dd2745-7718-487f-85e6-a67e758dd945 my-test-key-17
62090ba8-7363-408e-9edc-aa9fb69c09be my-test-key-12
768c9ceb-368b-46f7-9b1d-be211e036fe1 my-test-key-4

# list the third group of keys
$ list_keys 5 10

87679194-52d0-42af-81e1-bffd64f87315 my-test-key-7
90138be5-1dd1-4eea-b7c1-73cc8609e7f7 my-test-key-19
b70f62a1-4d52-4526-91a9-ce47bf14c2a5 my-test-key-1
b8794334-eea6-4c0d-8fe1-8086300b13f7 my-test-key-6
bc459a2f-56cb-445e-b4ee-9d1866b57560 my-test-key-11

# list the last group of keys
$ list_keys 5 15

cc7faf46-43cf-43b2-be98-7d1815371639 my-test-key-8
cf0a3d8b-4856-4aa5-be6a-88cca465eab0 my-test-key-20
df530c55-39c0-44e8-b7db-397593f70d90 my-test-key-3
e9b08526-3227-406c-b83f-c28844bd952b my-test-key-9
f141be88-5a34-4290-8513-4f01d934e75a my-test-key-5

# delete the test keys
$ KEYS=$(ibmcloud kp keys --output json | jq -r '.[] | .id')

$ for KEY_ID in $(echo "${KEYS}"); do
    KEY_NAME=$(ibmcloud kp key show $KEY_ID --output json | jq -r '.["name"]')
    if [[ $KEY_NAME == *"my-test-key-"* ]]; then
        echo "Deleting... $KEY_NAME $KEY_ID"
    ibmcloud kp key delete $KEY_ID
    fi
done

(output not shown)

Example 6

Lists the keys based on key states (Active, Suspended) in the Key Protect instance.

# list active and suspended keys
$ ibmcloud kp keys --key-states active,suspended

Retrieving keys...
OK
Key ID                                 Key Name
ef2cc155-fe56-492c-845c-4d1f0688c7ba   my-active-key
636e9f3a-feaf-4033-8603-687754dc7e51   my-suspended-key

Example 7

Lists the keys based on key type (root) in the Key Protect instance.

# list root keys
$ ibmcloud kp keys -t root

Retrieving keys...
OK
Key ID                                 Key Name
2f1cb135-fa16-40dc-815c-4d1f0ee8c7ba   my-root-key

Example 8

Lists the keys in the Key Protect instance with the key name or alias exactly matching the characters in the string "TEST" without quotation marks.

# list keys with identifiers exactly matching TEST
$ ibmcloud kp keys -l exact:TEST

Retrieving keys...
OK
Key ID                                 Key Name
636e9f3a-feaf-4033-8603-687754dc7e51   TEST

Example 9

Lists the keys in the Key Protect instance and sort the keys based on their id and the date the key was created starting with the newest (the hyphen, '-', indicates sort by descending order).

# sort keys by id and descending creationDate 
$ ibmcloud kp keys -b id,-creationDate

Retrieving keys...
OK
Key ID                                 Key Name
ef2cc155-fe56-492c-845c-4d1f0688c7ba   my-last-key
2f1cb135-fa16-40dc-815c-4d1f0ee8c7ba   my-first-key

Example 1

If the REGION parameter is not specified, you are prompted to select a region.

# set the region endpoint
$ ibmcloud kp region-set

Select a Region:
1. au-syd
2. ca-tor
3. eu-de
4. eu-gb
5. jp-osa
6. jp-tok
7. us-east
8. us-south
9. br-sao
10. staging (us-south)
Enter a number: 
5
OK

Example 2

Set the region explicitly.

# set the region endpoint to "us-south"
$ ibmcloud kp region-set us-south

OK

The REGION must be a valid regional endpoint.

# this should fail (not a valid regional endpoint)
$ ibmcloud kp region-set not-a-region

FAILED

Example 3

Unset (remove) the regional endpoint.

# remove the regional endpoint
$ ibmcloud kp region-set -u

OK

Example 1

List all registrations, which may include cloud resources such as databases, storage, compute, containers, or messaging.

This example shows the registration between Cloud Object Storage (COS) and Key Protect.

# view all registrations
$ ibmcloud kp registrations --output json

[
  {
    "keyId": "2cbea94c-6070-4a24-b0f8-7a56e4d7cb6f",
    "resourceCrn": "crn:v1:bluemix:public:cloud-object-storage:global:a/ea998d3389c3473aa0987652b46fb146:4b636e74-f3ca-40bb-80b8-3bd21801ccb8:bucket:my-cos-kms-bucket",
    "createdBy": "crn-crn:v1:bluemix:public:cloud-object-storage:global:a/ea998d3389c3473aa0987652b46fb146:4b636e74-f3ca-40bb-80b8-3bd21801ccb8::",
    "creationDate": "2020-06-15T16:07:37Z",
    "lastUpdated": "2020-06-15T16:07:37Z",
    "keyVersion": { "id": "2cbea94c-6070-4a24-b0f8-7a56e4d7cb6f", "creationDate": "2020-06-15T16:05:53Z"
    }
  }
]

Example 2

This example shows the full lifecycle of two cloud resources (Cloud Object Storage and Key Protect - from creating Key Protect instances and creating a policy between them to deleting the instances.

A summary of the steps is:

These commands show COS and Key Protect service plans. The ibmcloud resource service-instance-create command requires a service plan name and a location, which is in the catalog.

# show the catalog offerings for cloud object storage (COS) and Key Protect
$ ibmcloud catalog service cloud-object-storage

$ ibmcloud catalog service kms

The example covers multiple steps and should be performed in consultation with the summary provided.

# create a Cloud Object Storage (COS) instance
# "lite" is the pricing plan and "global" is the region
$ COS_NAME=my-cos-1

$ ibmcloud resource service-instance-create $COS_NAME cloud-object-storage lite global

Creating service instance my-cos-1 in resource group Default of account <account name> as <email address>...
OK
Service instance my-cos-1 was created.
Name:             my-cos-1
ID:               crn:v1:bluemix:public:cloud-object-storage:global:a/ea998d3389c3473aa0987652b46fb146:4b636e74-f3ca-40bb-80b8-3bd21801ccb8::
GUID:             4b636e74-f3ca-40bb-80b8-3bd21801ccb8
Location:         global
State:            active
Type:             service_instance
Sub Type:
Allow Cleanup:    false
Locked:           false
Created at:       2020-06-15T16:03:39Z
Updated at:       2020-06-15T16:03:39Z
Last Operation:             Status    create succeeded             Message   Completed create instance operation

# capture the COS instance id (GUID)
$ COS_INSTANCE_ID=4b636e74-f3ca-40bb-80b8-3bd21801ccb8

# create a Key Management Service (KMS) service instance
# "tiered-pricing" is the pricing plan and "us-south" is the region
$ KMS_NAME=my-kms-1

$ ibmcloud resource service-instance-create $KMS_NAME kms tiered-pricing us-south

Creating service instance my-kms-1 in resource group Default of account <account name> as <email address>...
OK
Service instance my-kms-1 was created.
Name:             my-kms-1
ID:               crn:v1:bluemix:public:kms:us-south:a/ea998d3389c3473aa0987652b46fb146:b3933ab0-d579-46fc-8ed5-351aea657b9a::
GUID:             b3933ab0-d579-46fc-8ed5-351aea657b9a
Location:         us-south
State:            active
Type:             service_instance
Sub Type:         kms
Allow Cleanup:    false
Locked:           false
Created at:       2020-06-15T16:04:40Z
Updated at:       2020-06-15T16:04:40Z
Last Operation:             Status    create succeeded             Message   Completed create instance operation

# capture the Key Protect (KP) instance id (GUID)
$ KP_INSTANCE_ID=b3933ab0-d579-46fc-8ed5-351aea657b9a

# create a policy for COS to read KMS; source is COS, target is KMS
$ ibmcloud iam authorization-policy-create cloud-object-storage kms Reader \
  --source-service-instance-id $COS_INSTANCE_ID \
  --target-service-instance-id $KP_INSTANCE_ID

Creating authorization policy under account ea998d3389c3473aa0987652b46fb146 as <email address>...
OK
Authorization policy 18cfc980-4458-4313-972e-93f312cdcd81 was created.
ID:                        18cfc980-4458-4313-972e-93f312cdcd81
Source service name:       cloud-object-storage
Source service instance:   4b636e74-f3ca-40bb-80b8-3bd21801ccb8
Target service name:       kms
Target service instance:   b3933ab0-d579-46fc-8ed5-351aea657b9a
Roles:                     Reader

# capture the COS-to-KMS authorization policy id
$ COS_KMS_AUTHORIZATION=18cfc980-4458-4313-972e-93f312cdcd81

# create a KP root key that COS uses to encrypt data
$ ibmcloud kp key create my-cos-key --output json

{
  "id": "2cbea94c-6070-4a24-b0f8-7a56e4d7cb6f",
  "name": "my-cos-key",
  "type": "application/vnd.ibm.kms.key+json",
  "extractable": false,
  "state": 1,
  "crn": "crn:v1:bluemix:public:kms:us-south:a/ea998d3389c3473aa0987652b46fb146:b3933ab0-d579-46fc-8ed5-351aea657b9a:key:2cbea94c-6070-4a24-b0f8-7a56e4d7cb6f"
}

# capture the KP root key id
$ MY_COS_KEY_ID=2cbea94c-6070-4a24-b0f8-7a56e4d7cb6f

# create a COS bucket and set KP encryption
#   must be done in the console user interface (UI) because
#   there is no API or CLI support at this time
# 1 - In the UI, go to... Resource list -> Storage -> my-cos-1
# 2 - Create bucket -> custom bucket
# 3 - Properties of a custom bucket
#   a - bucket name: my-cos-kms-bucket
#   b - location: us-south (same region as KP)
#   c - checkbox: Key Protect
#   d - instance: my-kms-1
#   e - key name: my-cos-key
#   f - button: Create bucket

# capture the name of the COS bucket that was created
$ COS_BUCKET=my-cos-kms-bucket

# view the KP registration; it's a result of creating the COS bucket
$ ibmcloud kp registrations --output json

[
  {
    "keyId": "2cbea94c-6070-4a24-b0f8-7a56e4d7cb6f",
    "resourceCrn": "crn:v1:bluemix:public:cloud-object-storage:global:a/ea998d3389c3473aa0987652b46fb146:4b636e74-f3ca-40bb-80b8-3bd21801ccb8:bucket:my-cos-kms-bucket",
    "createdBy": "crn-crn:v1:bluemix:public:cloud-object-storage:global:a/ea998d3389c3473aa0987652b46fb146:4b636e74-f3ca-40bb-80b8-3bd21801ccb8::",
    "creationDate": "2020-06-15T16:07:37Z",
    "lastUpdated": "2020-06-15T16:07:37Z",
    "keyVersion": { "id": "2cbea94c-6070-4a24-b0f8-7a56e4d7cb6f", "creationDate": "2020-06-15T16:05:53Z"
    }
  }
]

# list the bucket
$ ibmcloud cos list-buckets --ibm-service-instance-id $COS_INSTANCE_ID

OK
1 bucket found in your account:
Name                Date Created
my-cos-kms-bucket   Jun 15, 2020 at 16:07:38

# upload an object to COS
$ ibmcloud cos put-object --bucket $COS_BUCKET --key '/cos-file.txt' --body cos-file-upload.txt

OK
Successfully uploaded object '/cos-file.txt' to bucket 'my-cos-kms-bucket'.

# get the object from COS
$ ibmcloud cos get-object --bucket $COS_BUCKET --key '/cos-file.txt' cos-file-download.txt

OK
Successfully downloaded '/cos-file.txt' from bucket 'my-cos-kms-bucket'
20 B downloaded.

# verify that the upload and download files are the same
$ cat cos-file-upload.txt

This is a test file

$ cat cos-file-download.txt

This is a test file

# delete the object
$ ibmcloud cos delete-object --bucket $COS_BUCKET --key '/cos-file.txt' --force

OK
Delete '/cos-file.txt' from bucket 'my-cos-kms-bucket' ran successfully.

# delete the bucket
$ ibmcloud cos delete-bucket --bucket $COS_BUCKET --force

OK
Successfully deleted bucket 'my-cos-kms-bucket'. The bucket 'my-cos-kms-bucket' will be available for reuse after 15 minutes.

# list the bucket (it should no longer exist)
$ ibmcloud cos list-buckets --ibm-service-instance-id $COS_INSTANCE_ID

OK
No buckets found in your account.

# view the KP registration (it should no longer exist)
$ ibmcloud kp registrations --output json

# delete the KP root key; COS no longer uses it
$ ibmcloud kp key delete $MY_COS_KEY_ID --output json

{
  "id": "2cbea94c-6070-4a24-b0f8-7a56e4d7cb6f"
}

# delete the authorization policy between COS AND KMS
$ ibmcloud iam authorization-policy-delete $COS_KMS_AUTHORIZATION --force

Deleting authorization policy 18cfc980-4458-4313-972e-93f312cdcd81 under account ea998d3389c3473aa0987652b46fb146...
OK
Authorization policy 18cfc980-4458-4313-972e-93f312cdcd81 is deleted successfully

# view the authorization policy (it should no longer exist)
$ ibmcloud iam authorization-policies

Getting authorization policies under account ea998d3389c3473aa0987652b46fb146 as <email address>...
OK
No policy found

# delete the KMS instance
$ ibmcloud resource service-instance-delete $KMS_NAME --force

Deleting service instance my-kms-1 in resource group Default under account <account name> as <email address>...
OK
Service instance my-kms-1 with ID crn:v1:bluemix:public:kms:us-south:a/ea998d3389c3473aa0987652b46fb146:b3933ab0-d579-46fc-8ed5-351aea657b9a:: is deleted successfully

# delete the COS instance
$ ibmcloud resource service-instance-delete $COS_NAME --force

Deleting service instance my-cos-1 in resource group Default under account <account name> as <email address>...
OK
Service instance my-cos-1 with ID crn:v1:bluemix:public:cloud-object-storage:global:a/ea998d3389c3473aa0987652b46fb146:4b636e74-f3ca-40bb-80b8-3bd21801ccb8:: is deleted successfully

# view resources (COS and KMS should no longer exist)
$ ibmcloud resource service-instances

Retrieving instances with type service_instance in resource group Default in all locations under account <account name> as <email address>...
OK
No service instance found.

Example 3

This example shows what happens when one of the following occurs between COS and Key Protect (KP) - COS is not able to access the Key Protect root key.

• Delete the KP root key
• Remove the CMS/KP authorization policy

This example does not show command output except when relevant.

# create a Cloud Object Storage (COS) service instance
# "lite" is the pricing plan and "global" is the region
$ COS_NAME=my-cos-1

$ ibmcloud resource service-instance-create $COS_NAME cloud-object-storage lite global

# capture the COS instance id (GUID)
$ COS_INSTANCE_ID=c488e11a-c8a0-4688-b002-9327266ea55f

# create a Key Management Service (KMS) service instance
# "tiered-pricing" is the pricing plan and "us-south" is the region
$ KMS_NAME=my-kms-1

$ ibmcloud resource service-instance-create $KMS_NAME kms tiered-pricing us-south

# capture the Key Protect (KP) instance id (GUID)
$ KP_INSTANCE_ID=26f4b198-952a-47ab-9f44-ef69c038b3c5

# create a policy for COS to read KMS; source is COS, target is KMS (Key Protect)
$ ibmcloud iam authorization-policy-create cloud-object-storage kms Reader \
  --source-service-instance-id $COS_INSTANCE_ID \
  --target-service-instance-id $KP_INSTANCE_ID

# capture the COS-to-KMS authorization policy id
$ COS_KMS_AUTHORIZATION=594b946e-0e90-44ea-ac62-6cbb42450cd5

# create a KP root key that COS uses to encrypt data
$ ibmcloud kp key create my-cos-key --output json

# capture the KP root key id
$ MY_COS_KEY_ID=464d78c3-57dc-49a5-b932-8ebf8f8c7771

# create a COS bucket and set KP encryption
#   must be done in the console user interface (UI) because
#   there is no API or CLI support at this time

# capture the name of the COS bucket that was created
$ COS_BUCKET=my-cos-kms-bucket

# upload an object to COS
$ ibmcloud cos put-object --bucket $COS_BUCKET --key '/cos-file.txt' --body cos-file-upload.txt

# delete the authorization policy between COS AND KMS - this breaks everything
$ ibmcloud iam authorization-policy-delete $COS_KMS_AUTHORIZATION --force

# get the object from COS - this fails because COS no longer has access to KMS
$ ibmcloud cos get-object --bucket $COS_BUCKET --key '/cos-file.txt' cos-file-download.txt

FAILED
ServiceNotAuthorized: The specified COS Service Instance does not have sufficient
    permissions to access the resource provided in the ibm-sse-kp-customer-root-key-crn request header
status code: 401,
request id: a51e1da3-9bf7-4cc9-9eb0-0d074c7f9093,
host id:

# delete the object
$ ibmcloud cos delete-object --bucket $COS_BUCKET --key '/cos-file.txt' --force

# delete the bucket
$ ibmcloud cos delete-bucket --bucket $COS_BUCKET --force

# delete the KP root key - this fails because the registration was not deleted
$ ibmcloud kp key delete $MY_COS_KEY_ID --output json

FAILED
kp.Error:
    correlation_id='fffdd8a9-405a-4a91-a5a7-52c30d11424d',
    msg='Conflict: Key could not be deleted. Please see "reasons" for more details.',
    reasons='[PROTECTED_RESOURCE_ERR: Key is protecting one or more cloud resources -
        FOR_MORE_INFO_REFER: https://cloud.ibm.com/docs/key-protect?topic=key-protect-troubleshooting#unable-to-delete-keys]'

# delete the KP root key; use --force because the registration between COS and KMS still exists
$ ibmcloud kp key delete $MY_COS_KEY_ID --force --output json

# delete the KMS instance
$ ibmcloud resource service-instance-delete $KMS_NAME --force

# delete the COS instance
$ ibmcloud resource service-instance-delete $COS_NAME --force

# view resources (COS and KMS should no longer exist)
$ ibmcloud resource service-instances

Retrieving instances with type service_instance in resource group Default in all locations under account <account name> as <email address>...
OK
No service instance found.

Example 1

This example creates KMIP adapter with the native_1.0 profile

$ ibmcloud kp kmip adapter-create -n myadapter -k 47a0ad90-204d-4e45-aa5b-68ed40a05fa2 -p native_1.0 -d "my description"
Targeting endpoint: https://qa.us-south.kms.test.cloud.ibm.com
Creating KMIP Adapter...
OK
Adapter ID                             Adapter Profile   Adapter Name   Adapter Description   
d6a00af1-277f-40e8-b33e-da3a68752209   native_1.0        myadapter      my description  
$ ibmcloud kp kmip adapters
Targeting endpoint: https://qa.us-south.kms.test.cloud.ibm.com
Listing KMIP Adapters...
OK
Adapter ID                             Adapter Profile   Adapter Name   Created At                      Updated At   
d6a00af1-277f-40e8-b33e-da3a68752209   native_1.0        myadapter      2024-03-20 22:06:43 +0000 UTC   2024-03-20 22:06:43 +0000 UTC   

Example 1

Note that there are some attributes to the adapter only visible in the JSON output format.

$ ibmcloud kp key create rootKmip
Targeting endpoint: https://qa.us-south.kms.test.cloud.ibm.com
Creating key: 'rootKmip', in instance: '8944cc2d-7e00-46b2-baa4-787051e0f7b3'...
OK
Key ID                                 Key Name   
47a0ad90-204d-4e45-aa5b-68ed40a05fa2   rootKmip   
$ ibmcloud kp kmip adapter-create -n myadapter -k 47a0ad90-204d-4e45-aa5b-68ed40a05fa2 -p native_1.0
Targeting endpoint: https://qa.us-south.kms.test.cloud.ibm.com
Creating KMIP Adapter...
OK
Adapter ID                             Adapter Profile   Adapter Name   Adapter Description   
d6a00af1-277f-40e8-b33e-da3a68752209   native_1.0        myadapter      -   
# retreiving adapter by name
$ ibmcloud kp kmip adapter myadapter
Targeting endpoint: https://qa.us-south.kms.test.cloud.ibm.com
Getting KMIP Adapter...
OK
Adapter ID                             Adapter Profile   Adapter Name   Created At                      Updated At                      Adapter Description   
d6a00af1-277f-40e8-b33e-da3a68752209   native_1.0        myadapter      2024-03-20 22:06:43 +0000 UTC   2024-03-20 22:06:43 +0000 UTC   -   
# retrieving adapter by ID
$ ibmcloud kp kmip adapter d6a00af1-277f-40e8-b33e-da3a68752209 -o json
{
    "id": "d6a00af1-277f-40e8-b33e-da3a68752209",
    "profile": "native_1.0",
    "profile_data": {
        "crk_id": "47a0ad90-204d-4e45-aa5b-68ed40a05fa2"
    },
    "name": "myadapter",
    "description": "",
    "created_by": "IBMid-664003LB2T",
    "created_at": "2024-03-20T22:06:43Z",
    "updated_by": "IBMid-664003LB2T",
    "updated_at": "2024-03-20T22:06:43Z"
}

Example 1

$ ibmcloud kp kmip adapters -n 100 -s 0
Targeting endpoint: https://qa.us-south.kms.test.cloud.ibm.com
Listing KMIP Adapters...
OK
Adapter ID                             Adapter Profile   Adapter Name   Created At                      Updated At   
d6a00af1-277f-40e8-b33e-da3a68752209   native_1.0        myadapter      2024-03-20 22:06:43 +0000 UTC   2024-03-20 22:06:43 +0000 UTC 

Example 1

$ ibmcloud kp kmip adapter-create -n adap -k 47a0ad90-204d-4e45-aa5b-68ed40a05fa2 -p native_1.0
Targeting endpoint: https://qa.us-south.kms.test.cloud.ibm.com
Creating KMIP Adapter...
OK
Adapter ID                             Adapter Profile   Adapter Name   Adapter Description   
e97e4297-4a6f-41c9-ae67-0920715964fd   native_1.0        adap           -   
$ ibmcloud kp kmip adapter-delete e97e4297-4a6f-41c9-ae67-0920715964fd
Targeting endpoint: https://qa.us-south.kms.test.cloud.ibm.com
Deleting KMIP Adapter...
OK

Example 1

This example shows two ways of uploading the same certificate file.

$ ibmcloud kp key create rootKmip
Targeting endpoint: https://qa.us-south.kms.test.cloud.ibm.com
Creating key: 'rootKmip', in instance: '8944cc2d-7e00-46b2-baa4-787051e0f7b3'...
OK
Key ID                                 Key Name   
47a0ad90-204d-4e45-aa5b-68ed40a05fa2   rootKmip   
$ ibmcloud kp kmip adapter-create -n myadapter -k 47a0ad90-204d-4e45-aa5b-68ed40a05fa2 -p native_1.0
Targeting endpoint: https://qa.us-south.kms.test.cloud.ibm.com
Creating KMIP Adapter...
OK
Adapter ID                             Adapter Profile   Adapter Name   Adapter Description   
d6a00af1-277f-40e8-b33e-da3a68752209   native_1.0        myadapter      -   

$ export CERT=$(cat ./cert.pem) 

$ ibmcloud kp kmip cert-create -n mycert -c "$CERT" -a myadapter
Targeting endpoint: https://qa.us-south.kms.test.cloud.ibm.com
Creating KMIP Client Certificate...
OK
Certificate ID                         Certificate Name   Created At   
3f550b96-86bc-44fe-8d1d-113e57067219   mycert             2024-03-20 22:08:03 +0000 UTC   

## Alternatively, you can also provide the filepath of the certificate

$ ibmcloud kp kmip cert-delete mycert -a myadapter
Targeting endpoint: https://qa.us-south.kms.test.cloud.ibm.com
Deleting KMIP Client Certificate...
OK

$ ibmcloud kp kmip cert-create -n mycert -c @./cert.pem -a myadapter
Targeting endpoint: https://qa.us-south.kms.test.cloud.ibm.com
Creating KMIP Client Certificate...
OK
Certificate ID                         Certificate Name   Created At   
a279fded-06d1-45a1-8a95-901f194fb937   mycert             2024-03-20 22:11:34 +0000 UTC   

Example 1

Getting a certificate by name:

$ ibmcloud kp kmip cert mycert -a myadapter
Targeting endpoint: https://qa.us-south.kms.test.cloud.ibm.com
Getting KMIP Client Certificate...
OK
Certificate ID                         Certificate Name   Created At   
a279fded-06d1-45a1-8a95-901f194fb937   mycert             2024-03-20 22:11:34 +0000 UTC   

Example 2

Getting a certificate by UUID in JSON format. The PEM-format contents of the certificate will be returned in the JSON body.

$ ibmcloud kp kmip cert a279fded-06d1-45a1-8a95-901f194fb937  -a myadapter -o json
{
    "id": "a279fded-06d1-45a1-8a95-901f194fb937",
    "name": "mycert",
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIFqzCCA5OgAwIBAgIUNXqfJMkAHOBHz6+ekETDlCqIEqUwDQYJKoZIhvcNAQEL\nBQAw
    ... CERTIFICATE CONTENTS ABBREVIATED ...
    Y6uFtHuQSpud0C\n-----END CERTIFICATE-----\n",
    "created_by": "IBMid-12345678",
    "created_at": "2024-03-20T22:11:34Z"
}

Example 1

$ ibmcloud kp kmip certs -a myadapter
Targeting endpoint: https://qa.us-south.kms.test.cloud.ibm.com
Listing KMIP Client Certificates...
OK
Certificate ID                         Certificate Name   Created At   
a279fded-06d1-45a1-8a95-901f194fb937   mycert             2024-03-20 22:11:34 +0000 UTC   

Example 1

$ ibmcloud kp kmip cert-delete -a myadapter mycert
Targeting endpoint: https://qa.us-south.kms.test.cloud.ibm.com
Deleting KMIP Client Certificate...
OK

Example 1

$ ibmcloud kp kmip object 12365a82-5404-4bd9-a4c7-2b628ee18304 -a testadapter 
Targeting endpoint: https://qa.us-south.kms.test.cloud.ibm.com
Getting KMIP Object...
OK
Object ID                              Object Type     Object State   Created At                      Updated At   
12365a82-5404-4bd9-a4c7-2b628ee18304   Symmetric Key   Active         2024-03-14 21:01:45 +0000 UTC   2024-03-14 21:01:45 +0000 UTC   

Example 2

Getting a KMIP Object as a JSON will show some extra attributes not visible in the normal table view.

$ ibmcloud kp kmip object 12365a82-5404-4bd9-a4c7-2b628ee18304 -a testadapter -o json
{
    "id": "12365a82-5404-4bd9-a4c7-2b628ee18304",
    "kmip_object_type": 2,
    "state": 2,
    "created_by_kmip_client_cert_id": "531c18f3-4e37-447e-a7e0-e8676407bb75",
    "created_by": "IBMid-123456",
    "created_at": "2024-03-14T21:01:45Z",
    "updated_by_kmip_client_cert_id": "531c18f3-4e37-447e-a7e0-e8676407bb75",
    "updated_by": "IBMid-123456",
    "updated_at": "2024-03-14T21:01:45Z"
}

Example 1

$ ibmcloud kp kmip objects -a myadapter
Targeting endpoint: https://qa.us-south.kms.test.cloud.ibm.com
Listing KMIP Objects...
OK
Object ID                              Object Type     Object State   Created At                      Updated At   
00196c59-c5c2-42d8-9729-703cd0389f60   Symmetric Key   Compromised    2024-03-14 20:47:54 +0000 UTC   2024-03-14 20:47:54 +0000 UTC   
02f1043c-0494-4399-82af-5395a14b019f   Symmetric Key   Pre-Active     2024-03-14 20:58:06 +0000 UTC   2024-03-14 20:58:06 +0000 UTC   
08082ff4-821b-4689-83ec-15cac5bd1939   Symmetric Key   Pre-Active     2024-02-22 00:10:46 +0000 UTC   2024-02-22 00:11:23 +0000 UTC   
0c1ea28d-dfaa-404a-b9c4-fcdc3f5d8b02   Symmetric Key   Deactivated    2024-03-14 21:05:48 +0000 UTC   2024-03-14 21:05:48 +0000 UTC   
10b49b05-0101-4234-927b-20a3356da291   Symmetric Key   Pre-Active     2024-03-14 21:26:54 +0000 UTC   2024-03-14 21:26:54 +0000 UTC   
12365a82-5404-4bd9-a4c7-2b628ee18304   Symmetric Key   Active         2024-03-14 21:01:45 +0000 UTC   2024-03-14 21:01:45 +0000 UTC

Example 2

Using the -f flag to filter for objects of a specific state. Use commas to specify multiple states.

$ ibmcloud kp kmip objects -a testadapter -f 5,6
Targeting endpoint: https://qa.us-south.kms.test.cloud.ibm.com
Listing KMIP Objects...
OK
Object ID                              Object Type     Object State            Created At                      Updated At   
03d38805-2bb2-4aa0-bbf3-dc4a6d5d0475   Symmetric Key   Destroyed               2024-03-14 20:47:58 +0000 UTC   2024-03-14 20:47:58 +0000 UTC   
08c94f34-0100-4331-b759-5937ed5b1228   Symmetric Key   Destroyed               2024-03-14 20:46:38 +0000 UTC   2024-03-14 20:46:38 +0000 UTC   
1a13e112-41f8-4d52-be08-a0946b8c22fa   Symmetric Key   Destroyed Compromised   2024-03-14 20:58:20 +0000 UTC   2024-03-14 20:58:20 +0000 UTC   

Example 1

$ ibmcloud kp kmip object-delete 9b2f5af5-3534-4f02-8836-f89af37c4351 -a testadapter
Targeting endpoint: https://qa.us-south.kms.test.cloud.ibm.com
Deleting KMIP Object...
OK