AWS Key Management Service
Developer Guide

The AWS Documentation website is getting a new look!
Try it now and let us know what you think. Switch to the new look >>

You can return to the original look by selecting English in the language selector above.

Using CMKs in a Custom Key Store

After you create CMKs in a custom key store, you can use them for cryptographic operations — Encrypt, Decrypt, GenerateDataKey, GenerateDataKeyWithoutPlaintext, and ReEncrypt — just as you would for any CMK. In the request, you identify the CMK by its ID or alias; you do not need to specify the custom key store or AWS CloudHSM cluster. The response includes the same fields that are returned for any CMK.

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

To make this possible, the following conditions are required.

  • The key state of the CMK must be Enabled. To find the key state, use the Status field in the AWS Management Console or the KeyState field in the DescribeKey response.

  • The custom key store must be connected to its AWS CloudHSM cluster. Its Status in the AWS Management Console or ConnectionState in the DescribeCustomKeyStores response must be CONNECTED.

  • The AWS 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 AWS KMS console, the AWS CloudHSM console, or the DescribeClusters operation.

  • The AWS CloudHSM cluster must contain the key material for the CMK. 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 AWS KMS returns a KMSInvalidStateException exception. Typically, you just need to reconnect the custom key store. For additional help, see How to Fix a Failing CMK.

AWS KMS limits the rate of cryptographic operations that use CMKs in custom key stores. If you exceed this rate, AWS KMS returns a ThrottlingException. In addition, if the AWS CloudHSM cluster that is associated with the custom key store is processing numerous commands, including those unrelated to the custom key store, you might get a ThrottlingException at a rate lower than the published rate. If you get a ThrottlingException for any request, lower your request rate and try the commands again. For details about the throttling limit for cryptographic operations in custom key stores, see Custom Key Store Limits.