# Find KMS keys and key material in an AWS CloudHSM key store
If you manage an AWS CloudHSM key store, you might need to identify the KMS keys in each AWS CloudHSM key store. For example, you might need to do some of the following tasks.
+ Track the KMS keys in AWS CloudHSM key store in AWS CloudTrail logs.
+ Predict the effect on KMS keys of disconnecting an AWS CloudHSM key store.
+ Schedule deletion of KMS keys before you delete an AWS CloudHSM key store.
In addition, you might want to identify the keys in your AWS CloudHSM cluster that serve as key material for your KMS keys. Although AWS KMS manages the KMS keys and the key material, you still retain control of and responsibility for the management of your AWS 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 AWS CloudHSM key store is owned by the [`kmsuser` crypto user](keystore-cloudhsm.md#concept-kmsuser) (CU). AWS KMS sets the key label attribute, which is viewable only in AWS 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 AWS CloudHSM key store](find-cmk-in-keystore.md) — How to identify the KMS keys in one or all of your AWS CloudHSM key stores.
+ [Find all keys for an AWS CloudHSM key store](find-all-kmsuser-keys.md) — How to find all keys in your cluster that serve as key material for the KMS keys in your AWS CloudHSM key store.
+ [Find the AWS CloudHSM key for a KMS key](find-handle-for-cmk-id.md) — How to find the key in your cluster that serves as key material for a particular KMS key in your AWS CloudHSM key store.
+ [Find the KMS key for an AWS CloudHSM key](find-label-for-key-handle.md) — How to find the KMS key for a particular key in your cluster.
# Find the KMS keys in an AWS CloudHSM key store
If you manage an AWS CloudHSM key store, you might need to identify the KMS keys in each AWS CloudHSM key store. You can use this information to track the KMS key operations in AWS CloudTrail logs, predict the effect of disconnecting a custom key store on KMS keys, or schedule deletion of KMS keys before you delete an AWS CloudHSM key store.
## To find the KMS keys in an AWS CloudHSM key store (console)
To find the KMS keys in a particular AWS 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 AWS CloudHSM key store, look for KMS keys with an **Origin** value of **AWS 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 AWS CloudHSM key store (API)
To find the KMS keys in an AWS CloudHSM key store, use the [ListKeys](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListKeys.html) and [DescribeKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html) operations and then filter by `CustomKeyStoreId` value. Before running the following examples, replace the fictitious custom key store ID values with a valid value.
------
#### [ Bash ]
To find KMS keys in a particular AWS 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 AWS 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 AWS CloudHSM key store, use the [Get-KmsKeyList](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-KMSKeyList.html) and [Get-KmsKey](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-KMSKey.html) 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 AWS 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 AWS CloudHSM key store
You can identify the keys in your AWS CloudHSM cluster that serve as key material for your AWS CloudHSM key store. To do that, use the [key list](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-key-list.html) command in CloudHSM CLI.
You can also use the **key list** command to find the AWS KMS for an AWS CloudHSM key. When AWS KMS creates the key material for a KMS key in your AWS CloudHSM cluster, it writes the Amazon Resource Name (ARN) of the KMS key in the key label. The **key list** command returns the `key-reference` and the `label`.
**Notes**
The following procedures use the AWS CloudHSM Client SDK 5 command line tool, [CloudHSM CLI](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli.html). The CloudHSM CLI replaces `key-handle` with `key-reference`.
On January 1, 2025, AWS CloudHSM will end support for the Client SDK 3 command line tools, the CloudHSM Management Utility (CMU) and the Key Management Utility (KMU). For more information on the differences between the Client SDK 3 command line tools and the Client SDK 5 command line tool, see [Migrate from Client SDK 3 CMU and KMU to Client SDK 5 CloudHSM CLI](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-migrate-from-kmu-cmu.html) in the *AWS CloudHSM User Guide*.
To run this procedure you need to disconnect the AWS CloudHSM key store temporarily so you can log in as the `kmsuser` CU.
1. Disconnect the AWS CloudHSM key store, if it is not already disconnected, then log in as `kmsuser`, as explained in [How to disconnect and log in](fix-keystore.md#login-kmsuser-1).
**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. Use the [https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-key-list.html](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-key-list.html) command in CloudHSM CLI to find all keys for the current user present in your AWS CloudHSM cluster.
By default, only 10 keys of the currently logged in user are displayed, and only the `key-reference` and `label` are displayed as output. For more options, see [key list](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-key-list.html#chsm-cli-key-list-syntax) in the *AWS CloudHSM User Guide*.
```
aws-cloudhsm > key list
{
"error_code": 0,
"data": {
"matched_keys": [
{
"key-reference": "0x0000000000000123",
"attributes": {
"label": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
}
},
{
"key-reference": "0x0000000000000456",
"attributes": {
"label": "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321"
}
},.
...8 keys later...
],
"total_key_count": 56,
"returned_key_count": 10,
"next_token": "10"
}
}
```
1. Log out and reconnect the AWS CloudHSM key store as described in [How to log out and reconnect](fix-keystore.md#login-kmsuser-2).
# Find the KMS key for an AWS CloudHSM key
If you know the key reference or ID of a key that the `kmsuser` owns in the cluster, you can use that value to identify the associated KMS key in your AWS CloudHSM key store.
When AWS KMS creates the key material for a KMS key in your AWS 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 [key list](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-key-list.html) command in CloudHSM CLI to identify the KMS key associated with the AWS CloudHSM key.
**Notes**
The following procedures use the AWS CloudHSM Client SDK 5 command line tool, [CloudHSM CLI](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli.html). The CloudHSM CLI replaces `key-handle` with `key-reference`.
On January 1, 2025, AWS CloudHSM will end support for the Client SDK 3 command line tools, the CloudHSM Management Utility (CMU) and the Key Management Utility (KMU). For more information on the differences between the Client SDK 3 command line tools and the Client SDK 5 command line tool, see [Migrate from Client SDK 3 CMU and KMU to Client SDK 5 CloudHSM CLI](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-migrate-from-kmu-cmu.html) in the *AWS CloudHSM User Guide*.
To run these procedures you need to disconnect the AWS 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.
**Topics**
+ [Identify the KMS key associated with a key reference](#key-reference-filter)
+ [Identify the KMS key associated with a backing key ID](#backing-key-id-filter)
## Identify the KMS key associated with a key reference
The following procedures demonstrate how to use the [https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-key-list.html](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-key-list.html) command in CloudHSM CLI with the `key-reference` attribute filter to find the key in your cluster that serves as key material for a particular KMS key in your AWS CloudHSM key store.
1. Disconnect the AWS CloudHSM key store, if it is not already disconnected, then log in as `kmsuser`, as explained in [How to disconnect and log in](fix-keystore.md#login-kmsuser-1).
1. Use the [https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-key-list.html](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-key-list.html) command in CloudHSM CLI to filter by the `key-reference` attribute. Specify the `verbose` argument to include all attributes and key information for the matched key. If you don't specify the `verbose` argument, the **key list** operation only returns the matched key's key-reference and label attribute.
Before running this command, replace the example `key-reference` with a valid one from your account.
```
aws-cloudhsm > key list --filter attr.key-reference="0x0000000000120034" --verbose
{
"error_code": 0,
"data": {
"matched_keys": [
{
"key-reference": "0x0000000000120034",
"key-info": {
"key-owners": [
{
"username": "kmsuser",
"key-coverage": "full"
}
],
"shared-users": [],
"cluster-coverage": "full"
},
"attributes": {
"key-type": "aes",
"label": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"id": "0xbacking-key-id",
"check-value": "0x29bbd1",
"class": "my_test_key",
"encrypt": true,
"decrypt": true,
"token": true,
"always-sensitive": true,
"derive": false,
"destroyable": true,
"extractable": false,
"local": true,
"modifiable": true,
"never-extractable": false,
"private": true,
"sensitive": true,
"sign": false,
"trusted": false,
"unwrap": true,
"verify": false,
"wrap": true,
"wrap-with-trusted": false,
"key-length-bytes": 32
}
}
],
"total_key_count": 1,
"returned_key_count": 1
}
}
```
1. Log out and reconnect the AWS CloudHSM key store as described in [How to log out and reconnect](fix-keystore.md#login-kmsuser-2).
## Identify the KMS key associated with a backing key ID
All CloudTrail log entries for cryptographic operations with a KMS key in an AWS CloudHSM key store include an `additionalEventData` field with the `customKeyStoreId` and `backingKeyId`. The value returned in the `backingKeyId` field correlates to the CloudHSM key `id` attribute. You can filter the [https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-key-list.html](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-key-list.html) operation by the `id` attribute to identify the KMS key associated with a specific `backingKeyId`.
1. Disconnect the AWS CloudHSM key store, if it is not already disconnected, then log in as `kmsuser`, as explained in [How to disconnect and log in](fix-keystore.md#login-kmsuser-1).
1. Use the [https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-key-list.html](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-key-list.html) command in CloudHSM CLI with the attribute filter to find the key in your cluster that serves as key material for a particular KMS key in your AWS CloudHSM key store.
The following example demonstrates how to filter by the `id` attribute. AWS CloudHSM recognizes the `id` value as a hexadecimal value. To filter the **key list** operation by the `id` attribute, you must first convert the `backingKeyId` value that you identified in your CloudTrail log entry into a format that AWS CloudHSM recognizes.
1. Use the following Linux command to convert the `backingKeyId` into a hexadecimal representation.
```
echo backingKeyId | tr -d '\n' | xxd -p
```
The following example demonstrates how to convert the `backingKeyId` byte array into a hexadecimal representation.
```
echo 5890723622dc15f699aa9ab2387a9f744b2b884c18b2186ee8ada4f556a2eb9d | tr -d '\n' | xxd -p
35383930373233363232646331356636393961613961623233383761396637343462326238383463313862323138366565386164613466353536613265623964
```
1. Prepend the hexadecimal representation of the `backingKeyId` with `0x`.
```
0x35383930373233363232646331356636393961613961623233383761396637343462326238383463313862323138366565386164613466353536613265623964
```
1. Use the converted `backingKeyId` value to filter by the `id` attribute. Specify the `verbose` argument to include all attributes and key information for the matched key. If you don't specify the `verbose` argument, the **key list** operation only returns the matched key's key-reference and label attribute.
```
aws-cloudhsm > key list --filter attr.id="0x35383930373233363232646331356636393961613961623233383761396637343462326238383463313862323138366565386164613466353536613265623964" --verbose
{
"error_code": 0,
"data": {
"matched_keys": [
{
"key-reference": "0x0000000000120034",
"key-info": {
"key-owners": [
{
"username": "kmsuser",
"key-coverage": "full"
}
],
"shared-users": [],
"cluster-coverage": "full"
},
"attributes": {
"key-type": "aes",
"label": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"id": "0x35383930373233363232646331356636393961613961623233383761396637343462326238383463313862323138366565386164613466353536613265623964",
"check-value": "0x29bbd1",
"class": "my_test_key",
"encrypt": true,
"decrypt": true,
"token": true,
"always-sensitive": true,
"derive": false,
"destroyable": true,
"extractable": false,
"local": true,
"modifiable": true,
"never-extractable": false,
"private": true,
"sensitive": true,
"sign": false,
"trusted": false,
"unwrap": true,
"verify": false,
"wrap": true,
"wrap-with-trusted": false,
"key-length-bytes": 32
}
}
],
"total_key_count": 1,
"returned_key_count": 1
}
}
```
1. Log out and reconnect the AWS CloudHSM key store as described in [How to log out and reconnect](fix-keystore.md#login-kmsuser-2).
# Find the AWS CloudHSM key for a KMS key
You can use the KMS key ID of a KMS key in an AWS CloudHSM key store to identify the key in your AWS CloudHSM cluster that serves as its key material.
When AWS KMS creates the key material for a KMS key in your AWS 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 [https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-key-list.html](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-key-list.html) command in CloudHSM CLI to find the key-resource and id of the key material for the KMS key.
All CloudTrail log entries for cryptographic operation with a KMS key in an AWS CloudHSM key store include an `additionalEventData` field with the `customKeyStoreId` and `backingKeyId`. The value returned in the `backingKeyId` field is the `id` AWS CloudHSM key attribute. You can filter the **key list** AWS CloudHSM CLI operation by KMS key ARN to identify the CloudHSM key `id` attribute associated with a specific KMS key.
To run this procedure, you need to disconnect the AWS CloudHSM key store temporarily so you can log in as the `kmsuser` CU.
**Notes**
The following procedures use the AWS CloudHSM Client SDK 5 command line tool, [CloudHSM CLI](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli.html). The CloudHSM CLI replaces `key-handle` with `key-reference`.
On January 1, 2025, AWS CloudHSM will end support for the Client SDK 3 command line tools, the CloudHSM Management Utility (CMU) and the Key Management Utility (KMU). For more information on the differences between the Client SDK 3 command line tools and the Client SDK 5 command line tool, see [Migrate from Client SDK 3 CMU and KMU to Client SDK 5 CloudHSM CLI](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-migrate-from-kmu-cmu.html) in the *AWS CloudHSM User Guide*.
1. Disconnect the AWS CloudHSM key store, if it is not already disconnected, then log in as `kmsuser`, as explained in [How to disconnect and log in](fix-keystore.md#login-kmsuser-1).
**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. Use the [https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-key-list.html](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-key-list.html) command in CloudHSM CLI and filter by `label` to find the KMS key for a particular key in your AWS CloudHSM cluster. Specify the `verbose` argument to include all attributes and key information for the matched key. If you don't specify the `verbose` argument, the **key list** operation only returns the matched key's key-reference and label attributes.
The following example demonstrates how to filter by the `label` attribute that stores the KMS key ARN. Before running this command, replace the example KMS key ARN with a valid one from your account.
```
aws-cloudhsm > key list --filter attr.label="arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" --verbose
{
"error_code": 0,
"data": {
"matched_keys": [
{
"key-reference": "0x0000000000120034",
"key-info": {
"key-owners": [
{
"username": "kmsuser",
"key-coverage": "full"
}
],
"shared-users": [],
"cluster-coverage": "full"
},
"attributes": {
"key-type": "aes",
"label": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"id": "0xbacking-key-id",
"check-value": "0x29bbd1",
"class": "my_test_key",
"encrypt": true,
"decrypt": true,
"token": true,
"always-sensitive": true,
"derive": false,
"destroyable": true,
"extractable": false,
"local": true,
"modifiable": true,
"never-extractable": false,
"private": true,
"sensitive": true,
"sign": false,
"trusted": false,
"unwrap": true,
"verify": false,
"wrap": true,
"wrap-with-trusted": false,
"key-length-bytes": 32
}
}
],
"total_key_count": 1,
"returned_key_count": 1
}
}
```
1. Log out and reconnect the AWS CloudHSM key store as described in [How to log out and reconnect](fix-keystore.md#login-kmsuser-2).