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

Using KMS keys in an Amazon CloudHSM key store

After you create a symmetric encryption KMS key in an Amazon CloudHSM key store, you can use it for the following cryptographic operations:

The operations that generate asymmetric data key pairs, GenerateDataKeyPair and GenerateDataKeyPairWithoutPlaintext, are not supported in custom key stores.

When you use your KMS key in a request, identify the KMS key by its ID or alias; you do not need to specify the Amazon CloudHSM key store or Amazon CloudHSM cluster. The response includes the same fields that are returned for any symmetric encryption KMS key.

However, when you use a KMS key in an Amazon CloudHSM key store, the cryptographic operation is performed entirely within the Amazon CloudHSM cluster that is associated with the Amazon CloudHSM key store. The operation uses the key material in the cluster that is associated with the KMS key that you chose.

To make this possible, the following conditions are required.

  • The key state of the KMS key must be Enabled. To find the key state, use the Status field in the Amazon KMS console or the KeyState field in the DescribeKey response.

  • The Amazon CloudHSM key store must be connected to its Amazon CloudHSM cluster. Its Status in the Amazon KMS console or ConnectionState in the DescribeCustomKeyStores response must be CONNECTED.

  • The Amazon CloudHSM cluster that is associated with the custom key store must contain at least one active HSM. To find the number of active HSMs in the cluster, use the Amazon KMS console, the Amazon CloudHSM console, or the DescribeClusters operation.

  • The Amazon CloudHSM cluster must contain the key material for the KMS key. If the key material was deleted from the cluster, or an HSM was created from a backup that did not include the key material, the cryptographic operation will fail.

If these conditions are not met, the cryptographic operation fails, and Amazon KMS returns a KMSInvalidStateException exception. Typically, you just need to reconnect the Amazon CloudHSM key store. For additional help, see How to fix a failing KMS key.

When using the KMS keys in an Amazon CloudHSM key store, be aware that the KMS keys in each Amazon CloudHSM key store share a custom key store request quota for cryptographic operations. If you exceed the quota, Amazon KMS returns a ThrottlingException. If the Amazon CloudHSM cluster that is associated with the Amazon CloudHSM key store is processing numerous commands, including those unrelated to the Amazon CloudHSM key store, you might get a ThrottlingException at an even lower rate. If you get a ThrottlingException for any request, lower your request rate and try the commands again. For details about the custom key store request quota, see Custom key store request quotas.