AWS CloudHSM key stores

An AWS CloudHSM key store is a custom key store backed by a AWS CloudHSM cluster. 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 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-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:

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 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.

You can create symmetric encryption KMS keys 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 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.

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.

Quotas

AWS KMS allows up to 10 custom key stores in each AWS account and Region, including both AWS CloudHSM key stores and external key stores, 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.

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. For information about the cost of AWS CloudHSM clusters and HSMs, see AWS 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.

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 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 Level 3.

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 your AWS CloudHSM key store, edit its properties, and connect and disconnect it from its associated AWS CloudHSM cluster. If you need to delete an AWS CloudHSM key store, 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 (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 in your AWS CloudHSM cluster using the user create command in CloudHSM CLI. Then when you create the AWS CloudHSM key store, you provide the kmsuser account password to AWS KMS. When you connect the custom key store, 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 that kmsuser owns. If necessary, you can disconnect the custom key store, change the kmsuser password, log into the cluster 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.

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, 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 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 that support the use of customer managed keys However, you cannot enable automatic key rotation or import key material into a KMS key in an AWS CloudHSM key store.

You also use the same process to schedule deletion 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 from the cluster and its backups.