Using KMS keys in an external 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 external key store

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

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

An encryption context is supported for all cryptographic operations with KMS keys in an external key store. As always, using an encryption context is a security best practice that Amazon KMS recommends.

When you use your KMS key in a request, identify the KMS key by its key ID, key ARN, alias, or alias ARN. You do not need to specify the external key store. The response includes the same fields that are returned for any symmetric encryption KMS key. However, when you use a KMS key in an external key store, encryption and decryption operations are performed by your external key manager using the external key that is associated with the KMS key.

To ensure that ciphertext encrypted by a KMS key in an external key store is at least as secure as any ciphertext encrypted by a standard KMS key, Amazon KMS uses double encryption. Data is first encrypted in Amazon KMS using Amazon KMS key material. Then it is encrypted by your external key manager using the external key for the KMS key. To decrypt double-encrypted ciphertext, the ciphertext is first decrypted by your external key manager using the external key for the KMS key. Then it is decrypted in Amazon KMS using the Amazon KMS key material for the KMS key.

To make this possible, the following conditions are required.

  • The key state of the KMS key must be Enabled. To find the key state, see the Status field for customer managed keys the Amazon KMS console or the KeyState field in the DescribeKey response.

  • The external key store that hosts the KMS key must be connected to its external key store proxy, that is, the connection state of the external key store must be CONNECTED.

    You can view the connection state on the External key stores page in the Amazon KMS console or in the DescribeCustomKeyStores response. The connection state of the external key store is also displayed on the detail page for the KMS key in the Amazon KMS console. On the detail page, choose the Cryptographic configuration tab and see the Connection state field in the Custom key store section.

    If the connection state is DISCONNECTED, you must first connect it. If the connection state is FAILED, you must resolve the problem, disconnect the external key store, and then connect it. For instructions, see Connecting and disconnecting an external key store..

  • The external key store proxy must be able to find the external key.

  • The external key must be enabled and it must perform encryption and decryption.

    The status of the external key is independent of and not affected by changes in the key state of the KMS key, including enabling and disabling the KMS key. Similarly, disabling or deleting the external key doesn't change the key state of the KMS key, but cryptographic operations using the associated KMS key will fail.

If these conditions are not met, the cryptographic operation fails, and Amazon KMS returns a KMSInvalidStateException exception. You might need to reconnect the external key store or use your external key manager tools to reconfigure or repair your external key. For additional help, see Troubleshooting external key stores.

When using the KMS keys in an external key store, be aware that the KMS keys in each external key store share a custom key store request quota for cryptographic operations. If you exceed the quota, Amazon KMS returns a ThrottlingException. For details about the custom key store request quota, see Custom key store request quotas.