Finding KMS keys and key material - Amazon Key Management Service
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China.

Finding KMS keys and key material

If you manage an Amazon CloudHSM key store, you might need to identify the KMS keys in each Amazon CloudHSM key store. For example, you might need to do some of the following tasks.

  • Track the KMS keys in Amazon CloudHSM key store in Amazon CloudTrail logs.

  • Predict the effect on KMS keys of disconnecting an Amazon CloudHSM key store.

  • Schedule deletion of KMS keys before you delete an Amazon CloudHSM key store.

In addition, you might want to identify the keys in your Amazon CloudHSM cluster that serve as key material for your KMS keys. Although Amazon KMS manages the KMS keys and the key material, you still retain control of and responsibility for the management of your Amazon CloudHSM cluster, as well as the HSMs and backups and the keys in the HSMs. You might need to identify the keys in order to audit the key material, protect it from accidental deletion, or delete it from HSMs and cluster backups after deleting the KMS key.

All key material for the KMS keys in your Amazon CloudHSM key store is owned by the kmsuser crypto user (CU). Amazon KMS sets the key label attribute, which is viewable only in Amazon CloudHSM, to the Amazon Resource Name (ARN) of the KMS key.

To find KMS keys and key material, use any of the following techniques.

Find the KMS keys in an Amazon CloudHSM key store

If you manage an Amazon CloudHSM key store, you might need to identify the KMS keys in each Amazon CloudHSM key store. You can use this information track the KMS key operations in Amazon CloudTrail logs, predict the effect on KMS keys of disconnecting a custom key store, or schedule deletion of KMS keys before you delete an Amazon CloudHSM key store.

To find the KMS keys in an Amazon CloudHSM key store (console)

To find the KMS keys in a particular Amazon CloudHSM key store, on the Customer managed keys page, view the values in the Custom Key Store Name or Custom Key Store ID fields. To identify KMS keys in any Amazon CloudHSM key store, look for KMS keys with an Origin value of Amazon CloudHSM. To add optional columns to the display, choose the gear icon in the upper right corner of the page.

To find the KMS keys in an Amazon CloudHSM key store (API)

To find the KMS keys in an Amazon CloudHSM key store, use the ListKeys and DescribeKey operations and then filter by CustomKeyStoreId value. Before running the examples, replace the fictitious custom key store ID values with a valid value.

Bash

To find KMS keys in a particular Amazon CloudHSM key store, get all of your KMS keys in the account and Region. Then filter by the custom key store ID.

for key in $(aws kms list-keys --query 'Keys[*].KeyId' --output text) ; do aws kms describe-key --key-id $key | grep '"CustomKeyStoreId": "cks-1234567890abcdef0"' --context 100; done

To get KMS keys in any Amazon CloudHSM key store in the account and Region, search for CustomKeyStoreType with a value of AWS_CloudHSM.

for key in $(aws kms list-keys --query 'Keys[*].KeyId' --output text) ; do aws kms describe-key --key-id $key | grep '"CustomKeyStoreType": "AWS_CloudHSM"' --context 100; done
PowerShell

To find KMS keys in a particular Amazon CloudHSM key store, use the Get-KmsKeyList and Get-KmsKey cmdlets to get all of your KMS keys in the account and Region. Then filter by the custom key store ID.

PS C:\> Get-KMSKeyList | Get-KMSKey | where CustomKeyStoreId -eq 'cks-1234567890abcdef0'

To get KMS keys in any Amazon CloudHSM key store in the account and Region, filter for the CustomKeyStoreType value of AWS_CLOUDHSM.

PS C:\> Get-KMSKeyList | Get-KMSKey | where CustomKeyStoreType -eq 'AWS_CLOUDHSM'

Find all keys for an Amazon CloudHSM key store

You can identify the keys in your Amazon CloudHSM cluster that serve as key material for your Amazon CloudHSM key store. To do that, use the findAllKeys command in cloudhsm_mgmt_util to find the key handles of all keys that kmsuser owns or shares. Unless you have logged in as kmsuser and created keys outside of Amazon KMS, all of the keys that kmsuser owns represent key material for KMS keys.

