# AWS CloudHSM key stores
An AWS CloudHSM key store is a [custom key store](key-store-overview.md#custom-key-store-overview) backed by a [AWS CloudHSM cluster](https://docs.aws.amazon.com/cloudhsm/latest/userguide/). When you create an AWS KMS key in a custom key store, AWS KMS generates and stores non-extractable key material for the KMS key in an AWS CloudHSM cluster that you own and manage. When you use a KMS key in a custom key store, the [cryptographic operations](manage-cmk-keystore.md#use-cmk-keystore) are performed in the HSMs in the cluster. This feature combines the convenience and widespread integration of AWS KMS with the added control of an AWS CloudHSM cluster in your AWS account.
AWS KMS provides full console and API support for creating, using, and managing your custom key stores. You can use the KMS keys in your custom key store the same way that you use any KMS key. For example, you can use the KMS keys to generate data keys and encrypt data. You can also use the KMS keys in your custom key store with AWS services that support customer managed keys.
**Do I need a custom key store?**
For most users, the default AWS KMS key store, which is protected by [FIPS 140-3 validated cryptographic modules](https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/4884), fulfills their security requirements. There is no need to add an extra layer of maintenance responsibility or a dependency on an additional service.
However, you might consider creating a custom key store if your organization has any of the following requirements:
+ You have keys that are explicitly required to be protected in a single tenant HSM or in an HSM that you have direct control over.
+ You need the ability to immediately remove key material from AWS KMS.
+ You need to be able to audit all use of your keys independently of AWS KMS or AWS CloudTrail.
**How do custom key stores work?**
Each custom key store is associated with an AWS CloudHSM cluster in your AWS account. When you connect the custom key store to its cluster, AWS KMS creates the network infrastructure to support the connection. Then it logs into the key AWS CloudHSM client in the cluster using the credentials of a [dedicated crypto user](#concept-kmsuser) in the cluster.
You create and manage your custom key stores in AWS KMS and create and manage your HSM clusters in AWS CloudHSM. When you create AWS KMS keys in an AWS KMS custom key store, you view and manage the KMS keys in AWS KMS. But you can also view and manage their key material in AWS CloudHSM, just as you would do for other keys in the cluster.
![\[Managing KMS keys in a custom key store\]](http://docs.aws.amazon.com/kms/latest/developerguide/images/kms-hsm-view.png)
You can [create symmetric encryption KMS keys](create-cmk-keystore.md) with key material generated by AWS KMS in your custom key store. Then use the same techniques to view and manage the KMS keys in your custom key store that you use for KMS keys in the AWS KMS key store. You can control access with IAM and key policies, create tags and aliases, enable and disable the KMS keys, and schedule key deletion. You can use the KMS keys for [cryptographic operations](manage-cmk-keystore.md#use-cmk-keystore) and use them with AWS services that integrate with AWS KMS.
In addition, you have full control over the AWS CloudHSM cluster, including creating and deleting HSMs and managing backups. You can use the AWS CloudHSM client and supported software libraries to view, audit, and manage the key material for your KMS keys. While the custom key store is disconnected, AWS KMS cannot access it, and users cannot use the KMS keys in the custom key store for cryptographic operations. This added layer of control makes custom key stores a powerful solution for organizations that require it.
**Where do I start?**
To create and manage an AWS CloudHSM key store, you use features of AWS KMS and AWS CloudHSM.
1. Start in AWS CloudHSM. [Create an active AWS CloudHSM cluster](https://docs.aws.amazon.com/cloudhsm/latest/userguide/getting-started.html) or select an existing cluster. The cluster must have at least two active HSMs in different Availability Zones. Then create a [dedicated crypto user (CU) account](#concept-kmsuser) in that cluster for AWS KMS.
1. In AWS KMS, [create a custom key store](create-keystore.md) that is associated with your selected AWS CloudHSM cluster. AWS KMS provides a complete management interface that lets you create, view, edit, and delete your custom key stores.
1. When you're ready to use your custom key store, [connect it to its associated AWS CloudHSM cluster](connect-keystore.md). AWS KMS creates the network infrastructure that it needs to support the connection. It then logs in to the cluster using the dedicated crypto user account credentials so it can generate and manage key material in the cluster.
1. Now, you can [create symmetric encryption KMS keys in your custom key store](create-cmk-keystore.md). Just specify the custom key store when you create the KMS key.
If you get stuck at any point, you can find help in the [Troubleshooting a custom key store](fix-keystore.md) topic. If your question is not answered, use the feedback link at the bottom of each page of this guide or post a question on the [AWS Key Management Service Discussion Forum](https://repost.aws/tags/TAMC3vcPOPTF-rPAHZVRj1PQ/aws-key-management-service).
**Quotas**
AWS KMS allows up to [10 custom key stores](resource-limits.md) in each AWS account and Region, including both [AWS CloudHSM key stores](https://docs.aws.amazon.com/kms/latest/developerguide/keystore-cloudhsm.html) and [external key stores](https://docs.aws.amazon.com/kms/latest/developerguide/keystore-external.html), regardless of their connection state. In addition, there are AWS KMS request quotas on the [use of KMS keys in an AWS CloudHSM key store](requests-per-second.md#rps-key-stores).
**Pricing**
For information on the cost of AWS KMS custom key stores and customer managed keys in a custom key store, see [AWS Key Management Service pricing](https://aws.amazon.com/kms/pricing/). For information about the cost of AWS CloudHSM clusters and HSMs, see [AWS CloudHSM Pricing](https://aws.amazon.com/cloudhsm/pricing/).
**Regions**
AWS KMS supports AWS CloudHSM key stores in all AWS Regions where AWS KMS is supported, except for Asia Pacific (Melbourne), China (Beijing), China (Ningxia), and Europe (Spain).
**Unsupported features**
AWS KMS does not support the following features in custom key stores.
+ [Asymmetric KMS keys](symmetric-asymmetric.md)
+ [HMAC KMS keys](hmac.md)
+ [KMS keys with imported key material](importing-keys.md)
+ [Automatic key rotation](rotate-keys.md)
+ [Multi-Region keys](multi-region-keys-overview.md)
## AWS CloudHSM key store concepts
This topic explains some of the terms and concepts used in AWS CloudHSM key stores.
### AWS CloudHSM key store
An *AWS CloudHSM key store* is a [custom key store](key-store-overview.md#custom-key-store-overview) associated with an AWS CloudHSM cluster that you own and manage. AWS CloudHSM clusters are backed by hardware security modules (HSMs) certified at [FIPS 140-2 or FIPS 140-3Level 3](https://docs.aws.amazon.com/cloudhsm/latest/userguide/compliance.html).
When you create a KMS key in your AWS CloudHSM key store, AWS KMS generates a 256-bit, persistent, non-exportable Advanced Encryption Standard (AES) symmetric key in the associated AWS CloudHSM cluster. This key material never leaves your HSMs unencrypted. When you use a KMS key in an AWS CloudHSM key store, the cryptographic operations are performed in the HSMs in the cluster.
AWS CloudHSM key stores combine the convenient and comprehensive key management interface of AWS KMS with the additional controls provided by an AWS CloudHSM cluster in your AWS account. This integrated feature lets you create, manage, and use KMS keys in AWS KMS while maintaining full control of the HSMs that store their key material, including managing clusters, HSMs, and backups. You can use the AWS KMS console and APIs to manage the AWS CloudHSM key store and its KMS keys. You can also use the AWS CloudHSM console, APIs, client software, and associated software libraries to manage the associated cluster.
You can [view and manage](view-keystore.md) your AWS CloudHSM key store, [edit its properties](update-keystore.md), and [connect](connect-keystore.md) and [disconnect](disconnect-keystore.md) it from its associated AWS CloudHSM cluster. If you need to [delete an AWS CloudHSM key store](delete-keystore.md#delete-keystore-console), you must first delete the KMS keys in the AWS CloudHSM key store by scheduling their deletion and waiting until the grace period expires. Deleting the AWS CloudHSM key store removes the resource from AWS KMS, but it does not affect your AWS CloudHSM cluster.
### AWS CloudHSM cluster
Every AWS CloudHSM key store is associated with one *AWS CloudHSM cluster*. When you create an AWS KMS key in your AWS CloudHSM key store, AWS KMS creates its key material in the associated cluster. When you use a KMS key in your AWS CloudHSM key store, the cryptographic operation is performed in the associated cluster.
Each AWS CloudHSM cluster can be associated with only one AWS CloudHSM key store. The cluster that you choose cannot be associated with another AWS CloudHSM key store or share a backup history with a cluster that is associated with another AWS CloudHSM key store. The cluster must be initialized and active, and it must be in the same AWS account and Region as the AWS CloudHSM key store. You can create a new cluster or use an existing one. AWS KMS does not need exclusive use of the cluster. To create KMS keys in the AWS CloudHSM key store, its associated cluster it must contain at least two active HSMs. All other operations require only one HSM.
You specify the AWS CloudHSM cluster when you create the AWS CloudHSM key store, and you cannot change it. However, you can substitute any cluster that shares a backup history with the original cluster. This lets you delete the cluster, if necessary, and replace it with a cluster created from one of its backups. You retain full control of the associated AWS CloudHSM cluster so you can manage users and keys, create and delete HSMs, and use and manage backups.
When you are ready to use your AWS CloudHSM key store, you connect it to its associated AWS CloudHSM cluster. You can connect and disconnect your custom key store at any time. When a custom key store is connected, you can create and use its KMS keys. When it is disconnected, you can view and manage the AWS CloudHSM key store and its KMS keys. But you cannot create new KMS keys or use the KMS keys in the AWS CloudHSM key store for cryptographic operations.
### `kmsuser` Crypto user
To create and manage key material in the associated AWS CloudHSM cluster on your behalf, AWS KMS uses a dedicated *AWS CloudHSM [crypto user](https://docs.aws.amazon.com/cloudhsm/latest/userguide/hsm-users.html#crypto-user) (CU)* in the cluster named `kmsuser`. The `kmsuser` CU is a standard CU account that is automatically synchronized to all HSMs in the cluster and is saved in cluster backups.
Before you create your AWS CloudHSM key store, you [create a `kmsuser` CU account](create-keystore.md#before-keystore) in your AWS CloudHSM cluster using the [https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-user-cloudhsm-cli.html](https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-user-cloudhsm-cli.html) command in CloudHSM CLI. Then when you [create the AWS CloudHSM key store](create-keystore.md), you provide the `kmsuser` account password to AWS KMS. When you [connect the custom key store](connect-keystore.md), AWS KMS logs into the cluster as the `kmsuser` CU and rotates its password. AWS KMS encrypts your `kmsuser` password before it stores it securely. When the password is rotated, the new password is encrypted and stored in the same way.
AWS KMS remains logged in as `kmsuser` as long as the AWS CloudHSM key store is connected. You should not use this CU account for other purposes. However, you retain ultimate control of the `kmsuser` CU account. At any time, you can [find the keys](find-key-material.md) that `kmsuser` owns. If necessary, you can [disconnect the custom key store](disconnect-keystore.md), change the `kmsuser` password, [log into the cluster as `kmsuser`](fix-keystore.md#fix-login-as-kmsuser), and view and manage the keys that `kmsuser` owns.
For instructions on creating your `kmsuser` CU account, see [Create the `kmsuser` Crypto User](create-keystore.md#before-keystore).
### KMS keys in an AWS CloudHSM key store
You can use the AWS KMS or AWS KMS API to create a AWS KMS keys in an AWS CloudHSM key store. You use the same technique that you would use on any KMS key. The only difference is that you must identify the AWS CloudHSM key store and specify that the origin of the key material is the AWS CloudHSM cluster.
When you [create a KMS key in an AWS CloudHSM key store](create-cmk-keystore.md), AWS KMS creates the KMS key in AWS KMS and it generates a 256-bit, persistent, non-exportable Advanced Encryption Standard (AES) symmetric key material in its associated cluster. When you use the AWS KMS key in a cryptographic operation, the operation is performed in the AWS CloudHSM cluster using the cluster-based AES key. Although AWS CloudHSM supports symmetric and asymmetric keys of different types, AWS CloudHSM key stores support only AES symmetric encryption keys.
You can view the KMS keys in an AWS CloudHSM key store in the AWS KMS console, and use the console options to display the custom key store ID. You can also use the [DescribeKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html) operation to find the AWS CloudHSM key store ID and AWS CloudHSM cluster ID.
The KMS keys in an AWS CloudHSM key store work just like any KMS keys in AWS KMS. Authorized users need the same permissions to use and manage the KMS keys. You use the same console procedures and API operations to view and manage the KMS keys in an AWS CloudHSM key store. These include enabling and disabling KMS keys, creating and using tags and aliases, and setting and changing IAM and key policies. You can use the KMS keys in an AWS CloudHSM key store for cryptographic operations, and use them with [integrated AWS services](service-integration.md) that support the use of customer managed keys However, you cannot enable [automatic key rotation](rotate-keys.md) or [import key material](importing-keys.md) into a KMS key in an AWS CloudHSM key store.
You also use the same process to [schedule deletion](deleting-keys.md#delete-cmk-keystore) of a KMS key in an AWS CloudHSM key store. After the waiting period expires, AWS KMS deletes the KMS key from KMS. Then it makes a best effort to delete the key material for the KMS key from the associated AWS CloudHSM cluster. However, you might need to manually [delete the orphaned key material](fix-keystore.md#fix-keystore-orphaned-key) from the cluster and its backups.
# Control access to your AWS CloudHSM key store
You use IAM policies to control access to your AWS CloudHSM key store and your AWS CloudHSM cluster. You can use key policies, IAM policies, and grants to control access to the AWS KMS keys in your AWS CloudHSM key store. We recommend that you provide users, groups, and roles only the permissions that they require for the tasks that they are likely to perform.
To support your AWS CloudHSM key stores, AWS KMS needs permission to get information about your AWS CloudHSM clusters. It also needs permission to create the network infrastructure that connects your AWS CloudHSM key store to its AWS CloudHSM cluster. To get these permissions, AWS KMS creates the **AWSServiceRoleForKeyManagementServiceCustomKeyStores** service-linked role in your AWS account. For more information, see [Authorizing AWS KMS to manage AWS CloudHSM and Amazon EC2 resources](authorize-kms.md).
When designing your AWS CloudHSM key store, be sure that the principals who use and manage it have only the permissions that they require. The following list describes the minimum permissions required for AWS CloudHSM key store managers and users.
+ Principals who create and manage your AWS CloudHSM key store require the following permission to use the AWS CloudHSM key store API operations.
+ `cloudhsm:DescribeClusters`
+ `kms:CreateCustomKeyStore`
+ `kms:ConnectCustomKeyStore`
+ `kms:DeleteCustomKeyStore`
+ `kms:DescribeCustomKeyStores`
+ `kms:DisconnectCustomKeyStore`
+ `kms:UpdateCustomKeyStore`
+ `iam:CreateServiceLinkedRole`
+ Principals who create and manage the AWS CloudHSM cluster that is associated with your AWS CloudHSM key store need permission to create and initialize an AWS CloudHSM cluster. This includes permission to create or use an Amazon Virtual Private Cloud (VPC), create subnets, and create an Amazon EC2 instance. They might also need to create and delete HSMs, and manage backups. For lists of the required permissions, see [Identity and access management for AWS CloudHSM](https://docs.aws.amazon.com/cloudhsm/latest/userguide/identity-access-management.html) in the *AWS CloudHSM User Guide*.
+ Principals who create and manage AWS KMS keys in your AWS CloudHSM key store require [the same permissions](create-keys.md#create-key-permissions) as those who create and manage any KMS key in AWS KMS. The [default key policy](key-policy-default.md) for a KMS key in an AWS CloudHSM key store is identical to the default key policy for KMS keys in AWS KMS. [Attribute-based access control](abac.md) (ABAC), which uses tags and aliases to control access to KMS keys, is also effective on KMS keys in AWS CloudHSM key stores.
+ Principals who use the KMS keys in your AWS CloudHSM key store for [cryptographic operations](manage-cmk-keystore.md#use-cmk-keystore) need permission to perform the cryptographic operation with the KMS key, such as [kms:Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html). You can provide these permissions in a key policy, IAM policy. But, they do not need any additional permissions to use a KMS key in an AWS CloudHSM key store.
# Create an AWS CloudHSM key store
You can create one or several AWS CloudHSM key stores in your account. Each AWS CloudHSM key store is associated with one AWS CloudHSM cluster in the same AWS account and Region. Before you create your AWS CloudHSM key store, you need to [assemble the prerequisites](#before-keystore). Then, before you can use your AWS CloudHSM key store, you must [connect it](connect-keystore.md) to its AWS CloudHSM cluster.
**Notes**
KMS cannot communicate over IPv6 with AWS CloudHSM key stores.
If you try to create an AWS CloudHSM key store with all of the same property values as an existing *disconnected* AWS CloudHSM key store, AWS KMS does not create a new AWS CloudHSM key store, and it does not throw an exception or display an error. Instead, AWS KMS recognizes the duplicate as the likely consequence of a retry, and it returns the ID of the existing AWS CloudHSM key store.
You do not have to connect your AWS CloudHSM key store immediately. You can leave it in a disconnected state until you are ready to use it. However, to verify that it is configured properly, you might want to [connect it](connect-keystore.md),[ view its connection state](view-keystore.md), and then [disconnect it](disconnect-keystore.md).
**Topics**
+ [Assemble the prerequisites](#before-keystore)
+ [Create a new AWS CloudHSM key store](#create-hsm-keystore)
## Assemble the prerequisites
Each AWS CloudHSM key store is backed by an AWS CloudHSM cluster. To create an AWS CloudHSM key store, you must specify an active AWS CloudHSM cluster that is not already associated with another key store. You also need to create a dedicated crypto user (CU) in the cluster's HSMs that AWS KMS can use to create and manage keys on your behalf.
Before you create an AWS CloudHSM key store, do the following:
**Select an AWS CloudHSM cluster**
Every AWS CloudHSM key store is [associated with exactly one AWS CloudHSM cluster](keystore-cloudhsm.md#concept-cluster). When you create AWS KMS keys in your AWS CloudHSM key store, AWS KMS creates the KMS key metadata, such as an ID and Amazon Resource Name (ARN) in AWS KMS. It then creates the key material in the HSMs of the associated cluster. You can [create a new AWS CloudHSM](https://docs.aws.amazon.com/cloudhsm/latest/userguide/getting-started.html) cluster or use an existing one. AWS KMS does not require exclusive access to the cluster.
The AWS CloudHSM cluster that you select is permanently associated with the AWS CloudHSM key store. After you create the AWS CloudHSM key store, you can [change the cluster ID](update-keystore.md) of the associated cluster, but the cluster that you specify must share a backup history with the original cluster. To use an unrelated cluster, you need to create a new AWS CloudHSM key store.
The AWS CloudHSM cluster that you select must have the following characteristics:
+ **The cluster must be active**.
You must create the cluster, initialize it, install the AWS CloudHSM client software for your platform, and then activate the cluster. For detailed instructions, see [Getting started with AWS CloudHSM](https://docs.aws.amazon.com/cloudhsm/latest/userguide/getting-started.html) in the *AWS CloudHSM User Guide*.
+ **Mutual TLS (mTLS) is not enabled.**
KMS does not support mTLS for clusters. This setting must not be enabled.
+ **The cluster must be in the same account and Region** as the AWS CloudHSM key store. You cannot associate an AWS CloudHSM key store in one Region with a cluster in a different Region. To create a key infrastructure in multiple Regions, you must create AWS CloudHSM key stores and clusters in each Region.
+ **The cluster cannot be associated with another custom key store** in the same account and Region. Each AWS CloudHSM key store in the account and Region must be associated with a different AWS CloudHSM cluster. You cannot specify a cluster that is already associated with a custom key store or a cluster that shares a backup history with an associated cluster. Clusters that share a backup history have the same cluster certificate. To view the cluster certificate of a cluster, use the AWS CloudHSM console or the [DescribeClusters](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DescribeClusters.html) operation.
If you [back up an AWS CloudHSM cluster to a different Region](https://docs.aws.amazon.com/cloudhsm/latest/userguide/copy-backup-to-region.html), it is considered to be different cluster, and you can associate the backup with a custom key store in its Region. However, KMS keys in the two custom key stores are not interoperable, even if they have the same backing key. AWS KMS binds metadata to the ciphertext so it can be decrypted only by the KMS key that encrypted it.
+ The cluster must be configured with [private subnets](https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-subnets.html) in **at least two Availability Zones** in the Region. Because AWS CloudHSM is not supported in all Availability Zones, we recommend that you create private subnets in all Availability Zones in the region. You cannot reconfigure the subnets for an existing cluster, but you can [create a cluster from a backup](https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-cluster-from-backup.html) with different subnets in the cluster configuration.
**Important**
After you create your AWS CloudHSM key store, do not delete any of the private subnets configured for its AWS CloudHSM cluster. If AWS KMS cannot find all of the subnets in the cluster configuration, attempts to [connect to the custom key store](connect-keystore.md) fail with a `SUBNET_NOT_FOUND` connection error state. For details, see [How to fix a connection failure](fix-keystore.md#fix-keystore-failed).
+ The [security group for the cluster](https://docs.aws.amazon.com/cloudhsm/latest/userguide/configure-sg.html) (`cloudhsm-cluster--sg`) must include inbound rules and outbound rules that allow TCP traffic over IPv4, on ports 2223-2225. The **Source** in the inbound rules and the **Destination** in the outbound rules must match the security group ID. These rules are set by default when you create the cluster. Do not delete or change them.
+ **The cluster must contain at least two active HSMs** in different Availability Zones. To verify the number of HSMs, use the AWS CloudHSM console or the [DescribeClusters](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DescribeClusters.html) operation. If necessary, you can [add an HSM](https://docs.aws.amazon.com/cloudhsm/latest/userguide/add-remove-hsm.html#add-hsm).
**Find the trust anchor certificate**
When you create a custom key store, you must upload the trust anchor certificate for the AWS CloudHSM cluster to AWS KMS. AWS KMS needs the trust anchor certificate to connect the AWS CloudHSM key store to its associated AWS CloudHSM cluster.
Every active AWS CloudHSM cluster has a *trust anchor certificate*. When you [initialize the cluster](https://docs.aws.amazon.com/cloudhsm/latest/userguide/initialize-cluster.html#sign-csr), you generate this certificate, save it in the `customerCA.crt` file, and copy it to hosts that connect to the cluster.
**Create the `kmsuser` crypto user for AWS KMS**
To administer your AWS CloudHSM key store, AWS KMS logs into the [`kmsuser` crypto user](keystore-cloudhsm.md#concept-kmsuser) (CU) account in the selected cluster. Before you create your AWS CloudHSM key store, you must create the `kmsuser` CU. Then when you create your AWS CloudHSM key store, you provide the password for `kmsuser` to AWS KMS. Whenever you connect the AWS CloudHSM key store to its associated AWS CloudHSM cluster, AWS KMS logs in as the `kmsuser` and rotates the `kmsuser` password
Do not specify the `2FA` option when you create the `kmsuser` CU. If you do, AWS KMS cannot log in and your AWS CloudHSM key store cannot be connected to this AWS CloudHSM cluster. Once you specify 2FA, you cannot undo it. Instead, you must delete the CU and recreate it.
**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. Follow the getting started procedures as described in the [Getting started with CloudHSM Command Line Interface (CLI)](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-getting-started.html) topic of the *AWS CloudHSM User Guide*.
1. Use the [https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-user-cloudhsm-cli.html](https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-user-cloudhsm-cli.html) command to create a CU named `kmsuser`.
The password must consist of 7-32 alphanumeric characters. It is case-sensitive and cannot contain any special characters.
The following example command creates a `kmsuser` CU.
```
aws-cloudhsm > user create --username kmsuser --role crypto-user
Enter password:
Confirm password:
{
"error_code": 0,
"data": {
"username": "kmsuser",
"role": "crypto-user"
}
}
```
## Create a new AWS CloudHSM key store
After [assembling the prerequisites](#before-keystore), you can create a new AWS CloudHSM key store in the AWS KMS console or by using the [CreateCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateCustomKeyStore.html) operation.
### Using the AWS KMS console
When you create an AWS CloudHSM key store in the AWS Management Console, you can add and create the [prerequisites](#before-keystore) as part of your workflow. However, the process is quicker when you have assembled them in advance.
1. Sign in to the AWS Management Console and open the AWS Key Management Service (AWS KMS) console at [https://console.aws.amazon.com/kms](https://console.aws.amazon.com/kms).
1. To change the AWS Region, use the Region selector in the upper-right corner of the page.
1. In the navigation pane, choose **Custom key stores**, **AWS CloudHSM key stores**.
1. Choose **Create a key store**.
1. Enter a friendly name for the custom key store. The name must be unique among all custom key stores in your account.
**Important**
Do not include confidential or sensitive information in this field. This field may be displayed in plaintext in CloudTrail logs and other output.
1. Select [an AWS CloudHSM cluster](keystore-cloudhsm.md#concept-cluster) for the AWS CloudHSM key store. Or, to create a new AWS CloudHSM cluster, choose the **Create an AWS CloudHSM cluster** link.
The menu displays the AWS CloudHSM clusters in your account and region that are not already associated with an AWS CloudHSM key store. The cluster must [fulfill the requirements](#before-keystore) for association with a custom key store.
1. Choose **Choose file**, and then upload the trust anchor certificate for the AWS CloudHSM cluster that you chose. This is the `customerCA.crt` file that you created when you [initialized the cluster](https://docs.aws.amazon.com/cloudhsm/latest/userguide/initialize-cluster.html#sign-csr).
1. Enter the password of [the `kmsuser` crypto user](keystore-cloudhsm.md#concept-kmsuser) (CU) that you created in the selected cluster.
1. Choose **Create**.
When the procedure is successful, the new AWS CloudHSM key store appears in the list of AWS CloudHSM key stores in the account and Region. If it is unsuccessful, an error message appears that describes the problem and provides help on how to fix it. If you need more help, see [Troubleshooting a custom key store](fix-keystore.md).
If you try to create an AWS CloudHSM key store with all of the same property values as an existing *disconnected* AWS CloudHSM key store, AWS KMS does not create a new AWS CloudHSM key store, and it does not throw an exception or display an error. Instead, AWS KMS recognizes the duplicate as the likely consequence of a retry, and it returns the ID of the existing AWS CloudHSM key store.
**Next**: New AWS CloudHSM key stores are not automatically connected. Before you can create AWS KMS keys in the AWS CloudHSM key store, you must [connect the custom key store](connect-keystore.md) to its associated AWS CloudHSM cluster.
### Using the AWS KMS API
You can use the [CreateCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateCustomKeyStore.html) operation to create a new AWS CloudHSM key store that is associated with an AWS CloudHSM cluster in the account and Region. These examples use the AWS Command Line Interface (AWS CLI), but you can use any supported programming language.
The `CreateCustomKeyStore` operation requires the following parameter values.
+ CustomKeyStoreName – A friendly name for the custom key store that is unique in the account.
**Important**
Do not include confidential or sensitive information in this field. This field may be displayed in plaintext in CloudTrail logs and other output.
+ CloudHsmClusterId – The cluster ID of an AWS CloudHSM cluster that [fulfills the requirements](#before-keystore) for an AWS CloudHSM key store.
+ KeyStorePassword – The password of `kmsuser` CU account in the specified cluster.
+ TrustAnchorCertificate – The content of the `customerCA.crt` file that you created when you [initialized the cluster](https://docs.aws.amazon.com/cloudhsm/latest/userguide/initialize-cluster.html).
The following example uses a fictitious cluster ID. Before running the command, replace it with a valid cluster ID.
```
$ aws kms create-custom-key-store
--custom-key-store-name ExampleCloudHSMKeyStore \
--cloud-hsm-cluster-id cluster-1a23b4cdefg \
--key-store-password kmsPswd \
--trust-anchor-certificate
```
If you are using the AWS CLI, you can specify the trust anchor certificate file, instead of its contents. In the following example, the `customerCA.crt` file is in the root directory.
```
$ aws kms create-custom-key-store
--custom-key-store-name ExampleCloudHSMKeyStore \
--cloud-hsm-cluster-id cluster-1a23b4cdefg \
--key-store-password kmsPswd \
--trust-anchor-certificate file://customerCA.crt
```
When the operation is successful, `CreateCustomKeyStore` returns the custom key store ID, as shown in the following example response.
```
{
"CustomKeyStoreId": cks-1234567890abcdef0
}
```
If the operation fails, correct the error indicated by the exception, and try again. For additional help, see [Troubleshooting a custom key store](fix-keystore.md).
If you try to create an AWS CloudHSM key store with all of the same property values as an existing *disconnected* AWS CloudHSM key store, AWS KMS does not create a new AWS CloudHSM key store, and it does not throw an exception or display an error. Instead, AWS KMS recognizes the duplicate as the likely consequence of a retry, and it returns the ID of the existing AWS CloudHSM key store.
**Next**: To use the AWS CloudHSM key store, [connect it to its AWS CloudHSM cluster](connect-keystore.md).
# View an AWS CloudHSM key store
You can view the AWS CloudHSM key stores in each account and Region by using the AWS KMS console or the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) operation.
## Using the AWS KMS console
When you view the AWS CloudHSM key stores in the AWS Management Console, you can see the following:
+ The custom key store name and ID
+ The ID of associated AWS CloudHSM cluster
+ The number of HSMs in the cluster
+ The current connection state
A connection state (**Status**) value of **Disconnected** indicates that the custom key store is new and has never been connected, or it was intentionally [disconnected from its AWS CloudHSM cluster](disconnect-keystore.md). However, if your attempts to use a KMS key in a connected custom key store fail, that might indicate a problem with the custom key store or its AWS CloudHSM cluster. For help, see [How to fix a failing KMS key](fix-keystore.md#fix-cmk-failed).
To view the AWS CloudHSM key stores in a given account and Region, use the following procedure.
1. Sign in to the AWS Management Console and open the AWS Key Management Service (AWS KMS) console at [https://console.aws.amazon.com/kms](https://console.aws.amazon.com/kms).
1. To change the AWS Region, use the Region selector in the upper-right corner of the page.
1. In the navigation pane, choose **Custom key stores**, **AWS CloudHSM key stores**.
To customize the display, click the gear icon that appears below the **Create key store** button.
## Using the AWS KMS API
To view your AWS CloudHSM key stores, use the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) operation. By default, this operation returns all custom key stores in the account and Region. But you can use either the `CustomKeyStoreId` or `CustomKeyStoreName` parameter (but not both) to limit the output to a particular custom key store. For AWS CloudHSM key stores, the output consists of the custom key store ID and name, the custom key store type, the ID of the associated AWS CloudHSM cluster, and the connection state. If the connection state indicates an error, the output also includes an error code that describes the reason for the error.
The examples in this section use the [AWS Command Line Interface (AWS CLI)](https://aws.amazon.com/cli/), but you can use any supported programming language.
For example, the following command returns all custom key stores in the account and Region. You can use the `Limit` and `Marker` parameters to page through the custom key stores in the output.
```
$ aws kms describe-custom-key-stores
```
The following example command uses the `CustomKeyStoreName` parameter to get only the custom key store with the `ExampleCloudHSMKeyStore` friendly name. You can use either the `CustomKeyStoreName` or `CustomKeyStoreId` parameter (but not both) in each command.
The following example output represents an AWS CloudHSM key store that is connected to its AWS CloudHSM cluster.
**Note**
The `CustomKeyStoreType` field was added to the `DescribeCustomKeyStores` response to distinguish AWS CloudHSM key stores from external key stores.
```
$ aws kms describe-custom-key-stores --custom-key-store-name ExampleCloudHSMKeyStore
{
"CustomKeyStores": [
{
"CloudHsmClusterId": "cluster-1a23b4cdefg",
"ConnectionState": "CONNECTED",
"CreationDate": "1.499288695918E9",
"CustomKeyStoreId": "cks-1234567890abcdef0",
"CustomKeyStoreName": "ExampleCloudHSMKeyStore",
"CustomKeyStoreType": "AWS_CLOUDHSM",
"TrustAnchorCertificate": ""
}
]
}
```
A `ConnectionState` of `Disconnected` indicates that a custom key store has never been connected or it was intentionally [disconnected from its AWS CloudHSM cluster](disconnect-keystore.md). However, if attempts to use a KMS key in a connected AWS CloudHSM key store fail, that might indicate a problem with the AWS CloudHSM key store or its AWS CloudHSM cluster. For help, see [How to fix a failing KMS key](fix-keystore.md#fix-cmk-failed).
If the `ConnectionState` of the custom key store is `FAILED`, the `DescribeCustomKeyStores` response includes a `ConnectionErrorCode` element that explains the reason for the error.
For example, in the following output, the `INVALID_CREDENTIALS` value indicates that the custom key store connection failed because the [`kmsuser` password is invalid](fix-keystore.md#fix-keystore-password). For help with this and other connection error failures, see [Troubleshooting a custom key store](fix-keystore.md).
```
$ aws kms describe-custom-key-stores --custom-key-store-id cks-1234567890abcdef0
{
"CustomKeyStores": [
{
"CloudHsmClusterId": "cluster-1a23b4cdefg",
"ConnectionErrorCode": "INVALID_CREDENTIALS",
"ConnectionState": "FAILED",
"CustomKeyStoreId": "cks-1234567890abcdef0",
"CustomKeyStoreName": "ExampleCloudHSMKeyStore",
"CustomKeyStoreType": "AWS_CLOUDHSM",
"CreationDate": "1.499288695918E9",
"TrustAnchorCertificate": ""
}
]
}
```
**Learn more:**
+ [View external key stores](view-xks-keystore.md)
+ [Identify KMS keys in AWS CloudHSM key stores](identify-key-types.md#identify-key-hsm-keystore)
+ [Logging AWS KMS API calls with AWS CloudTrail](logging-using-cloudtrail.md)
# Edit AWS CloudHSM key store settings
You can change the settings of an existing AWS CloudHSM key store. The custom key store must be disconnected its AWS CloudHSM cluster.
To edit AWS CloudHSM key store settings:
1. [Disconnect the custom key store](disconnect-keystore.md) from its AWS CloudHSM cluster.
While the custom key store is disconnected, you cannot create AWS KMS keys (KMS keys) in the custom key store and you cannot use the KMS keys it contains for [cryptographic operations](manage-cmk-keystore.md#use-cmk-keystore).
1. Edit one or more of the AWS CloudHSM key store settings.
You can edit the following settings in a custom key store:
The friendly name of the custom key store.
Enter a new friendly name. The new name must be unique among all custom key stores in your AWS account.
Do not include confidential or sensitive information in this field. This field may be displayed in plaintext in CloudTrail logs and other output.
The cluster ID of the associated AWS CloudHSM cluster.
Edit this value to substitute a related AWS CloudHSM cluster for the original one. You can use this feature to repair a custom key store if its AWS CloudHSM cluster becomes corrupted or is deleted.
Specify an AWS CloudHSM cluster that shares a backup history with the original cluster and [fulfills the requirements](create-keystore.md#before-keystore) for association with a custom key store, including two active HSMs in different Availability Zones. Clusters that share a backup history have the same cluster certificate. To view the cluster certificate of a cluster, use the [DescribeClusters](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DescribeClusters.html) operation. You cannot use the edit feature to associate the custom key store with an unrelated AWS CloudHSM cluster.
The current password of the [`kmsuser` crypto user](keystore-cloudhsm.md#concept-kmsuser) (CU).
Tells AWS KMS the current password of the `kmsuser` CU in the AWS CloudHSM cluster. This action does not change the password of the `kmsuser` CU in the AWS CloudHSM cluster.
If you change the password of the `kmsuser` CU in the AWS CloudHSM cluster, use this feature to tell AWS KMS the new `kmsuser` password. Otherwise, AWS KMS cannot log into the cluster and all attempts to connect the custom key store to the cluster fail.
1. [Reconnect the custom key store](connect-keystore.md) to its AWS CloudHSM cluster.
## Edit your key store settings
You can edit your AWS CloudHSM key store settings in the AWS KMS console or by using the [UpdateCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_UpdateCustomKeyStore.html) operation.
### Using the AWS KMS console
When you edit an AWS CloudHSM key store, you can change any or of the configurable values.
1. Sign in to the AWS Management Console and open the AWS Key Management Service (AWS KMS) console at [https://console.aws.amazon.com/kms](https://console.aws.amazon.com/kms).
1. To change the AWS Region, use the Region selector in the upper-right corner of the page.
1. In the navigation pane, choose **Custom key stores**, **AWS CloudHSM key stores**.
1. Choose the row of the AWS CloudHSM key store you want to edit.
If the value in the **Connection state** column is not **Disconnected**, you must disconnect the custom key store before you can edit it. (From the **Key store actions** menu, choose **Disconnect**.)
While an AWS CloudHSM key store is disconnected, you can manage the AWS CloudHSM key store and its KMS keys, but you cannot create or use KMS keys in the AWS CloudHSM key store.
1. From the **Key store actions** menu, choose **Edit**.
1. Do one or more of the following actions.
+ Type a new friendly name for the custom key store.
+ Type the cluster ID of a related AWS CloudHSM cluster.
+ Type the current password of the `kmsuser` crypto user in the associated AWS CloudHSM cluster.
1. Choose **Save**.
When the procedure is successful, a message describes the settings that you edited. When it is unsuccessful, an error message appears that describes the problem and provides help on how to fix it. If you need more help, see [Troubleshooting a custom key store](fix-keystore.md).
1. [Reconnect the custom key store.](connect-keystore.md)
To use the AWS CloudHSM key store, you must reconnect it after editing. You can leave the AWS CloudHSM key store disconnected. But while it is disconnected, you cannot create KMS keys in the AWS CloudHSM key store or use the KMS keys in the AWS CloudHSM key store in [cryptographic operations](manage-cmk-keystore.md#use-cmk-keystore).
### Using the AWS KMS API
To change the properties of an AWS CloudHSM key store, use the [UpdateCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_UpdateCustomKeyStore.html) operation. You can change multiple properties of a custom key store in the same command. If the operation is successful, AWS KMS returns an HTTP 200 response and a JSON object with no properties. To verify that the changes are effective, use the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) operation.
The examples in this section use the [AWS Command Line Interface (AWS CLI)](https://aws.amazon.com/cli/), but you can use any supported programming language.
Begin by using [DisconnectCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_DisconnectCustomKeyStore.html) to [disconnect the custom key store](disconnect-keystore.md) from its AWS CloudHSM cluster. Replace the example custom key store ID, cks-1234567890abcdef0, with an actual ID.
```
$ aws kms disconnect-custom-key-store --custom-key-store-id cks-1234567890abcdef0
```
The first example uses [UpdateCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_UpdateCustomKeyStore.html) to change the friendly name of the AWS CloudHSM key store to `DevelopmentKeys`. The command uses the `CustomKeyStoreId` parameter to identify the AWS CloudHSM key store and the `CustomKeyStoreName` to specify the new name for the custom key store.
```
$ aws kms update-custom-key-store --custom-key-store-id cks-1234567890abcdef0 --new-custom-key-store-name DevelopmentKeys
```
The following example changes the cluster that is associated with an AWS CloudHSM key store to another backup of the same cluster. The command uses the `CustomKeyStoreId` parameter to identify the AWS CloudHSM key store and the `CloudHsmClusterId` parameter to specify the new cluster ID.
```
$ aws kms update-custom-key-store --custom-key-store-id cks-1234567890abcdef0 --cloud-hsm-cluster-id cluster-1a23b4cdefg
```
The following example tells AWS KMS that the current `kmsuser` password is `ExamplePassword`. The command uses the `CustomKeyStoreId` parameter to identify the AWS CloudHSM key store and the `KeyStorePassword` parameter to specify the current password.
```
$ aws kms update-custom-key-store --custom-key-store-id cks-1234567890abcdef0 --key-store-password ExamplePassword
```
The final command reconnects the AWS CloudHSM key store to its AWS CloudHSM cluster. You can leave the custom key store in the disconnected state, but you must connect it before you can create new KMS keys or use existing KMS keys for [cryptographic operations](manage-cmk-keystore.md#use-cmk-keystore). Replace the example custom key store ID with an actual ID.
```
$ aws kms connect-custom-key-store --custom-key-store-id cks-1234567890abcdef0
```
# Connect an AWS CloudHSM key store
New AWS CloudHSM key stores are not connected. Before you can create and use AWS KMS keys in your AWS CloudHSM key store, you need to connect it to its associated AWS CloudHSM cluster. You can connect and disconnect your AWS CloudHSM key store at any time, and [view its connection state](view-keystore.md#view-keystore-console).
You are not required to connect your AWS CloudHSM key store. You can leave an AWS CloudHSM key store in a disconnected state indefinitely and connect it only when you need to use it. However, you might want to test the connection periodically to verify that the settings are correct and it can be connected.
**Note**
AWS CloudHSM key stores have a `DISCONNECTED` connection state only when the key store has never been connected or you explicitly disconnect it. If your AWS CloudHSM key store connection state is `CONNECTED` but you are having trouble using it, make sure that its associated AWS CloudHSM cluster is active and contains at least one active HSMs. For help with connection failures, see [Troubleshooting a custom key store](fix-keystore.md).
When you connect an AWS CloudHSM key store, AWS KMS finds the associated AWS CloudHSM cluster, connects to it, logs into the AWS CloudHSM client as the [`kmsuser` crypto user](keystore-cloudhsm.md#concept-kmsuser) (CU), and then rotates the `kmsuser` password. AWS KMS remains logged into the AWS CloudHSM client as long as the AWS CloudHSM key store is connected.
To establish the connection, AWS KMS creates a [security group](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html) named `kms-` in the virtual private cloud (VPC) of the cluster. The security group has a single rule that allows inbound traffic from the cluster security group. AWS KMS also creates an [elastic network interface](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_ElasticNetworkInterfaces.html) (ENI) in each Availability Zone of the private subnet for the cluster. AWS KMS adds the ENIs to the `kms-` security group and the security group for the cluster. The description of each ENI is `KMS managed ENI for cluster `.
The connection process can take an extended amount of time to complete; up to 20 minutes.
Before you connect the AWS CloudHSM key store, verify that it meets the requirements.
+ Its associated AWS CloudHSM cluster must contain at least one active HSM. To find the number of HSMs in the cluster, view the cluster in the AWS CloudHSM console or use the [DescribeClusters](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DescribeClusters.html) operation. If necessary, you can [add an HSM](https://docs.aws.amazon.com/cloudhsm/latest/userguide/add-remove-hsm.html).
+ The cluster must have a [`kmsuser` crypto user](create-keystore.md#kmsuser-concept) (CU) account, but that CU cannot be logged into the cluster when you connect the AWS CloudHSM key store. For help with logging out, see [How to log out and reconnect](fix-keystore.md#login-kmsuser-2).
+ The connection state of the AWS CloudHSM key store cannot be `DISCONNECTING` or `FAILED`. To view the connection state, use the AWS KMS console or the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) response. If the connection state is `FAILED`, disconnect the custom key store, fix the problem, and then connect it.
For help with connection failures, see [How to fix a connection failure](fix-keystore.md#fix-keystore-failed).
When your AWS CloudHSM key store is connected, you can [create KMS keys in it](create-cmk-keystore.md) and use existing KMS keys in [cryptographic operations](manage-cmk-keystore.md#use-cmk-keystore).
## Connect and reconnect to your AWS CloudHSM key store
You can connect, or reconnect, your AWS CloudHSM key store in the AWS KMS console or by using the [ConnectCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_ConnectCustomKeyStore.html) operation.
### Using the AWS KMS console
To connect an AWS CloudHSM key store in the AWS Management Console, begin by selecting the AWS CloudHSM key store from the **Custom key stores** page. The connection process can take up to 20 minutes to complete.
1. Sign in to the AWS Management Console and open the AWS Key Management Service (AWS KMS) console at [https://console.aws.amazon.com/kms](https://console.aws.amazon.com/kms).
1. To change the AWS Region, use the Region selector in the upper-right corner of the page.
1. In the navigation pane, choose **Custom key stores**, **AWS CloudHSM key stores**.
1. Choose the row of the AWS CloudHSM key store you want to connect.
If the connection state of the AWS CloudHSM key store is **Failed**, you must [disconnect the custom key store](disconnect-keystore.md#disconnect-keystore-console) before you connect it.
1. From the **Key store actions** menu, choose **Connect**.
AWS KMS begins the process of connecting your custom key store. It finds the associated AWS CloudHSM cluster, builds the required network infrastructure, connects to it, logs into the AWS CloudHSM cluster as the `kmsuser` CU, and rotates the `kmsuser` password. When the operation completes, the connection state changes to **Connected**.
If the operation fails, an error message appears that describes the reason for the failure. Before you try to connect again, [view the connection state](view-keystore.md) of your AWS CloudHSM key store. If it is **Failed**, you must [disconnect the custom key store](disconnect-keystore.md#disconnect-keystore-console) before you connect it again. If you need help, see [Troubleshooting a custom key store](fix-keystore.md).
**Next:** [Create a KMS key in an AWS CloudHSM key store](create-cmk-keystore.md).
### Using the AWS KMS API
To connect a disconnected AWS CloudHSM key store, use the [ConnectCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_ConnectCustomKeyStore.html) operation. The associated AWS CloudHSM cluster must contain at least one active HSM and the connection state cannot be `FAILED`.
The connection process takes an extended amount of time to complete; up to 20 minutes. Unless it fails quickly, the operation returns an HTTP 200 response and a JSON object with no properties. However, this initial response does not indicate that the connection was successful. To determine the connection state of the custom key store, see the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) response.
The examples in this section use the [AWS Command Line Interface (AWS CLI)](https://aws.amazon.com/cli/), but you can use any supported programming language.
To identify the AWS CloudHSM key store, use its custom key store ID. You can find the ID on the **Custom key stores** page in the console or by using the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) operation with no parameters. Before running this example, replace the example ID with a valid one.
```
$ aws kms connect-custom-key-store --custom-key-store-id cks-1234567890abcdef0
```
To verify that the AWS CloudHSM key store is connected, use the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) operation. By default, this operation returns all custom keys stores in your account and Region. But you can use either the `CustomKeyStoreId` or `CustomKeyStoreName` parameter (but not both) to limit the response to particular custom key stores. The `ConnectionState` value of `CONNECTED` indicates that the custom key store is connected to its AWS CloudHSM cluster.
**Note**
The `CustomKeyStoreType` field was added to the `DescribeCustomKeyStores` response to distinguish AWS CloudHSM key stores from external key stores.
```
$ aws kms describe-custom-key-stores --custom-key-store-id cks-1234567890abcdef0
{
"CustomKeyStores": [
"CustomKeyStoreId": "cks-1234567890abcdef0",
"CustomKeyStoreName": "ExampleCloudHSMKeyStore",
"CloudHsmClusterId": "cluster-1a23b4cdefg",
"CustomKeyStoreType": "AWS_CLOUDHSM",
"TrustAnchorCertificate": "",
"CreationDate": "1.499288695918E9",
"ConnectionState": "CONNECTED"
],
}
```
If the `ConnectionState` value is failed, the `ConnectionErrorCode` element indicates the reason for the failure. In this case, AWS KMS could not find an AWS CloudHSM cluster in your account with the cluster ID `cluster-1a23b4cdefg`. If you deleted the cluster, you can [restore it from a backup](https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-cluster-from-backup.html) of the original cluster and then [edit the cluster ID](update-keystore.md) for the custom key store. For help responding to a connection error code, see [How to fix a connection failure](fix-keystore.md#fix-keystore-failed).
```
$ aws kms describe-custom-key-stores --custom-key-store-id cks-1234567890abcdef0
{
"CustomKeyStores": [
"CustomKeyStoreId": "cks-1234567890abcdef0",
"CustomKeyStoreName": "ExampleKeyStore",
"CloudHsmClusterId": "cluster-1a23b4cdefg",
"CustomKeyStoreType": "AWS_CLOUDHSM",
"TrustAnchorCertificate": "",
"CreationDate": "1.499288695918E9",
"ConnectionState": "FAILED"
"ConnectionErrorCode": "CLUSTER_NOT_FOUND"
],
}
```
# Disconnect an AWS CloudHSM key store
When you disconnect an AWS CloudHSM key store, AWS KMS logs out of the AWS CloudHSM client, disconnects from the associated AWS CloudHSM cluster, and removes the network infrastructure that it created to support the connection.
While an AWS CloudHSM key store is disconnected, you can manage the AWS CloudHSM key store and its KMS keys, but you cannot create or use KMS keys in the AWS CloudHSM key store. The connection state of the key store is `DISCONNECTED` and the [key state](key-state.md) of KMS keys in the custom key store is `Unavailable`, unless they are `PendingDeletion`. You can reconnect the AWS CloudHSM key store at any time.
**Note**
AWS CloudHSM key stores have a `DISCONNECTED` connection state only when the key store has never been connected or you explicitly disconnect it. If your AWS CloudHSM key store connection state is `CONNECTED` but you are having trouble using it, make sure that its associated AWS CloudHSM cluster is active and contains at least one active HSMs. For help with connection failures, see [Troubleshooting a custom key store](fix-keystore.md).
When you disconnect a custom key store, the KMS keys in the key store become unusable right away (subject to eventual consistency). However, resources encrypted with [data keys](data-keys.md) protected by the KMS key are not affected until the KMS key is used again, such as to decrypt the data key. This issue affects AWS services, many of which use data keys to protect your resources. For details, see [How unusable KMS keys affect data keys](unusable-kms-keys.md).
**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.
To better estimate the effect of disconnecting your custom key store, [identify the KMS keys](find-cmk-in-keystore.md) in the custom key store and [determine their past use](deleting-keys-determining-usage.md).
You might disconnect an AWS CloudHSM key store for reasons such as the following:
+ **To rotate of the `kmsuser` password.** AWS KMS changes the `kmsuser` password each time that it connects to the AWS CloudHSM cluster. To force a password rotation, just disconnect and reconnect.
+ **To audit the key material** for the KMS keys in the AWS CloudHSM cluster. When you disconnect the custom key store, AWS KMS logs out of the [`kmsuser` crypto user](keystore-cloudhsm.md#concept-kmsuser) account in the AWS CloudHSM client. This allows you to log into the cluster as the `kmsuser` CU and audit and manage the key material for the KMS key.
+ **To immediately disable all KMS keys** in the AWS CloudHSM key store. You can [disable and re-enable KMS keys](enabling-keys.md) in an AWS CloudHSM key store by using the AWS Management Console or the [DisableKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DisableKey.html) operation. These operations complete quickly, but they act on one KMS key at a time. Disconnecting the AWS CloudHSM key store immediately changes the key state of all KMS keys in the AWS CloudHSM key store to `Unavailable`, which prevents them from being used in any cryptographic operation.
+ **To repair a failed connection attempt**. If an attempt to connect an AWS CloudHSM key store fails (the connection state of the custom key store is `FAILED`), you must disconnect the AWS CloudHSM key store before you try to connect it again.
## Disconnect your AWS CloudHSM key store
You can disconnect your AWS CloudHSM key store in the AWS KMS console or by using the [DisconnectCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_DisconnectCustomKeyStore.html) operation.
### Disconnect using the AWS KMS console
To disconnect a connected AWS CloudHSM key store in the AWS KMS console, begin by choosing the AWS CloudHSM key store from the **Custom Key Stores** page.
1. Sign in to the AWS Management Console and open the AWS Key Management Service (AWS KMS) console at [https://console.aws.amazon.com/kms](https://console.aws.amazon.com/kms).
1. To change the AWS Region, use the Region selector in the upper-right corner of the page.
1. In the navigation pane, choose **Custom key stores**, **AWS CloudHSM key stores**.
1. Choose the row of the external key store you want to disconnect.
1. From the **Key store actions** menu, choose **Disconnect**.
When the operation completes, the connection state changes from **Disconnecting** to **Disconnected**. If the operation fails, an error message appears that describes the problem and provides help on how to fix it. If you need more help, see [Troubleshooting a custom key store](fix-keystore.md).
### Disconnect using the AWS KMS API
To disconnect a connected AWS CloudHSM key store, use the [DisconnectCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_DisconnectCustomKeyStore.html) operation. If the operation is successful, AWS KMS returns an HTTP 200 response and a JSON object with no properties.
The examples in this section use the [AWS Command Line Interface (AWS CLI)](https://aws.amazon.com/cli/), but you can use any supported programming language.
This example disconnects an AWS CloudHSM key store. Before running this example, replace the example ID with a valid one.
```
$ aws kms disconnect-custom-key-store --custom-key-store-id cks-1234567890abcdef0
```
To verify that the AWS CloudHSM key store is disconnected, use the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) operation. By default, this operation returns all custom keys stores in your account and Region. But you can use either the `CustomKeyStoreId` and `CustomKeyStoreName` parameter (but not both) to limit the response to particular custom key stores. The `ConnectionState` value of `DISCONNECTED` indicates that this example AWS CloudHSM key store is not connected to its AWS CloudHSM cluster.
```
$ aws kms describe-custom-key-stores --custom-key-store-id cks-1234567890abcdef0
{
"CustomKeyStores": [
"CloudHsmClusterId": "cluster-1a23b4cdefg",
"ConnectionState": "DISCONNECTED",
"CreationDate": "1.499288695918E9",
"CustomKeyStoreId": "cks-1234567890abcdef0",
"CustomKeyStoreName": "ExampleKeyStore",
"CustomKeyStoreType": "AWS_CLOUDHSM",
"TrustAnchorCertificate": ""
],
}
```
# Delete an AWS CloudHSM key store
When you delete an AWS CloudHSM key store, AWS KMS deletes all metadata about the AWS CloudHSM key store from KMS, including information about its association with an AWS CloudHSM cluster. This operation does not affect the AWS CloudHSM cluster, its HSMs, or its users. You can create a new AWS CloudHSM key store that is associated with the same AWS CloudHSM cluster, but you cannot undo the delete operation.
You can only delete an AWS CloudHSM key store that is disconnected from its AWS CloudHSM cluster and does not contain any AWS KMS keys. Before you delete a custom key store, do the following.
+ Verify that you will never need to use any of the KMS keys in the key store for any [cryptographic operations](manage-cmk-keystore.md#use-cmk-keystore). Then [schedule deletion](deleting-keys.md#delete-cmk-keystore) of all of the KMS keys from the key store. For help finding the KMS keys in an AWS CloudHSM key store, see [Find the KMS keys in an AWS CloudHSM key store](find-cmk-in-keystore.md).
+ Confirm that all KMS keys have been deleted. To view the KMS keys in an AWS CloudHSM key store, see [Identify KMS keys in AWS CloudHSM key stores](identify-key-types.md#identify-key-hsm-keystore).
+ [Disconnect the AWS CloudHSM key store](disconnect-keystore.md) from its AWS CloudHSM cluster.
Instead of deleting the AWS CloudHSM key store, consider [disconnecting it](disconnect-keystore.md) from its associated AWS CloudHSM cluster. While an AWS CloudHSM key store is disconnected, you can manage the AWS CloudHSM key store and its AWS KMS keys. But you cannot create or use KMS keys in the AWS CloudHSM key store. You can reconnect the AWS CloudHSM key store at any time.
## Delete your AWS CloudHSM key store
You can delete your AWS CloudHSM key store in the AWS KMS console or by using the [DeleteCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeleteCustomKeyStore.html) operation.
### Using the AWS KMS console
To delete an AWS CloudHSM key store in the AWS Management Console, begin by selecting the AWS CloudHSM key store from the **Custom key stores** page.
1. Sign in to the AWS Management Console and open the AWS Key Management Service (AWS KMS) console at [https://console.aws.amazon.com/kms](https://console.aws.amazon.com/kms).
1. To change the AWS Region, use the Region selector in the upper-right corner of the page.
1. In the navigation pane, choose **Custom key stores**, **AWS CloudHSM key stores**.
1. Find the row that represents the AWS CloudHSM key store that you want to delete. If the **Connection state** of the AWS CloudHSM key store is not **Disconnected**, you must [disconnect the AWS CloudHSM key store](disconnect-keystore.md) before you delete it.
1. From the **Key store actions** menu, choose **Delete**.
When the operation completes, a success message appears and the AWS CloudHSM key store no longer appears in the key stores list. If the operation is unsuccessful, an error message appears that describes the problem and provides help on how to fix it. If you need more help, see [Troubleshooting a custom key store](fix-keystore.md).
### Using the AWS KMS API
To delete an AWS CloudHSM key store, use the [DeleteCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeleteCustomKeyStore.html) operation. If the operation is successful, AWS KMS returns an HTTP 200 response and a JSON object with no properties.
To begin, verify that the AWS CloudHSM key store does not contain any AWS KMS keys. You cannot delete a custom key store that contains KMS keys. The first example command uses [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) to search for AWS KMS keys in the AWS CloudHSM key store with the example *cks-1234567890abcdef0* custom key store ID. In this case, the command does not return any KMS keys. If it does, use the [ScheduleKeyDeletion](https://docs.aws.amazon.com/kms/latest/APIReference/API_ScheduleKeyDeletion.html) operation to schedule deletion of each of the KMS keys.
------
#### [ Bash ]
```
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
```
------
#### [ PowerShell ]
```
PS C:\> Get-KMSKeyList | Get-KMSKey | where CustomKeyStoreId -eq 'cks-1234567890abcdef0'
```
------
Next, disconnect the AWS CloudHSM key store. This example command uses the [DisconnectCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_DisconnectCustomKeyStore.html) operation to disconnect an AWS CloudHSM key store from its AWS CloudHSM cluster. Before running this command, replace the example custom key store ID with a valid one.
------
#### [ Bash ]
```
$ aws kms disconnect-custom-key-store --custom-key-store-id cks-1234567890abcdef0
```
------
#### [ PowerShell ]
```
PS C:\> Disconnect-KMSCustomKeyStore -CustomKeyStoreId cks-1234567890abcdef0
```
------
After the custom key store is disconnected, you can use the [DeleteCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeleteCustomKeyStore.html) operation to delete it.
------
#### [ Bash ]
```
$ aws kms delete-custom-key-store --custom-key-store-id cks-1234567890abcdef0
```
------
#### [ PowerShell ]
```
PS C:\> Remove-KMSCustomKeyStore -CustomKeyStoreId cks-1234567890abcdef0
```
------
# Troubleshooting a custom key store
AWS CloudHSM key stores are designed to be available and resilient. However, there are some error conditions that you might have to repair to keep your AWS CloudHSM key store operational.
**Topics**
+ [How to fix unavailable KMS keys](#fix-unavailable-cmks)
+ [How to fix a failing KMS key](#fix-cmk-failed)
+ [How to fix a connection failure](#fix-keystore-failed)
+ [How to respond to a cryptographic operation failure](#fix-keystore-communication)
+ [How to fix invalid `kmsuser` credentials](#fix-keystore-password)
+ [How to delete orphaned key material](#fix-keystore-orphaned-key)
+ [How to recover deleted key material for a KMS key](#fix-keystore-recover-backing-key)
+ [How to log in as `kmsuser`](#fix-login-as-kmsuser)
## How to fix unavailable KMS keys
The [key state](key-state.md) of AWS KMS keys in an AWS CloudHSM key store is typically `Enabled`. Like all KMS keys, the key state changes when you disable the KMS keys in an AWS CloudHSM key store or schedule them for deletion. However, unlike other KMS keys, the KMS keys in a custom key store can also have a [key state](key-state.md) of `Unavailable`.
A key state of `Unavailable` indicates that the KMS key is in a custom key store that was intentionally [disconnected](disconnect-keystore.md) and attempts to reconnect it, if any, failed. While a KMS key is unavailable, you can view and manage the KMS key, but you cannot use it for [cryptographic operations](manage-cmk-keystore.md#use-cmk-keystore).
To find the key state of a KMS key, on the **Customer managed keys** page, view the **Status** field of the KMS key. Or, use the [DescribeKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html) operation and view the `KeyState` element in the response. For details, see [Identify and view keys](viewing-keys.md).
The KMS keys in a disconnected custom key store will have a key state of `Unavailable` or `PendingDeletion`. KMS keys that are scheduled for deletion from a custom key store have a `Pending Deletion` key state, even when the custom key store is disconnected. This allows you to cancel the scheduled key deletion without reconnecting the custom key store.
To fix an unavailable KMS key, [reconnect the custom key store](disconnect-keystore.md). After the custom key store is reconnected, the key state of the KMS keys in the custom key store is automatically restored to its previous state, such as `Enabled` or `Disabled`. KMS keys that are pending deletion remain in the `PendingDeletion` state. However, while the problem persists, [enabling and disabling an unavailable KMS key](enabling-keys.md) does not change its key state. The enable or disable action takes effect only when the key becomes available.
For help with failed connections, see [How to fix a connection failure](#fix-keystore-failed).
## How to fix a failing KMS key
Problems with creating and using KMS keys in AWS CloudHSM key stores can be caused by a problem with your AWS CloudHSM key store, its associated AWS CloudHSM cluster, the KMS key, or its key material.
When an AWS CloudHSM key store is disconnected from its AWS CloudHSM cluster, the key state of KMS keys in the custom key store is `Unavailable`. All requests to create KMS keys in a disconnected AWS CloudHSM key store return a `CustomKeyStoreInvalidStateException` exception. All requests to encrypt, decrypt, re-encrypt, or generate data keys return a `KMSInvalidStateException` exception. To fix the problem, [reconnect the AWS CloudHSM key store](connect-keystore.md).
However, your attempts to use a KMS key in an AWS CloudHSM key store for [cryptographic operations](manage-cmk-keystore.md#use-cmk-keystore) might fail even when its key state is `Enabled` and the connection state of the AWS CloudHSM key store is `Connected`. This might be caused by any of the following conditions.
+ The key material for the KMS key might have been deleted from the associated AWS CloudHSM cluster. To investigate, [find the key id](find-handle-for-cmk-id.md) of the key material for a KMS key and, if necessary, try to [recover the key material](#fix-keystore-recover-backing-key).
+ All HSMs were deleted from the AWS CloudHSM cluster that is associated with the AWS CloudHSM key store. To use a KMS key in an AWS CloudHSM key store in a cryptographic operation, its AWS CloudHSM cluster must contain at least one active HSM. To verify the number and state of HSMs in an AWS CloudHSM cluster, [use the AWS CloudHSM console](https://docs.aws.amazon.com/cloudhsm/latest/userguide/add-remove-hsm.html) or the [DescribeClusters](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DescribeClusters.html) operation. To add an HSM to the cluster, use the AWS CloudHSM console or the [CreateHsm](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_CreateHsm.html) operation.
+ The AWS CloudHSM cluster associated with the AWS CloudHSM key store was deleted. To fix the problem, [create a cluster from a backup](https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-cluster-from-backup.html) that is related to the original cluster, such as a backup of the original cluster, or a backup that was used to create the original cluster. Then, [edit the cluster ID](update-keystore.md) in the custom key store settings. For instructions, see [How to recover deleted key material for a KMS key](#fix-keystore-recover-backing-key).
+ The AWS CloudHSM cluster associated with the custom key store did not have any available PKCS \$111 sessions. This typically occurs during periods of high burst traffic when additional sessions are needed to service the traffic. To respond to a `KMSInternalException` with an error message about PKCS \$111 sessions, back off and retry the request again.
## How to fix a connection failure
If you try to [connect an AWS CloudHSM key store](connect-keystore.md) to its AWS CloudHSM cluster, but the operation fails, the connection state of the AWS CloudHSM key store changes to `FAILED`. To find the connection state of an AWS CloudHSM key store, use the AWS KMS console or the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) operation.
Alternatively, some connection attempts fail quickly due to easily detected cluster configuration errors. In this case, the connection state is still `DISCONNECTED`. These failures return an error message or [exception](https://docs.aws.amazon.com/kms/latest/APIReference/API_ConnectCustomKeyStore.html#API_ConnectCustomKeyStore_Errors) that explains why the attempt failed. Review the exception description and [cluster requirements](create-keystore.md#before-keystore), fix the problem, [update the AWS CloudHSM key store](update-keystore.md), if necessary, and try to connect again.
When the connection state is `FAILED`, run the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) operation and see the `ConnectionErrorCode` element in the response.
**Note**
When the connection state of an AWS CloudHSM key store is `FAILED`, you must [disconnect the AWS CloudHSM key store](disconnect-keystore.md) before attempting to reconnect it. You cannot connect an AWS CloudHSM key store with a `FAILED` connection state.
+ `CLUSTER_NOT_FOUND` indicates that AWS KMS cannot find an AWS CloudHSM cluster with the specified cluster ID. This might occur because the wrong cluster ID was provided to an API operation or the cluster was deleted and not replaced. To fix this error, verify the cluster ID, such as by using the AWS CloudHSM console or the [DescribeClusters](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DescribeClusters.html) operation. If the cluster was deleted, [create a cluster from a recent backup](https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-cluster-from-backup.html) of the original. Then, [disconnect the AWS CloudHSM key store](disconnect-keystore.md), [edit the AWS CloudHSM key store](update-keystore.md) cluster ID setting, and [reconnect the AWS CloudHSM key store](connect-keystore.md) to the cluster.
+ `INSUFFICIENT_CLOUDHSM_HSMS` indicates that the associated AWS CloudHSM cluster does not contain any HSMs. To connect, the cluster must have at least one HSM. To find the number of HSMs in the cluster, use the [DescribeClusters](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DescribeClusters.html) operation. To resolve this error, [add at least one HSM](https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-hsm.html) to the cluster. If you add multiple HSMs, it's best to create them in different Availability Zones.
+ `INSUFFICIENT_FREE_ADDRESSES_IN_SUBNET` indicates that AWS KMS could not connect the AWS CloudHSM key store to its AWS CloudHSM cluster because at least one [private subnet associated with the cluster](https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-subnets.html) doesn't have any available IP addresses. An AWS CloudHSM key store connection requires one free IP address in each of the associated private subnets, although two are preferable.
You [can't add IP addresses](https://aws.amazon.com/premiumsupport/knowledge-center/vpc-ip-address-range/) (CIDR blocks) to an existing subnet. If possible, move or delete other resources that are using the IP addresses in the subnet, such as unused EC2 instances or elastic network interfaces. Otherwise, you can [create a cluster from a recent backup](https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-cluster-from-backup.html) of the AWS CloudHSM cluster with new or existing private subnets that have [more free address space](https://docs.aws.amazon.com/vpc/latest/userguide/configure-subnets.html#subnet-sizing). Then, to associate the new cluster with your AWS CloudHSM key store, [disconnect the custom key store](disconnect-keystore.md), [change the cluster ID](update-keystore.md) of the AWS CloudHSM key store to the ID of the new cluster, and try to connect again.
**Tip**
To avoid [resetting the `kmsuser` password](#fix-keystore-password), use the most recent backup of the AWS CloudHSM cluster.
+ `INTERNAL_ERROR` indicates that AWS KMS could not complete the request due to an internal error. Retry the request. For `ConnectCustomKeyStore` requests, disconnect the AWS CloudHSM key store before trying to connect again.
+ `INVALID_CREDENTIALS` indicates that AWS KMS cannot log into the associated AWS CloudHSM cluster because it doesn't have the correct `kmsuser` account password. For help with this error, see [How to fix invalid `kmsuser` credentials](#fix-keystore-password).
+ `NETWORK_ERRORS` usually indicates transient network issues. [Disconnect the AWS CloudHSM key store](disconnect-keystore.md), wait a few minutes, and try to connect again.
+ `SUBNET_NOT_FOUND` indicates that at least one subnet in the AWS CloudHSM cluster configuration was deleted. If AWS KMS cannot find all of the subnets in the cluster configuration, attempts to connect the AWS CloudHSM key store to the AWS CloudHSM cluster fail.
To fix this error, [create a cluster from a recent backup](https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-cluster-from-backup.html) of the same AWS CloudHSM cluster. (This process creates a new cluster configuration with a VPC and private subnets.) Verify that the new cluster meets the [requirements for a custom key store](create-keystore.md#before-keystore), and note the new cluster ID. Then, to associate the new cluster with your AWS CloudHSM key store, [disconnect the custom key store](disconnect-keystore.md), [change the cluster ID](update-keystore.md) of the AWS CloudHSM key store to the ID of the new cluster, and try to connect again.
**Tip**
To avoid [resetting the `kmsuser` password](#fix-keystore-password), use the most recent backup of the AWS CloudHSM cluster.
+ `USER_LOCKED_OUT` indicates that the [`kmsuser` crypto user (CU) account](keystore-cloudhsm.md#concept-kmsuser) is locked out of the associated AWS CloudHSM cluster due to too many failed password attempts. For help with this error, see [How to fix invalid `kmsuser` credentials](#fix-keystore-password).
To fix this error, [disconnect the AWS CloudHSM key store](disconnect-keystore.md) and use the [https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-user-change-password.html](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-user-change-password.html) command in CloudHSM CLI to change the `kmsuser` account password. Then, [edit the `kmsuser` password setting](update-keystore.md) for the custom key store, and try to connect again. For help, use the procedure described in the [How to fix invalid `kmsuser` credentials](#fix-keystore-password) topic.
+ `USER_LOGGED_IN` indicates that the `kmsuser` CU account is logged into the associated AWS CloudHSM cluster. This prevents AWS KMS from rotating the `kmsuser` account password and logging into the cluster. To fix this error, log the `kmsuser` CU out of the cluster. If you changed the `kmsuser` password to log into the cluster, you must also and update the key store password value for the AWS CloudHSM key store. For help, see [How to log out and reconnect](#login-kmsuser-2).
+ `USER_NOT_FOUND` indicates that AWS KMS cannot find a `kmsuser` CU account in the associated AWS CloudHSM cluster. To fix this error, [create a `kmsuser` CU account](create-keystore.md#kmsuser-concept) in the cluster, and then [update the key store password value](update-keystore.md) for the AWS CloudHSM key store. For help, see [How to fix invalid `kmsuser` credentials](#fix-keystore-password).
## How to respond to a cryptographic operation failure
A cryptographic operation that uses a KMS key in a custom key store might fail with a `KMSInvalidStateException`. The following error messages might accompany the `KMSInvalidStateException`.
| |
| --- |
| KMS cannot communicate with your CloudHSM cluster. This might be a transient network issue. If you see this error repeatedly, verify that the Network ACLs and the security group rules for the VPC of your AWS CloudHSM cluster are correct. |
+ Although this is an HTTPS 400 error, it might result from transient network issues. To respond, begin by retrying the request. However, if it continues to fail, examine the configuration of your networking components. This error is most likely caused by the misconfiguration of a networking component, such as a firewall rule or VPC security group rule that is blocking outgoing traffic. For example, KMS cannot communicate with AWS CloudHSM clusters over IPv6. For details on prerequisites, see [Create an AWS CloudHSM key store](create-keystore.md).
| |
| --- |
| KMS cannot communicate with your AWS CloudHSM cluster because the kmsuser is locked out. If you see this error repeatedly, disconnect the AWS CloudHSM key store and reset the kmsuser account password. Update the kmsuser password for the custom key store and try the request again. |
+ This error message indicates that the [`kmsuser` crypto user (CU) account](keystore-cloudhsm.md#concept-kmsuser) is locked out of the associated AWS CloudHSM cluster due to too many failed password attempts. For help with this error, see [How to disconnect and log in](#login-kmsuser-1).
## How to fix invalid `kmsuser` credentials
When you [connect an AWS CloudHSM key store](connect-keystore.md), AWS KMS logs into the associated AWS CloudHSM cluster as the [`kmsuser` crypto user](keystore-cloudhsm.md#concept-kmsuser) (CU). It remains logged in until the AWS CloudHSM key store is disconnected. The [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) response shows a `ConnectionState` of `FAILED` and `ConnectionErrorCode` value of `INVALID_CREDENTIALS`, as shown in the following example.
If you disconnect the AWS CloudHSM key store and change the `kmsuser` password, AWS KMS cannot log into the AWS CloudHSM cluster with the credentials of the `kmsuser` CU account. As a result, all attempts to connect the AWS CloudHSM key store fail. The `DescribeCustomKeyStores` response shows a `ConnectionState` of `FAILED` and `ConnectionErrorCode` value of `INVALID_CREDENTIALS`, as shown in the following example.
```
$ aws kms describe-custom-key-stores --custom-key-store-name ExampleKeyStore
{
"CustomKeyStores": [
"CloudHsmClusterId": "cluster-1a23b4cdefg",
"ConnectionErrorCode": "INVALID_CREDENTIALS"
"CustomKeyStoreId": "cks-1234567890abcdef0",
"CustomKeyStoreName": "ExampleKeyStore",
"TrustAnchorCertificate": "",
"CreationDate": "1.499288695918E9",
"ConnectionState": "FAILED"
],
}
```
Also, after five failed attempts to log into the cluster with an incorrect password, AWS CloudHSM locks the user account. To log into the cluster, you must change the account password.
If AWS KMS gets a lockout response when it tries to log into the cluster as the `kmsuser` CU, the request to connect the AWS CloudHSM key store fails. The [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) response includes a `ConnectionState` of `FAILED` and `ConnectionErrorCode` value of `USER_LOCKED_OUT`, as shown in the following example.
```
$ aws kms describe-custom-key-stores --custom-key-store-name ExampleKeyStore
{
"CustomKeyStores": [
"CloudHsmClusterId": "cluster-1a23b4cdefg",
"ConnectionErrorCode": "USER_LOCKED_OUT"
"CustomKeyStoreId": "cks-1234567890abcdef0",
"CustomKeyStoreName": "ExampleKeyStore",
"TrustAnchorCertificate": "",
"CreationDate": "1.499288695918E9",
"ConnectionState": "FAILED"
],
}
```
To repair any of these conditions, use the following procedure.
1. [Disconnect the AWS CloudHSM key store](disconnect-keystore.md).
1. Run the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) operation and view the value of the `ConnectionErrorCode` element in the response.
+ If the `ConnectionErrorCode` value is `INVALID_CREDENTIALS`, determine the current password for the `kmsuser` account. If necessary, use the [https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-user-change-password.html](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-user-change-password.html) command in CloudHSM CLI to set the password to a known value.
+ If the `ConnectionErrorCode` value is `USER_LOCKED_OUT`, you must use the [https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-user-change-password.html](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-user-change-password.html) command in CloudHSM CLI to change the `kmsuser` password.
1. [Edit the `kmsuser` password setting](update-keystore.md) so it matches the current `kmsuser` password in the cluster. This action tells AWS KMS which password to use to log into the cluster. It does not change the `kmsuser` password in the cluster.
1. [Connect the custom key store](connect-keystore.md).
## How to delete orphaned key material
After scheduling deletion of a KMS key from an AWS CloudHSM key store, you might need to manually delete the corresponding key material from the associated AWS CloudHSM cluster.
When you create a KMS key in an AWS CloudHSM key store, AWS KMS creates the KMS key metadata in AWS KMS and generates the key material in the associated AWS CloudHSM cluster. When you schedule deletion of a KMS key in an AWS CloudHSM key store, after the waiting period, AWS KMS deletes the KMS key metadata. Then AWS KMS makes a best effort to delete the corresponding key material from the AWS CloudHSM cluster. The attempt might fail if AWS KMS cannot access the cluster, such as when it's disconnected from the AWS CloudHSM key store or the `kmsuser` password changes. AWS KMS does not attempt to delete key material from cluster backups.
AWS KMS reports the results of its attempt to delete the key material from the cluster in the `DeleteKey` event entry of your AWS CloudTrail logs. It appears in the `backingKeysDeletionStatus` element of the `additionalEventData` element, as shown in the following example entry. The entry also includes the KMS key ARN, the AWS CloudHSM cluster ID, and the ID (`backing-key-id`) of the key material.
```
{
"eventVersion": "1.08",
"userIdentity": {
"accountId": "111122223333",
"invokedBy": "AWS Internal"
},
"eventTime": "2021-12-10T14:23:51Z",
"eventSource": "kms.amazonaws.com",
"eventName": "DeleteKey",
"awsRegion": "us-west-2",
"sourceIPAddress": "AWS Internal",
"userAgent": "AWS Internal",
"requestParameters": null,
"responseElements": {
"keyId":"arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
},
"additionalEventData": {
"customKeyStoreId": "cks-1234567890abcdef0",
"clusterId": "cluster-1a23b4cdefg",
"backingKeys": "[{\"backingKeyId\":\"backing-key-id\"}]",
"backingKeysDeletionStatus": "[{\"backingKeyId\":\"backing-key-id\",\"deletionStatus\":\"FAILURE\"}]"
},
"eventID": "c21f1f47-f52b-4ffe-bff0-6d994403cf40",
"readOnly": false,
"resources": [
{
"accountId": "111122223333",
"type": "AWS::KMS::Key",
"ARN": "arn:aws:kms:eu-west-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
}
],
"eventType": "AwsServiceEvent",
"recipientAccountId": "111122223333",
"managementEvent": true,
"eventCategory": "Management"
}
```
**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*.
The following procedures demonstrate how to delete the orphaned key material from the associated AWS CloudHSM cluster.
1. Disconnect the AWS CloudHSM key store, if it is not already disconnected, then [https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-login.html](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-login.html), as explained in [How to disconnect and log in](#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 [key delete](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-key-delete.html) command in CloudHSM CLI to delete the key from the HSMs in the cluster.
All CloudTrail log entries for cryptographic operation with a KMS key in a AWS CloudHSM key store include an `additionalEventData` field with the `customKeyStoreId` and `backingKey`. The value returned in the `backingKeyId` field is the CloudHSM key `id` attribute. We recommend filtering the **key delete** operation by `id` to delete the orphaned key material you identified in your CloudTrail logs.
AWS CloudHSM recognizes the `backingKeyId` value as a hexadecimal value. To filter by `id`, you must prepend the `backingKeyId` with `Ox`. For example, if the `backingKeyId` in your CloudTrail log is `1a2b3c45678abcdef`, you would filter by `0x1a2b3c45678abcdef`.
The following example deletes a key from the HSMs in your cluster. The `backing-key-id` is listed in the CloudTrail log entry. Before running this command, replace the example `backing-key-id` with a valid one from your account.
```
aws-cloudhsm key delete --filter attr.id="0x"
{
"error_code": 0,
"data": {
"message": "Key deleted successfully"
}
}
```
1. Log out and reconnect the AWS CloudHSM key store as described in [How to log out and reconnect](#login-kmsuser-2).
## How to recover deleted key material for a KMS key
If the key material for an AWS KMS key is deleted, the KMS key is unusable and all ciphertext that was encrypted under the KMS key cannot be decrypted. This can happen if the key material for a KMS key in an AWS CloudHSM key store is deleted from the associated AWS CloudHSM cluster. However, it might be possible to recover the key material.
When you create an AWS KMS key (KMS key) in an AWS CloudHSM key store, AWS KMS logs into the associated AWS CloudHSM cluster and creates the key material for the KMS key. It also changes the password to a value that only it knows and remains logged in as long as the AWS CloudHSM key store is connected. Because only the key owner, that is, the CU who created a key, can delete the key, it is unlikely that the key will be deleted from the HSMs accidentally.
However, if the key material for a KMS key is deleted from the HSMs in a cluster, the key state of the KMS key eventually changes to `UNAVAILABLE`. If you attempt to use the KMS key for a cryptographic operation, the operation fails with a `KMSInvalidStateException` exception. Most importantly, any data that was encrypted under the KMS key cannot be decrypted.
Under certain circumstances, you can recover deleted key material by [creating a cluster from a backup](https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-cluster-from-backup.html) that contains the key material. This strategy works only when at least one backup was created while the key existed and before it was deleted.
Use the following process to recover the key material.
1. Find a cluster backup that contains the key material. The backup must also contain all users and keys that you need to support the cluster and its encrypted data.
Use the [DescribeBackups](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DescribeBackups.html) operation to list the backups for a cluster. Then use the backup timestamp to help you select a backup. To limit the output to the cluster that is associated with the AWS CloudHSM key store, use the `Filters` parameter, as shown in the following example.
```
$ aws cloudhsmv2 describe-backups --filters clusterIds=
{
"Backups": [
{
"ClusterId": "cluster-1a23b4cdefg",
"BackupId": "backup-9g87f6edcba",
"CreateTimestamp": 1536667238.328,
"BackupState": "READY"
},
...
]
}
```
1. [Create a cluster from the selected backup](https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-cluster-from-backup.html). Verify that the backup contains the deleted key and other users and keys that the cluster requires.
1. [Disconnect the AWS CloudHSM key store](disconnect-keystore.md) so you can edit its properties.
1. [Edit the cluster ID](update-keystore.md) of the AWS CloudHSM key store. Enter the cluster ID of the cluster that you created from the backup. Because the cluster shares a backup history with the original cluster, the new cluster ID should be valid.
1. [Reconnect the AWS CloudHSM key store](connect-keystore.md).
## How to log in as `kmsuser`
To create and manage the key material in the AWS CloudHSM cluster for your AWS CloudHSM key store, AWS KMS uses the [`kmsuser` crypto user (CU) account](keystore-cloudhsm.md#concept-kmsuser). You [create the `kmsuser` CU account](create-keystore.md#before-keystore) in your cluster and provide its password to AWS KMS when you create your AWS CloudHSM key store.
In general, AWS KMS manages the `kmsuser` account. However, for some tasks, you need to disconnect the AWS CloudHSM key store, log into the cluster as the `kmsuser` CU, and use the [CloudHSM Command Line Interface (CLI)](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli.html).
**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.
This topic explains how to [disconnect your AWS CloudHSM key store and log in](#login-kmsuser-1) as `kmsuser`, run the AWS CloudHSM command line tool, and [log out and reconnect your AWS CloudHSM key store](#login-kmsuser-2).
**Topics**
+ [How to disconnect and log in](#login-kmsuser-1)
+ [How to log out and reconnect](#login-kmsuser-2)
### How to disconnect and log in
Use the following procedure each time to need to log into an associated cluster as the `kmsuser` crypto user.
**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. You can use the AWS KMS console or AWS KMS API.
While your AWS CloudHSM key is connected, AWS KMS is logged in as the `kmsuser`. This prevents you from logging in as `kmsuser` or changing the `kmsuser` password.
For example, this command uses [DisconnectCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_DisconnectCustomKeyStore.html) to disconnect an example key store. Replace the example AWS CloudHSM key store ID with a valid one.
```
$ aws kms disconnect-custom-key-store --custom-key-store-id cks-1234567890abcdef0
```
1. Use the **login** command to login as an admin. Use the procedures described in the [Using CloudHSM CLI](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-getting-started.html#w17aac19c11c13b7) section of the *AWS CloudHSM User Guide*.
```
aws-cloudhsm > login --username admin --role admin
Enter password:
{
"error_code": 0,
"data": {
"username": "admin",
"role": "admin"
}
}
```
1. Use the [https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-user-change-password.html](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-user-change-password.html) command in CloudHSM CLI to change the password of the `kmsuser` account to one that you know. (AWS KMS rotates the password when you connect your AWS CloudHSM key store.) The password must consist of 7-32 alphanumeric characters. It is case-sensitive and cannot contain any special characters.
1. Login as `kmsuser` using the password that you set. For detailed instructions, see the [Using CloudHSM CLI](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-getting-started.html#w17aac19c11c13b7) section of the *AWS CloudHSM User Guide*.
```
aws-cloudhsm > login --username kmsuser --role crypto-user
Enter password:
{
"error_code": 0,
"data": {
"username": "kmsuser",
"role": "crypto-user"
}
}
```
### How to log out and reconnect
Use the following procedure each time you need to log out as the `kmsuser` crypto user and reconnect your key store.
**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. Perform the task, then use the [https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-logout.html](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-logout.html) command in CloudHSM CLI to log out. If you do not log out, attempts to reconnect your AWS CloudHSM key store will fail.
```
aws-cloudhsm logout
{
"error_code": 0,
"data": "Logout successful"
}
```
1. [Edit the `kmsuser` password setting](update-keystore.md) for the custom key store.
This tells AWS KMS the current password for `kmsuser` in the cluster. If you omit this step, AWS KMS will not be able to log into the cluster as `kmsuser`, and all attempts to reconnect your custom key store will fail. You can use the AWS KMS console or the `KeyStorePassword` parameter of the [UpdateCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_UpdateCustomKeyStore.html) operation.
For example, this command tells AWS KMS that the current password is `tempPassword`. Replace the example password with the actual one.
```
$ aws kms update-custom-key-store --custom-key-store-id cks-1234567890abcdef0 --key-store-password tempPassword
```
1. Reconnect the AWS KMS key store to its AWS CloudHSM cluster. Replace the example AWS CloudHSM key store ID with a valid one. During the connection process, AWS KMS changes the `kmsuser` password to a value that only it knows.
The [ConnectCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_ConnectCustomKeyStore.html) operation returns quickly, but the connection process can take an extended period of time. The initial response does not indicate the success of the connection process.
```
$ aws kms connect-custom-key-store --custom-key-store-id cks-1234567890abcdef0
```
1. Use the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) operation to verify that the AWS CloudHSM key store is connected. Replace the example AWS CloudHSM key store ID with a valid one.
In this example, the connection state field shows that the AWS CloudHSM key store is now connected.
```
$ aws kms describe-custom-key-stores --custom-key-store-id cks-1234567890abcdef0
{
"CustomKeyStores": [
"CustomKeyStoreId": "cks-1234567890abcdef0",
"CustomKeyStoreName": "ExampleKeyStore",
"CloudHsmClusterId": "cluster-1a23b4cdefg",
"TrustAnchorCertificate": "",
"CreationDate": "1.499288695918E9",
"ConnectionState": "CONNECTED"
],
}
```