KMS keys in external key stores

To create, view, manage, use, and schedule deletion of the KMS keys in an external key store, you use procedures that are very similar to those you use for other KMS keys. However, when you create a KMS key in an external key store, you specify an external key store and an external key. When you use a KMS key in an external key store, encryption and decryption operations are performed by your external key manager using the specified external key.

AWS KMS cannot create, view, update, or delete any cryptographic keys in your external key manager. AWS KMS never directly accesses your external key manager or any external key. All requests for cryptographic operations are mediated by your external key store proxy. To use a KMS key in an external key store, the external key store that hosts the KMS key must be connected to its external key store proxy.

Supported features

In addition to the procedures discussed in this section, you can do the following with KMS keys in an external key store:

• Use key policies, IAM policies, and grants to control access to the KMS keys.

• Enable and disable the KMS keys. These actions do not affect the external key in your external key manager.

• Assign tags and create aliases, and use attribute-based access control (ABAC) to authorize access to the KMS keys.

• Use the KMS keys to perform the following cryptographic operations:

  • Encrypt

  • Decrypt

  • GenerateDataKey

  • GenerateDataKeyWithoutPlaintext

  • ReEncrypt

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

• Use the KMS keys with AWS services that integrate with AWS KMS and support customer managed keys.

Unsupported features

• External key stores support only symmetric encryption KMS keys. You cannot create HMAC KMS keys or asymmetric KMS keys in an external key store.

• GenerateDataKeyPair and GenerateDataKeyPairWithoutPlaintext are not supported on KMS keys in an external key store.

• You cannot use an AWS::KMS::Key AWS CloudFormation template to create an external key store or a KMS key in an external key store.

• Multi-Region keys are not supported in an external key store.

• KMS keys with imported key material are not supported in an external key store.

• Automatic key rotation is not supported for KMS keys in an external key store.

Using KMS keys in an external key store

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, AWS KMS uses double encryption. Data is first encrypted in AWS KMS using AWS 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 AWS KMS using the AWS 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 AWS 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 AWS 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 AWS 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 Connect and disconnect external key stores.

• 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 AWS 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, AWS KMS returns a ThrottlingException. For details about the custom key store request quota, see Custom key store request quotas.

Learn more

• To learn more about external key stores, see External key stores.

• To learn more about key material in external key stores, see External key.

• To create KMS keys in an external key store, see Create a KMS key in external key stores.

• To identify and view KMS keys in an external key store, see Identify KMS keys in external key stores.

• To learn about special considerations for deleting KMS keys in an external key store, see Deleting KMS keys from an external key store.