Using a custom key store - AWS Key Management Service

Using a custom key store

AWS KMS supports custom key stores backed by AWS CloudHSM clusters. When you create an AWS KMS customer master key (CMK) in a custom key store, AWS KMS generates and stores non-extractable key material for the CMK in an AWS CloudHSM cluster that you own and manage. When you use a CMK in a custom key store, the cryptographic operations 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. When you create CMKs in a custom key store, you can use them just as you would any CMK. For example, you can use the CMKs to generate data keys and encrypt data. You can also use the CMKs in your custom key store with AWS services that support customer managed CMKs.

Do I need a custom key store?

For most users, the default AWS KMS key store, which is protected by FIPS 140-2 validated cryptographic modules, 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:

  • Key material cannot be stored in a shared environment.

  • Key material must be subject to a secondary, independent audit path.

  • The HSMs that generate and store key material must be certified at FIPS 140-2 Level 3.

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 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 customer master keys (CMKs) in an AWS KMS custom key store, you view and manage the CMKs 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 CMKs in a custom key store

You can create symmetric CMKs with key material generated by AWS KMS in your custom key store. Then use the same techniques to view and manage the CMKs in your custom key store that you use for CMKs in the AWS KMS key store. You can control access with IAM and key policies, create tags and aliases, enable and disable the CMKs, and schedule key deletion. You can use the CMKs for cryptographic operations 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 CMKs. While the custom key store is disconnected, AWS KMS cannot access it, and users cannot use the CMKs 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 a custom key store, you use features of AWS KMS and AWS CloudHSM.

  1. Start in AWS CloudHSM. Create an active AWS CloudHSM cluster 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 in that cluster for AWS KMS.

  2. In AWS KMS, create a custom key store 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.

  3. When you're ready to use your custom key store, connect it to its associated AWS CloudHSM cluster. 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.

  4. Now, you can create symmetric CMKs in your custom key store. Just specify the custom key store when you create the CMK.

If you get stuck at any point, you can find help in the Troubleshooting a custom key store 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.


There are no resource quotas for the number of custom key stores in an AWS account or Region. However, there are AWS CloudHSM quotas, such as a quota on the number of AWS CloudHSM clusters in each AWS account and Region, and AWS KMS quotas on the use of CMKs in a custom key store.


AWS KMS supports custom key stores in all AWS Regions where both AWS KMS and AWS CloudHSM are available. For a list of AWS Regions that each service supports, see AWS Key Management Service Endpoints and Quotas and AWS CloudHSM Endpoints and Quotas in the Amazon Web Services General Reference.

Unsupported features

AWS KMS does not support the following AWS KMS features in custom key stores.