Any crypto officer in the cluster can run this command without disconnecting the Amazon CloudHSM key store.

  1. Start cloudhsm_mgmt_util by using the procedure described in the Getting started with CloudHSM Management Utility (CMU) topic.

  2. Log into cloudhsm_mgmt_util using a crypto officer (CO) account.

  3. Use the listUsers command to find the user ID of the kmsuser crypto user.

    In this example, kmsuser has user ID 3.

    aws-cloudhsm> listUsers Users on server 0(10.0.0.1): Number of users found:3 User Id User Type User Name MofnPubKey LoginFailureCnt 2FA 1 PCO admin NO 0 NO 2 AU app_user NO 0 NO 3 CU kmsuser NO 0 NO
  4. Use the findAllKeys command to find the key handles of all keys that kmsuser owns or shares. Replace the example user ID (3) with the actual user ID of kmsuser in your cluster.

    The example output shows that kmsuser owns keys with key handles 8, 9, and 262162 on both HSMs in the cluster.

    aws-cloudhsm> findAllKeys 3 0 Keys on server 0(10.0.0.1): Number of keys found 3 number of keys matched from start index 0::6 8,9,262162 findAllKeys success on server 0(10.0.0.1) Keys on server 1(10.0.0.2): Number of keys found 6 number of keys matched from start index 0::6 8,9,262162 findAllKeys success on server 1(10.0.0.2)

Find the KMS key for an Amazon CloudHSM key

If you know the key handle of a key that kmsuser owns in the cluster, you can use the key label to identify the associated KMS key in your Amazon CloudHSM key store.

When Amazon KMS creates the key material for a KMS key in your Amazon CloudHSM cluster, it writes the Amazon Resource Name (ARN) of the KMS key in the key label. Unless you have changed the label value, you can use the getAttribute command in key_mgmt_util or cloudhsm_mgmt_util to associate the key with its KMS key.

To run this procedure, you need to disconnect the Amazon CloudHSM key store temporarily so you can log in as the kmsuser CU.

Note

While a custom key store is disconnected, all attempts to create KMS keys in the custom key store or to use existing KMS keys in cryptographic operations will fail. This action can prevent users from storing and accessing sensitive data.

  1. Disconnect the Amazon CloudHSM key store, if not already disconnected., then log into the key_mgmt_util as kmsuser, as explained in How to disconnect and log in.

  2. Use the getAttribute command in key_mgmt_util or cloudhsm_mgmt_util to get the label attribute (OBJ_ATTR_LABEL, attribute 3) for a particular key handle.

    For example, this command uses getAttribute in cloudhsm_mgmt_util to get the label attribute (attribute 3) of the key with key handle 262162. The output shows that key 262162 serves as key material for the KMS key with ARN arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab. Before running this command, replace the example key handle with a valid one.

    For a list of key attributes, use the listAttributes command or see the Key Attribute Reference in the Amazon CloudHSM User Guide.

    aws-cloudhsm> getAttribute 262162 3 Attribute Value on server 0(10.0.1.10): OBJ_ATTR_LABEL arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
  3. Log out of key_mgmt_util or cloudhsm_mgmt_util and reconnect the Amazon CloudHSM key store as explained in How to log out and reconnect.

Find the Amazon CloudHSM key for a KMS key

You can use the KMS key ID of a KMS key in an Amazon CloudHSM key store to identify the key in your Amazon CloudHSM cluster that serves as its key material. Then you can use its key handle to identify the key in Amazon CloudHSM client commands.

When Amazon KMS creates the key material for a KMS key in your Amazon CloudHSM cluster, it writes the Amazon Resource Name (ARN) of the KMS key in the key label. Unless you have changed the label value, you can use the findKey command in key_mgmt_util to get the key handle of the key material for the KMS key. To run this procedure, you need to disconnect the Amazon CloudHSM key store temporarily so you can log in as the kmsuser CU.

Note

While a custom key store is disconnected, all attempts to create KMS keys in the custom key store or to use existing KMS keys in cryptographic operations will fail. This action can prevent users from storing and accessing sensitive data.

  1. Disconnect the Amazon CloudHSM key store, if it is not already disconnected, then log into the key_mgmt_util as kmsuser, as explained in How to disconnect and log in.

  2. Use the findKey command in key_mgmt_util to search for a key with a label that matches the ARN of a KMS key in your Amazon CloudHSM key store. Replace the example KMS key ARN in the value of the -l (lower-case L for 'label') parameter with a valid KMS key ARN.

    For example, this command finds the key with a label that matches the example KMS key ARN, arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab. The example output shows that the key with key handle 262162 has the specified KMS key ARN in its label. You can now use this key handle in other key_mgmt_util commands.

    Command: findKey -l arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab Total number of keys present 1 number of keys matched from start index 0::1 262162 Cluster Error Status Node id 1 and err state 0x00000000 : HSM Return: SUCCESS Node id 0 and err state 0x00000000 : HSM Return: SUCCESS Cfm3FindKey returned: 0x00 : HSM Return: SUCCESS
  3. Log out of key_mgmt_util and reconnect the custom key store as explained in How to log out and reconnect.