# Key stores
A *key store* is a secure location for storing and using cryptographic keys. The default key store in AWS KMS also supports methods for generating and managing the keys that it stores. By default, the cryptographic key material for the AWS KMS keys that you create in AWS KMS is generated in and protected by hardware security modules (HSMs) that are [FIPS 140-3 Cryptographic Module Validation Program](https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/4884). Key material for your KMS keys never leave the HSMs unencrypted.
AWS KMS supports several types of key stores to protect your key material when using AWS KMS to create and manage your encryption keys. All of the key store options supplied by AWS KMS are continually validated under FIPS 140-3 at Security Level 3 and are designed to prevent anyone, including AWS operators, from accessing your plaintext keys or using them without your permission.
## AWS KMS standard key store
By default, a KMS key is created using the standard AWS KMS HSM. This HSM type can be thought of as a multi-tenant fleet of HSMs that allows for the most scalable, lowest cost and easiest key store to manage from your perspective. If you are creating a KMS key for use within one or more AWS services so that service can encrypt your data on your behalf, you will create a symmetric key. If you are using a KMS key for your own application design, you may choose to create a symmetric encryption key, asymmetric key, or HMAC key.
In the standard key store option, AWS KMS creates your key, then encrypts it under keys that the service manages internally. Multiple copies of encrypted versions of your keys are then stored in systems that are designed for durability. Generating and protecting your key material in the standard key store type lets you take full advantage of the scalability, availability, and durability of AWS KMS with the lowest operational burden and cost of the AWS key stores.
## AWS KMS standard key store with imported key material
Instead of asking AWS KMS to both generate and store the only copies of a given key, you can choose to import key material into AWS KMS, allowing you to generate your own 256-bit symmetric encryption key, RSA or elliptic curve (ECC) key, or Hash-Based Message Authentication Code (HMAC) key, and apply it to a KMS key identifier (keyId). This is sometimes referred to as *bring your own key* (BYOK). Imported key material from your local key management system must be protected by using a public key issued by AWS KMS, a supported cryptographic wrapping algorithm, and a time-based import token provided by AWS KMS. This process verifies that your encrypted, imported key can only ever be decrypted by an AWS KMS HSM once it has left your environment.
Imported key material may be useful if you have specific requirements around the system that generates keys, or want a copy of your key outside of AWS as a backup. Note that you are responsible for an imported key material's overall availability and durability. While AWS KMS has a copy of your imported key and will keep highly available while you need it, imported keys offer a special API for deletion – DeleteImportedKeyMaterial. This API will immediately delete all copies of the imported key material that AWS KMS has, with no option for AWS to recover the key. In addition, you can set an expiration time on an imported key, after which the key will be unusable. To make the key useful again in AWS KMS, you will have to reimport the key material and assign it to the same keyId. This deletion action for imported keys is different than standard keys that AWS KMS generates and stored for you on your behalf. In the standard case, the key deletion process has a mandatory waiting period where a key scheduled for deletion is first blocked from usage. This action allows you to see access denied errors in logs from any application or AWS service that might need that key to access data. If you see such access requests, you can choose to cancel the scheduled deletion and re-enable the key. After a configurable waiting period (between 7 and 30 days), only then will KMS actually delete the key material, the keyID and all metadata associated with the key. For more information about availability and durability, see [Protecting imported key material](import-keys-protect.md) in the *AWS KMS Developer Guide*.
There are some additional limitations with imported key material to be aware of. Since AWS KMS cannot generate new key material, there is no way to configure automatic rotation of imported keys. You will need to create a new KMS key with a new keyId, then import new key material to achieve an effective rotation. Also, ciphertexts created in AWS KMS under an imported symmetric key cannot be easily decrypted using your local copy of the key outside of AWS. This is because the authenticated encryption format used by AWS KMS appends additional metadata to the ciphertext to provide assurances during the decryption operation that the ciphertext was created by the expected KMS key under a previous encrypt operation. Most external cryptographic systems won’t understand how to parse this metadata to gain access to the raw ciphertext to be able to use their copy of a symmetric key. Ciphertexts created under imported asymmetric keys (e.g. RSA or ECC) can be used outside of AWS KMS with the matching (public or private) portion of the key because there is no additional metadata added by AWS KMS to the ciphertext.
## AWS KMS custom key stores
However, if you require even more control of the HSMs, you can create a custom key store.
A *custom key store* is a key store within AWS KMS that is backed by a key manager outside of AWS KMS, which you own and manage. Custom key stores combine the convenient and comprehensive key management interface of AWS KMS with the ability to own and control the key material and cryptographic operations. When you use a KMS key in a custom key store, the cryptographic operations are performed by your key manager using your cryptographic keys. As a result, you assume more responsibility for the availability and durability of cryptographic keys, and for the operation of the HSMs.
Owning your HSMs may be useful to help meet certain regulatory requirements that don’t yet allow multi-tenant web services like the standard KMS key store to hold your cryptographic keys. Custom key stores are not more secure than KMS key store that use AWS-managed HSMs, but they have different (and higher) management and cost implications. As a result, you assume more responsibility for the availability and durability of cryptographic keys and for the operation of the HSMs. Regardless of whether you use the standard key store with AWS KMS HSMs or a custom key store, the service is designed so that no one, including AWS employees, can retrieve your plaintext keys or use them without your permission. AWS KMS supports two types of custom key stores, AWS CloudHSM key stores and external key stores.
**Unsupported features**
AWS KMS does not support the following features in custom key stores.
+ [Asymmetric KMS keys](symmetric-asymmetric.md)
+ [HMAC KMS keys](hmac.md)
+ [KMS keys with imported key material](importing-keys.md)
+ [Automatic key rotation](rotate-keys.md)
+ [Multi-Region keys](multi-region-keys-overview.md)
### AWS CloudHSM key store
You can create a KMS key in an [AWS CloudHSM](https://aws.amazon.com/kms/pricing/) key store, where root user keys are generated, stored and used in a AWS CloudHSM cluster that you own and manage. Requests to AWS KMS to use a key for some cryptographic operation are forwarded to your AWS CloudHSM cluster to perform the operation. While a AWS CloudHSM cluster is hosted by AWS, it is a single-tenant solution that is directly managed and operated by you. You own much of the availability and performance of KMS keys in a AWS CloudHSM cluster. To see if a AWS CloudHSM custom key store is a good fit for your requirements, read [Are AWS KMS custom key stores right for you? ](https://aws.amazon.com/blogs/security/are-kms-custom-key-stores-right-for-you/) on the AWS security blog.
### External key store
You can configure AWS KMS to use an External Key Store (XKS), where root user keys are generated, stored and used in a key management system outside the AWS Cloud. Requests to AWS KMS to use a key for some cryptographic operation are forwarded to your externally hosted system to perform the operation. Specifically, requests are forwarded to an XKS Proxy in your network, which then forwards the request to whichever cryptographic system you use. The XKS Proxy is an open-source specification that anyone can integrate with. Many commercial key management vendors support the XKS Proxy specification. Because an External Key Store is hosted by you or some third party, you own all of the availability, durability, and performance of the keys in the system. To see if an External Key Store is a good fit for your requirements, read [Announcing AWS KMS External Key Store (XKS) ](https://aws.amazon.com/blogs/aws/announcing-aws-kms-external-key-store-xks/) on the AWS News blog.
# AWS CloudHSM key stores
An AWS CloudHSM key store is a [custom key store](key-store-overview.md#custom-key-store-overview) backed by a [AWS CloudHSM cluster](https://docs.aws.amazon.com/cloudhsm/latest/userguide/). 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](manage-cmk-keystore.md#use-cmk-keystore) 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-3 validated cryptographic modules](https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/4884), 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:
+ You have keys that are explicitly required to be protected in a single tenant HSM or in an HSM that you have direct control over.
+ You need the ability to immediately remove key material from AWS KMS.
+ You need to be able to audit all use of your keys independently of AWS KMS or AWS CloudTrail.
**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](#concept-kmsuser) 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.
![\[Managing KMS keys in a custom key store\]](http://docs.aws.amazon.com/kms/latest/developerguide/images/kms-hsm-view.png)
You can [create symmetric encryption KMS keys](create-cmk-keystore.md) 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](manage-cmk-keystore.md#use-cmk-keystore) 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.
1. Start in AWS CloudHSM. [Create an active AWS CloudHSM cluster](https://docs.aws.amazon.com/cloudhsm/latest/userguide/getting-started.html) or select an existing cluster. The cluster must have at least two active HSMs in different Availability Zones. Then create a [dedicated crypto user (CU) account](#concept-kmsuser) in that cluster for AWS KMS.
1. In AWS KMS, [create a custom key store](create-keystore.md) that is associated with your selected AWS CloudHSM cluster. AWS KMS provides a complete management interface that lets you create, view, edit, and delete your custom key stores.
1. When you're ready to use your custom key store, [connect it to its associated AWS CloudHSM cluster](connect-keystore.md). AWS KMS creates the network infrastructure that it needs to support the connection. It then logs in to the cluster using the dedicated crypto user account credentials so it can generate and manage key material in the cluster.
1. Now, you can [create symmetric encryption KMS keys in your custom key store](create-cmk-keystore.md). Just specify the custom key store when you create the KMS key.
If you get stuck at any point, you can find help in the [Troubleshooting a custom key store](fix-keystore.md) 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](https://repost.aws/tags/TAMC3vcPOPTF-rPAHZVRj1PQ/aws-key-management-service).
**Quotas**
AWS KMS allows up to [10 custom key stores](resource-limits.md) in each AWS account and Region, including both [AWS CloudHSM key stores](https://docs.aws.amazon.com/kms/latest/developerguide/keystore-cloudhsm.html) and [external key stores](https://docs.aws.amazon.com/kms/latest/developerguide/keystore-external.html), 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](requests-per-second.md#rps-key-stores).
**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](https://aws.amazon.com/kms/pricing/). For information about the cost of AWS CloudHSM clusters and HSMs, see [AWS CloudHSM Pricing](https://aws.amazon.com/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.
+ [Asymmetric KMS keys](symmetric-asymmetric.md)
+ [HMAC KMS keys](hmac.md)
+ [KMS keys with imported key material](importing-keys.md)
+ [Automatic key rotation](rotate-keys.md)
+ [Multi-Region keys](multi-region-keys-overview.md)
## 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](key-store-overview.md#custom-key-store-overview) 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 or FIPS 140-3Level 3](https://docs.aws.amazon.com/cloudhsm/latest/userguide/compliance.html).
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](view-keystore.md) your AWS CloudHSM key store, [edit its properties](update-keystore.md), and [connect](connect-keystore.md) and [disconnect](disconnect-keystore.md) it from its associated AWS CloudHSM cluster. If you need to [delete an AWS CloudHSM key store](delete-keystore.md#delete-keystore-console), 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](https://docs.aws.amazon.com/cloudhsm/latest/userguide/hsm-users.html#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](create-keystore.md#before-keystore) in your AWS CloudHSM cluster using the [https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-user-cloudhsm-cli.html](https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-user-cloudhsm-cli.html) command in CloudHSM CLI. Then when you [create the AWS CloudHSM key store](create-keystore.md), you provide the `kmsuser` account password to AWS KMS. When you [connect the custom key store](connect-keystore.md), 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](find-key-material.md) that `kmsuser` owns. If necessary, you can [disconnect the custom key store](disconnect-keystore.md), change the `kmsuser` password, [log into the cluster as `kmsuser`](fix-keystore.md#fix-login-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](create-keystore.md#before-keystore).
### 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](create-cmk-keystore.md), 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](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html) 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](service-integration.md) that support the use of customer managed keys However, you cannot enable [automatic key rotation](rotate-keys.md) or [import key material](importing-keys.md) into a KMS key in an AWS CloudHSM key store.
You also use the same process to [schedule deletion](deleting-keys.md#delete-cmk-keystore) 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](fix-keystore.md#fix-keystore-orphaned-key) from the cluster and its backups.
# Control access to your AWS CloudHSM key store
You use IAM policies to control access to your AWS CloudHSM key store and your AWS CloudHSM cluster. You can use key policies, IAM policies, and grants to control access to the AWS KMS keys in your AWS CloudHSM key store. We recommend that you provide users, groups, and roles only the permissions that they require for the tasks that they are likely to perform.
To support your AWS CloudHSM key stores, AWS KMS needs permission to get information about your AWS CloudHSM clusters. It also needs permission to create the network infrastructure that connects your AWS CloudHSM key store to its AWS CloudHSM cluster. To get these permissions, AWS KMS creates the **AWSServiceRoleForKeyManagementServiceCustomKeyStores** service-linked role in your AWS account. For more information, see [Authorizing AWS KMS to manage AWS CloudHSM and Amazon EC2 resources](authorize-kms.md).
When designing your AWS CloudHSM key store, be sure that the principals who use and manage it have only the permissions that they require. The following list describes the minimum permissions required for AWS CloudHSM key store managers and users.
+ Principals who create and manage your AWS CloudHSM key store require the following permission to use the AWS CloudHSM key store API operations.
+ `cloudhsm:DescribeClusters`
+ `kms:CreateCustomKeyStore`
+ `kms:ConnectCustomKeyStore`
+ `kms:DeleteCustomKeyStore`
+ `kms:DescribeCustomKeyStores`
+ `kms:DisconnectCustomKeyStore`
+ `kms:UpdateCustomKeyStore`
+ `iam:CreateServiceLinkedRole`
+ Principals who create and manage the AWS CloudHSM cluster that is associated with your AWS CloudHSM key store need permission to create and initialize an AWS CloudHSM cluster. This includes permission to create or use an Amazon Virtual Private Cloud (VPC), create subnets, and create an Amazon EC2 instance. They might also need to create and delete HSMs, and manage backups. For lists of the required permissions, see [Identity and access management for AWS CloudHSM](https://docs.aws.amazon.com/cloudhsm/latest/userguide/identity-access-management.html) in the *AWS CloudHSM User Guide*.
+ Principals who create and manage AWS KMS keys in your AWS CloudHSM key store require [the same permissions](create-keys.md#create-key-permissions) as those who create and manage any KMS key in AWS KMS. The [default key policy](key-policy-default.md) for a KMS key in an AWS CloudHSM key store is identical to the default key policy for KMS keys in AWS KMS. [Attribute-based access control](abac.md) (ABAC), which uses tags and aliases to control access to KMS keys, is also effective on KMS keys in AWS CloudHSM key stores.
+ Principals who use the KMS keys in your AWS CloudHSM key store for [cryptographic operations](manage-cmk-keystore.md#use-cmk-keystore) need permission to perform the cryptographic operation with the KMS key, such as [kms:Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html). You can provide these permissions in a key policy, IAM policy. But, they do not need any additional permissions to use a KMS key in an AWS CloudHSM key store.
# Create an AWS CloudHSM key store
You can create one or several AWS CloudHSM key stores in your account. Each AWS CloudHSM key store is associated with one AWS CloudHSM cluster in the same AWS account and Region. Before you create your AWS CloudHSM key store, you need to [assemble the prerequisites](#before-keystore). Then, before you can use your AWS CloudHSM key store, you must [connect it](connect-keystore.md) to its AWS CloudHSM cluster.
**Notes**
KMS cannot communicate over IPv6 with AWS CloudHSM key stores.
If you try to create an AWS CloudHSM key store with all of the same property values as an existing *disconnected* AWS CloudHSM key store, AWS KMS does not create a new AWS CloudHSM key store, and it does not throw an exception or display an error. Instead, AWS KMS recognizes the duplicate as the likely consequence of a retry, and it returns the ID of the existing AWS CloudHSM key store.
You do not have to connect your AWS CloudHSM key store immediately. You can leave it in a disconnected state until you are ready to use it. However, to verify that it is configured properly, you might want to [connect it](connect-keystore.md),[ view its connection state](view-keystore.md), and then [disconnect it](disconnect-keystore.md).
**Topics**
+ [
## Assemble the prerequisites
](#before-keystore)
+ [
## Create a new AWS CloudHSM key store
](#create-hsm-keystore)
## Assemble the prerequisites
Each AWS CloudHSM key store is backed by an AWS CloudHSM cluster. To create an AWS CloudHSM key store, you must specify an active AWS CloudHSM cluster that is not already associated with another key store. You also need to create a dedicated crypto user (CU) in the cluster's HSMs that AWS KMS can use to create and manage keys on your behalf.
Before you create an AWS CloudHSM key store, do the following:
**Select an AWS CloudHSM cluster**
Every AWS CloudHSM key store is [associated with exactly one AWS CloudHSM cluster](keystore-cloudhsm.md#concept-cluster). When you create AWS KMS keys in your AWS CloudHSM key store, AWS KMS creates the KMS key metadata, such as an ID and Amazon Resource Name (ARN) in AWS KMS. It then creates the key material in the HSMs of the associated cluster. You can [create a new AWS CloudHSM](https://docs.aws.amazon.com/cloudhsm/latest/userguide/getting-started.html) cluster or use an existing one. AWS KMS does not require exclusive access to the cluster.
The AWS CloudHSM cluster that you select is permanently associated with the AWS CloudHSM key store. After you create the AWS CloudHSM key store, you can [change the cluster ID](update-keystore.md) of the associated cluster, but the cluster that you specify must share a backup history with the original cluster. To use an unrelated cluster, you need to create a new AWS CloudHSM key store.
The AWS CloudHSM cluster that you select must have the following characteristics:
+ **The cluster must be active**.
You must create the cluster, initialize it, install the AWS CloudHSM client software for your platform, and then activate the cluster. For detailed instructions, see [Getting started with AWS CloudHSM](https://docs.aws.amazon.com/cloudhsm/latest/userguide/getting-started.html) in the *AWS CloudHSM User Guide*.
+ **Mutual TLS (mTLS) is not enabled.**
KMS does not support mTLS for clusters. This setting must not be enabled.
+ **The cluster must be in the same account and Region** as the AWS CloudHSM key store. You cannot associate an AWS CloudHSM key store in one Region with a cluster in a different Region. To create a key infrastructure in multiple Regions, you must create AWS CloudHSM key stores and clusters in each Region.
+ **The cluster cannot be associated with another custom key store** in the same account and Region. Each AWS CloudHSM key store in the account and Region must be associated with a different AWS CloudHSM cluster. You cannot specify a cluster that is already associated with a custom key store or a cluster that shares a backup history with an associated cluster. Clusters that share a backup history have the same cluster certificate. To view the cluster certificate of a cluster, use the AWS CloudHSM console or the [DescribeClusters](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DescribeClusters.html) operation.
If you [back up an AWS CloudHSM cluster to a different Region](https://docs.aws.amazon.com/cloudhsm/latest/userguide/copy-backup-to-region.html), it is considered to be different cluster, and you can associate the backup with a custom key store in its Region. However, KMS keys in the two custom key stores are not interoperable, even if they have the same backing key. AWS KMS binds metadata to the ciphertext so it can be decrypted only by the KMS key that encrypted it.
+ The cluster must be configured with [private subnets](https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-subnets.html) in **at least two Availability Zones** in the Region. Because AWS CloudHSM is not supported in all Availability Zones, we recommend that you create private subnets in all Availability Zones in the region. You cannot reconfigure the subnets for an existing cluster, but you can [create a cluster from a backup](https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-cluster-from-backup.html) with different subnets in the cluster configuration.
**Important**
After you create your AWS CloudHSM key store, do not delete any of the private subnets configured for its AWS CloudHSM cluster. If AWS KMS cannot find all of the subnets in the cluster configuration, attempts to [connect to the custom key store](connect-keystore.md) fail with a `SUBNET_NOT_FOUND` connection error state. For details, see [How to fix a connection failure](fix-keystore.md#fix-keystore-failed).
+ The [security group for the cluster](https://docs.aws.amazon.com/cloudhsm/latest/userguide/configure-sg.html) (`cloudhsm-cluster--sg`) must include inbound rules and outbound rules that allow TCP traffic over IPv4, on ports 2223-2225. The **Source** in the inbound rules and the **Destination** in the outbound rules must match the security group ID. These rules are set by default when you create the cluster. Do not delete or change them.
+ **The cluster must contain at least two active HSMs** in different Availability Zones. To verify the number of HSMs, use the AWS CloudHSM console or the [DescribeClusters](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DescribeClusters.html) operation. If necessary, you can [add an HSM](https://docs.aws.amazon.com/cloudhsm/latest/userguide/add-remove-hsm.html#add-hsm).
**Find the trust anchor certificate**
When you create a custom key store, you must upload the trust anchor certificate for the AWS CloudHSM cluster to AWS KMS. AWS KMS needs the trust anchor certificate to connect the AWS CloudHSM key store to its associated AWS CloudHSM cluster.
Every active AWS CloudHSM cluster has a *trust anchor certificate*. When you [initialize the cluster](https://docs.aws.amazon.com/cloudhsm/latest/userguide/initialize-cluster.html#sign-csr), you generate this certificate, save it in the `customerCA.crt` file, and copy it to hosts that connect to the cluster.
**Create the `kmsuser` crypto user for AWS KMS**
To administer your AWS CloudHSM key store, AWS KMS logs into the [`kmsuser` crypto user](keystore-cloudhsm.md#concept-kmsuser) (CU) account in the selected cluster. Before you create your AWS CloudHSM key store, you must create the `kmsuser` CU. Then when you create your AWS CloudHSM key store, you provide the password for `kmsuser` to AWS KMS. Whenever you connect the AWS CloudHSM key store to its associated AWS CloudHSM cluster, AWS KMS logs in as the `kmsuser` and rotates the `kmsuser` password
Do not specify the `2FA` option when you create the `kmsuser` CU. If you do, AWS KMS cannot log in and your AWS CloudHSM key store cannot be connected to this AWS CloudHSM cluster. Once you specify 2FA, you cannot undo it. Instead, you must delete the CU and recreate it.
**Notes**
The following procedures use the AWS CloudHSM Client SDK 5 command line tool, [CloudHSM CLI](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli.html). The CloudHSM CLI replaces `key-handle` with `key-reference`.
On January 1, 2025, AWS CloudHSM will end support for the Client SDK 3 command line tools, the CloudHSM Management Utility (CMU) and the Key Management Utility (KMU). For more information on the differences between the Client SDK 3 command line tools and the Client SDK 5 command line tool, see [Migrate from Client SDK 3 CMU and KMU to Client SDK 5 CloudHSM CLI](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-migrate-from-kmu-cmu.html) in the *AWS CloudHSM User Guide*.
1. Follow the getting started procedures as described in the [Getting started with CloudHSM Command Line Interface (CLI)](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-getting-started.html) topic of the *AWS CloudHSM User Guide*.
1. Use the [https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-user-cloudhsm-cli.html](https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-user-cloudhsm-cli.html) command to create a CU named `kmsuser`.
The password must consist of 7-32 alphanumeric characters. It is case-sensitive and cannot contain any special characters.
The following example command creates a `kmsuser` CU.
```
aws-cloudhsm > user create --username kmsuser --role crypto-user
Enter password:
Confirm password:
{
"error_code": 0,
"data": {
"username": "kmsuser",
"role": "crypto-user"
}
}
```
## Create a new AWS CloudHSM key store
After [assembling the prerequisites](#before-keystore), you can create a new AWS CloudHSM key store in the AWS KMS console or by using the [CreateCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateCustomKeyStore.html) operation.
### Using the AWS KMS console
When you create an AWS CloudHSM key store in the AWS Management Console, you can add and create the [prerequisites](#before-keystore) as part of your workflow. However, the process is quicker when you have assembled them in advance.
1. Sign in to the AWS Management Console and open the AWS Key Management Service (AWS KMS) console at [https://console.aws.amazon.com/kms](https://console.aws.amazon.com/kms).
1. To change the AWS Region, use the Region selector in the upper-right corner of the page.
1. In the navigation pane, choose **Custom key stores**, **AWS CloudHSM key stores**.
1. Choose **Create a key store**.
1. Enter a friendly name for the custom key store. The name must be unique among all custom key stores in your account.
**Important**
Do not include confidential or sensitive information in this field. This field may be displayed in plaintext in CloudTrail logs and other output.
1. Select [an AWS CloudHSM cluster](keystore-cloudhsm.md#concept-cluster) for the AWS CloudHSM key store. Or, to create a new AWS CloudHSM cluster, choose the **Create an AWS CloudHSM cluster** link.
The menu displays the AWS CloudHSM clusters in your account and region that are not already associated with an AWS CloudHSM key store. The cluster must [fulfill the requirements](#before-keystore) for association with a custom key store.
1. Choose **Choose file**, and then upload the trust anchor certificate for the AWS CloudHSM cluster that you chose. This is the `customerCA.crt` file that you created when you [initialized the cluster](https://docs.aws.amazon.com/cloudhsm/latest/userguide/initialize-cluster.html#sign-csr).
1. Enter the password of [the `kmsuser` crypto user](keystore-cloudhsm.md#concept-kmsuser) (CU) that you created in the selected cluster.
1. Choose **Create**.
When the procedure is successful, the new AWS CloudHSM key store appears in the list of AWS CloudHSM key stores in the account and Region. If it is unsuccessful, an error message appears that describes the problem and provides help on how to fix it. If you need more help, see [Troubleshooting a custom key store](fix-keystore.md).
If you try to create an AWS CloudHSM key store with all of the same property values as an existing *disconnected* AWS CloudHSM key store, AWS KMS does not create a new AWS CloudHSM key store, and it does not throw an exception or display an error. Instead, AWS KMS recognizes the duplicate as the likely consequence of a retry, and it returns the ID of the existing AWS CloudHSM key store.
**Next**: New AWS CloudHSM key stores are not automatically connected. Before you can create AWS KMS keys in the AWS CloudHSM key store, you must [connect the custom key store](connect-keystore.md) to its associated AWS CloudHSM cluster.
### Using the AWS KMS API
You can use the [CreateCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateCustomKeyStore.html) operation to create a new AWS CloudHSM key store that is associated with an AWS CloudHSM cluster in the account and Region. These examples use the AWS Command Line Interface (AWS CLI), but you can use any supported programming language.
The `CreateCustomKeyStore` operation requires the following parameter values.
+ CustomKeyStoreName – A friendly name for the custom key store that is unique in the account.
**Important**
Do not include confidential or sensitive information in this field. This field may be displayed in plaintext in CloudTrail logs and other output.
+ CloudHsmClusterId – The cluster ID of an AWS CloudHSM cluster that [fulfills the requirements](#before-keystore) for an AWS CloudHSM key store.
+ KeyStorePassword – The password of `kmsuser` CU account in the specified cluster.
+ TrustAnchorCertificate – The content of the `customerCA.crt` file that you created when you [initialized the cluster](https://docs.aws.amazon.com/cloudhsm/latest/userguide/initialize-cluster.html).
The following example uses a fictitious cluster ID. Before running the command, replace it with a valid cluster ID.
```
$ aws kms create-custom-key-store
--custom-key-store-name ExampleCloudHSMKeyStore \
--cloud-hsm-cluster-id cluster-1a23b4cdefg \
--key-store-password kmsPswd \
--trust-anchor-certificate
```
If you are using the AWS CLI, you can specify the trust anchor certificate file, instead of its contents. In the following example, the `customerCA.crt` file is in the root directory.
```
$ aws kms create-custom-key-store
--custom-key-store-name ExampleCloudHSMKeyStore \
--cloud-hsm-cluster-id cluster-1a23b4cdefg \
--key-store-password kmsPswd \
--trust-anchor-certificate file://customerCA.crt
```
When the operation is successful, `CreateCustomKeyStore` returns the custom key store ID, as shown in the following example response.
```
{
"CustomKeyStoreId": cks-1234567890abcdef0
}
```
If the operation fails, correct the error indicated by the exception, and try again. For additional help, see [Troubleshooting a custom key store](fix-keystore.md).
If you try to create an AWS CloudHSM key store with all of the same property values as an existing *disconnected* AWS CloudHSM key store, AWS KMS does not create a new AWS CloudHSM key store, and it does not throw an exception or display an error. Instead, AWS KMS recognizes the duplicate as the likely consequence of a retry, and it returns the ID of the existing AWS CloudHSM key store.
**Next**: To use the AWS CloudHSM key store, [connect it to its AWS CloudHSM cluster](connect-keystore.md).
# View an AWS CloudHSM key store
You can view the AWS CloudHSM key stores in each account and Region by using the AWS KMS console or the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) operation.
## Using the AWS KMS console
When you view the AWS CloudHSM key stores in the AWS Management Console, you can see the following:
+ The custom key store name and ID
+ The ID of associated AWS CloudHSM cluster
+ The number of HSMs in the cluster
+ The current connection state
A connection state (**Status**) value of **Disconnected** indicates that the custom key store is new and has never been connected, or it was intentionally [disconnected from its AWS CloudHSM cluster](disconnect-keystore.md). However, if your attempts to use a KMS key in a connected custom key store fail, that might indicate a problem with the custom key store or its AWS CloudHSM cluster. For help, see [How to fix a failing KMS key](fix-keystore.md#fix-cmk-failed).
To view the AWS CloudHSM key stores in a given account and Region, use the following procedure.
1. Sign in to the AWS Management Console and open the AWS Key Management Service (AWS KMS) console at [https://console.aws.amazon.com/kms](https://console.aws.amazon.com/kms).
1. To change the AWS Region, use the Region selector in the upper-right corner of the page.
1. In the navigation pane, choose **Custom key stores**, **AWS CloudHSM key stores**.
To customize the display, click the gear icon that appears below the **Create key store** button.
## Using the AWS KMS API
To view your AWS CloudHSM key stores, use the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) operation. By default, this operation returns all custom key stores in the account and Region. But you can use either the `CustomKeyStoreId` or `CustomKeyStoreName` parameter (but not both) to limit the output to a particular custom key store. For AWS CloudHSM key stores, the output consists of the custom key store ID and name, the custom key store type, the ID of the associated AWS CloudHSM cluster, and the connection state. If the connection state indicates an error, the output also includes an error code that describes the reason for the error.
The examples in this section use the [AWS Command Line Interface (AWS CLI)](https://aws.amazon.com/cli/), but you can use any supported programming language.
For example, the following command returns all custom key stores in the account and Region. You can use the `Limit` and `Marker` parameters to page through the custom key stores in the output.
```
$ aws kms describe-custom-key-stores
```
The following example command uses the `CustomKeyStoreName` parameter to get only the custom key store with the `ExampleCloudHSMKeyStore` friendly name. You can use either the `CustomKeyStoreName` or `CustomKeyStoreId` parameter (but not both) in each command.
The following example output represents an AWS CloudHSM key store that is connected to its AWS CloudHSM cluster.
**Note**
The `CustomKeyStoreType` field was added to the `DescribeCustomKeyStores` response to distinguish AWS CloudHSM key stores from external key stores.
```
$ aws kms describe-custom-key-stores --custom-key-store-name ExampleCloudHSMKeyStore
{
"CustomKeyStores": [
{
"CloudHsmClusterId": "cluster-1a23b4cdefg",
"ConnectionState": "CONNECTED",
"CreationDate": "1.499288695918E9",
"CustomKeyStoreId": "cks-1234567890abcdef0",
"CustomKeyStoreName": "ExampleCloudHSMKeyStore",
"CustomKeyStoreType": "AWS_CLOUDHSM",
"TrustAnchorCertificate": ""
}
]
}
```
A `ConnectionState` of `Disconnected` indicates that a custom key store has never been connected or it was intentionally [disconnected from its AWS CloudHSM cluster](disconnect-keystore.md). However, if attempts to use a KMS key in a connected AWS CloudHSM key store fail, that might indicate a problem with the AWS CloudHSM key store or its AWS CloudHSM cluster. For help, see [How to fix a failing KMS key](fix-keystore.md#fix-cmk-failed).
If the `ConnectionState` of the custom key store is `FAILED`, the `DescribeCustomKeyStores` response includes a `ConnectionErrorCode` element that explains the reason for the error.
For example, in the following output, the `INVALID_CREDENTIALS` value indicates that the custom key store connection failed because the [`kmsuser` password is invalid](fix-keystore.md#fix-keystore-password). For help with this and other connection error failures, see [Troubleshooting a custom key store](fix-keystore.md).
```
$ aws kms describe-custom-key-stores --custom-key-store-id cks-1234567890abcdef0
{
"CustomKeyStores": [
{
"CloudHsmClusterId": "cluster-1a23b4cdefg",
"ConnectionErrorCode": "INVALID_CREDENTIALS",
"ConnectionState": "FAILED",
"CustomKeyStoreId": "cks-1234567890abcdef0",
"CustomKeyStoreName": "ExampleCloudHSMKeyStore",
"CustomKeyStoreType": "AWS_CLOUDHSM",
"CreationDate": "1.499288695918E9",
"TrustAnchorCertificate": ""
}
]
}
```
**Learn more:**
+ [View external key stores](view-xks-keystore.md)
+ [Identify KMS keys in AWS CloudHSM key stores](identify-key-types.md#identify-key-hsm-keystore)
+ [Logging AWS KMS API calls with AWS CloudTrail](logging-using-cloudtrail.md)
# Edit AWS CloudHSM key store settings
You can change the settings of an existing AWS CloudHSM key store. The custom key store must be disconnected its AWS CloudHSM cluster.
To edit AWS CloudHSM key store settings:
1. [Disconnect the custom key store](disconnect-keystore.md) from its AWS CloudHSM cluster.
While the custom key store is disconnected, you cannot create AWS KMS keys (KMS keys) in the custom key store and you cannot use the KMS keys it contains for [cryptographic operations](manage-cmk-keystore.md#use-cmk-keystore).
1. Edit one or more of the AWS CloudHSM key store settings.
You can edit the following settings in a custom key store:
The friendly name of the custom key store.
Enter a new friendly name. The new name must be unique among all custom key stores in your AWS account.
Do not include confidential or sensitive information in this field. This field may be displayed in plaintext in CloudTrail logs and other output.
The cluster ID of the associated AWS CloudHSM cluster.
Edit this value to substitute a related AWS CloudHSM cluster for the original one. You can use this feature to repair a custom key store if its AWS CloudHSM cluster becomes corrupted or is deleted.
Specify an AWS CloudHSM cluster that shares a backup history with the original cluster and [fulfills the requirements](create-keystore.md#before-keystore) for association with a custom key store, including two active HSMs in different Availability Zones. Clusters that share a backup history have the same cluster certificate. To view the cluster certificate of a cluster, use the [DescribeClusters](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DescribeClusters.html) operation. You cannot use the edit feature to associate the custom key store with an unrelated AWS CloudHSM cluster.
The current password of the [`kmsuser` crypto user](keystore-cloudhsm.md#concept-kmsuser) (CU).
Tells AWS KMS the current password of the `kmsuser` CU in the AWS CloudHSM cluster. This action does not change the password of the `kmsuser` CU in the AWS CloudHSM cluster.
If you change the password of the `kmsuser` CU in the AWS CloudHSM cluster, use this feature to tell AWS KMS the new `kmsuser` password. Otherwise, AWS KMS cannot log into the cluster and all attempts to connect the custom key store to the cluster fail.
1. [Reconnect the custom key store](connect-keystore.md) to its AWS CloudHSM cluster.
## Edit your key store settings
You can edit your AWS CloudHSM key store settings in the AWS KMS console or by using the [UpdateCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_UpdateCustomKeyStore.html) operation.
### Using the AWS KMS console
When you edit an AWS CloudHSM key store, you can change any or of the configurable values.
1. Sign in to the AWS Management Console and open the AWS Key Management Service (AWS KMS) console at [https://console.aws.amazon.com/kms](https://console.aws.amazon.com/kms).
1. To change the AWS Region, use the Region selector in the upper-right corner of the page.
1. In the navigation pane, choose **Custom key stores**, **AWS CloudHSM key stores**.
1. Choose the row of the AWS CloudHSM key store you want to edit.
If the value in the **Connection state** column is not **Disconnected**, you must disconnect the custom key store before you can edit it. (From the **Key store actions** menu, choose **Disconnect**.)
While an AWS CloudHSM key store is disconnected, you can manage the AWS CloudHSM key store and its KMS keys, but you cannot create or use KMS keys in the AWS CloudHSM key store.
1. From the **Key store actions** menu, choose **Edit**.
1. Do one or more of the following actions.
+ Type a new friendly name for the custom key store.
+ Type the cluster ID of a related AWS CloudHSM cluster.
+ Type the current password of the `kmsuser` crypto user in the associated AWS CloudHSM cluster.
1. Choose **Save**.
When the procedure is successful, a message describes the settings that you edited. When it is unsuccessful, an error message appears that describes the problem and provides help on how to fix it. If you need more help, see [Troubleshooting a custom key store](fix-keystore.md).
1. [Reconnect the custom key store.](connect-keystore.md)
To use the AWS CloudHSM key store, you must reconnect it after editing. You can leave the AWS CloudHSM key store disconnected. But while it is disconnected, you cannot create KMS keys in the AWS CloudHSM key store or use the KMS keys in the AWS CloudHSM key store in [cryptographic operations](manage-cmk-keystore.md#use-cmk-keystore).
### Using the AWS KMS API
To change the properties of an AWS CloudHSM key store, use the [UpdateCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_UpdateCustomKeyStore.html) operation. You can change multiple properties of a custom key store in the same command. If the operation is successful, AWS KMS returns an HTTP 200 response and a JSON object with no properties. To verify that the changes are effective, use the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) operation.
The examples in this section use the [AWS Command Line Interface (AWS CLI)](https://aws.amazon.com/cli/), but you can use any supported programming language.
Begin by using [DisconnectCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_DisconnectCustomKeyStore.html) to [disconnect the custom key store](disconnect-keystore.md) from its AWS CloudHSM cluster. Replace the example custom key store ID, cks-1234567890abcdef0, with an actual ID.
```
$ aws kms disconnect-custom-key-store --custom-key-store-id cks-1234567890abcdef0
```
The first example uses [UpdateCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_UpdateCustomKeyStore.html) to change the friendly name of the AWS CloudHSM key store to `DevelopmentKeys`. The command uses the `CustomKeyStoreId` parameter to identify the AWS CloudHSM key store and the `CustomKeyStoreName` to specify the new name for the custom key store.
```
$ aws kms update-custom-key-store --custom-key-store-id cks-1234567890abcdef0 --new-custom-key-store-name DevelopmentKeys
```
The following example changes the cluster that is associated with an AWS CloudHSM key store to another backup of the same cluster. The command uses the `CustomKeyStoreId` parameter to identify the AWS CloudHSM key store and the `CloudHsmClusterId` parameter to specify the new cluster ID.
```
$ aws kms update-custom-key-store --custom-key-store-id cks-1234567890abcdef0 --cloud-hsm-cluster-id cluster-1a23b4cdefg
```
The following example tells AWS KMS that the current `kmsuser` password is `ExamplePassword`. The command uses the `CustomKeyStoreId` parameter to identify the AWS CloudHSM key store and the `KeyStorePassword` parameter to specify the current password.
```
$ aws kms update-custom-key-store --custom-key-store-id cks-1234567890abcdef0 --key-store-password ExamplePassword
```
The final command reconnects the AWS CloudHSM key store to its AWS CloudHSM cluster. You can leave the custom key store in the disconnected state, but you must connect it before you can create new KMS keys or use existing KMS keys for [cryptographic operations](manage-cmk-keystore.md#use-cmk-keystore). Replace the example custom key store ID with an actual ID.
```
$ aws kms connect-custom-key-store --custom-key-store-id cks-1234567890abcdef0
```
# Connect an AWS CloudHSM key store
New AWS CloudHSM key stores are not connected. Before you can create and use AWS KMS keys in your AWS CloudHSM key store, you need to connect it to its associated AWS CloudHSM cluster. You can connect and disconnect your AWS CloudHSM key store at any time, and [view its connection state](view-keystore.md#view-keystore-console).
You are not required to connect your AWS CloudHSM key store. You can leave an AWS CloudHSM key store in a disconnected state indefinitely and connect it only when you need to use it. However, you might want to test the connection periodically to verify that the settings are correct and it can be connected.
**Note**
AWS CloudHSM key stores have a `DISCONNECTED` connection state only when the key store has never been connected or you explicitly disconnect it. If your AWS CloudHSM key store connection state is `CONNECTED` but you are having trouble using it, make sure that its associated AWS CloudHSM cluster is active and contains at least one active HSMs. For help with connection failures, see [Troubleshooting a custom key store](fix-keystore.md).
When you connect an AWS CloudHSM key store, AWS KMS finds the associated AWS CloudHSM cluster, connects to it, logs into the AWS CloudHSM client as the [`kmsuser` crypto user](keystore-cloudhsm.md#concept-kmsuser) (CU), and then rotates the `kmsuser` password. AWS KMS remains logged into the AWS CloudHSM client as long as the AWS CloudHSM key store is connected.
To establish the connection, AWS KMS creates a [security group](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html) named `kms-` in the virtual private cloud (VPC) of the cluster. The security group has a single rule that allows inbound traffic from the cluster security group. AWS KMS also creates an [elastic network interface](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_ElasticNetworkInterfaces.html) (ENI) in each Availability Zone of the private subnet for the cluster. AWS KMS adds the ENIs to the `kms-` security group and the security group for the cluster. The description of each ENI is `KMS managed ENI for cluster `.
The connection process can take an extended amount of time to complete; up to 20 minutes.
Before you connect the AWS CloudHSM key store, verify that it meets the requirements.
+ Its associated AWS CloudHSM cluster must contain at least one active HSM. To find the number of HSMs in the cluster, view the cluster in the AWS CloudHSM console or use the [DescribeClusters](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DescribeClusters.html) operation. If necessary, you can [add an HSM](https://docs.aws.amazon.com/cloudhsm/latest/userguide/add-remove-hsm.html).
+ The cluster must have a [`kmsuser` crypto user](create-keystore.md#kmsuser-concept) (CU) account, but that CU cannot be logged into the cluster when you connect the AWS CloudHSM key store. For help with logging out, see [How to log out and reconnect](fix-keystore.md#login-kmsuser-2).
+ The connection state of the AWS CloudHSM key store cannot be `DISCONNECTING` or `FAILED`. To view the connection state, use the AWS KMS console or the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) response. If the connection state is `FAILED`, disconnect the custom key store, fix the problem, and then connect it.
For help with connection failures, see [How to fix a connection failure](fix-keystore.md#fix-keystore-failed).
When your AWS CloudHSM key store is connected, you can [create KMS keys in it](create-cmk-keystore.md) and use existing KMS keys in [cryptographic operations](manage-cmk-keystore.md#use-cmk-keystore).
## Connect and reconnect to your AWS CloudHSM key store
You can connect, or reconnect, your AWS CloudHSM key store in the AWS KMS console or by using the [ConnectCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_ConnectCustomKeyStore.html) operation.
### Using the AWS KMS console
To connect an AWS CloudHSM key store in the AWS Management Console, begin by selecting the AWS CloudHSM key store from the **Custom key stores** page. The connection process can take up to 20 minutes to complete.
1. Sign in to the AWS Management Console and open the AWS Key Management Service (AWS KMS) console at [https://console.aws.amazon.com/kms](https://console.aws.amazon.com/kms).
1. To change the AWS Region, use the Region selector in the upper-right corner of the page.
1. In the navigation pane, choose **Custom key stores**, **AWS CloudHSM key stores**.
1. Choose the row of the AWS CloudHSM key store you want to connect.
If the connection state of the AWS CloudHSM key store is **Failed**, you must [disconnect the custom key store](disconnect-keystore.md#disconnect-keystore-console) before you connect it.
1. From the **Key store actions** menu, choose **Connect**.
AWS KMS begins the process of connecting your custom key store. It finds the associated AWS CloudHSM cluster, builds the required network infrastructure, connects to it, logs into the AWS CloudHSM cluster as the `kmsuser` CU, and rotates the `kmsuser` password. When the operation completes, the connection state changes to **Connected**.
If the operation fails, an error message appears that describes the reason for the failure. Before you try to connect again, [view the connection state](view-keystore.md) of your AWS CloudHSM key store. If it is **Failed**, you must [disconnect the custom key store](disconnect-keystore.md#disconnect-keystore-console) before you connect it again. If you need help, see [Troubleshooting a custom key store](fix-keystore.md).
**Next:** [Create a KMS key in an AWS CloudHSM key store](create-cmk-keystore.md).
### Using the AWS KMS API
To connect a disconnected AWS CloudHSM key store, use the [ConnectCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_ConnectCustomKeyStore.html) operation. The associated AWS CloudHSM cluster must contain at least one active HSM and the connection state cannot be `FAILED`.
The connection process takes an extended amount of time to complete; up to 20 minutes. Unless it fails quickly, the operation returns an HTTP 200 response and a JSON object with no properties. However, this initial response does not indicate that the connection was successful. To determine the connection state of the custom key store, see the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) response.
The examples in this section use the [AWS Command Line Interface (AWS CLI)](https://aws.amazon.com/cli/), but you can use any supported programming language.
To identify the AWS CloudHSM key store, use its custom key store ID. You can find the ID on the **Custom key stores** page in the console or by using the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) operation with no parameters. Before running this example, replace the example ID with a valid one.
```
$ aws kms connect-custom-key-store --custom-key-store-id cks-1234567890abcdef0
```
To verify that the AWS CloudHSM key store is connected, use the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) operation. By default, this operation returns all custom keys stores in your account and Region. But you can use either the `CustomKeyStoreId` or `CustomKeyStoreName` parameter (but not both) to limit the response to particular custom key stores. The `ConnectionState` value of `CONNECTED` indicates that the custom key store is connected to its AWS CloudHSM cluster.
**Note**
The `CustomKeyStoreType` field was added to the `DescribeCustomKeyStores` response to distinguish AWS CloudHSM key stores from external key stores.
```
$ aws kms describe-custom-key-stores --custom-key-store-id cks-1234567890abcdef0
{
"CustomKeyStores": [
"CustomKeyStoreId": "cks-1234567890abcdef0",
"CustomKeyStoreName": "ExampleCloudHSMKeyStore",
"CloudHsmClusterId": "cluster-1a23b4cdefg",
"CustomKeyStoreType": "AWS_CLOUDHSM",
"TrustAnchorCertificate": "",
"CreationDate": "1.499288695918E9",
"ConnectionState": "CONNECTED"
],
}
```
If the `ConnectionState` value is failed, the `ConnectionErrorCode` element indicates the reason for the failure. In this case, AWS KMS could not find an AWS CloudHSM cluster in your account with the cluster ID `cluster-1a23b4cdefg`. If you deleted the cluster, you can [restore it from a backup](https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-cluster-from-backup.html) of the original cluster and then [edit the cluster ID](update-keystore.md) for the custom key store. For help responding to a connection error code, see [How to fix a connection failure](fix-keystore.md#fix-keystore-failed).
```
$ aws kms describe-custom-key-stores --custom-key-store-id cks-1234567890abcdef0
{
"CustomKeyStores": [
"CustomKeyStoreId": "cks-1234567890abcdef0",
"CustomKeyStoreName": "ExampleKeyStore",
"CloudHsmClusterId": "cluster-1a23b4cdefg",
"CustomKeyStoreType": "AWS_CLOUDHSM",
"TrustAnchorCertificate": "",
"CreationDate": "1.499288695918E9",
"ConnectionState": "FAILED"
"ConnectionErrorCode": "CLUSTER_NOT_FOUND"
],
}
```
# Disconnect an AWS CloudHSM key store
When you disconnect an AWS CloudHSM key store, AWS KMS logs out of the AWS CloudHSM client, disconnects from the associated AWS CloudHSM cluster, and removes the network infrastructure that it created to support the connection.
While an AWS CloudHSM key store is disconnected, you can manage the AWS CloudHSM key store and its KMS keys, but you cannot create or use KMS keys in the AWS CloudHSM key store. The connection state of the key store is `DISCONNECTED` and the [key state](key-state.md) of KMS keys in the custom key store is `Unavailable`, unless they are `PendingDeletion`. You can reconnect the AWS CloudHSM key store at any time.
**Note**
AWS CloudHSM key stores have a `DISCONNECTED` connection state only when the key store has never been connected or you explicitly disconnect it. If your AWS CloudHSM key store connection state is `CONNECTED` but you are having trouble using it, make sure that its associated AWS CloudHSM cluster is active and contains at least one active HSMs. For help with connection failures, see [Troubleshooting a custom key store](fix-keystore.md).
When you disconnect a custom key store, the KMS keys in the key store become unusable right away (subject to eventual consistency). However, resources encrypted with [data keys](data-keys.md) protected by the KMS key are not affected until the KMS key is used again, such as to decrypt the data key. This issue affects AWS services, many of which use data keys to protect your resources. For details, see [How unusable KMS keys affect data keys](unusable-kms-keys.md).
**Note**
While a custom key store is disconnected, all attempts to create KMS keys in the custom key store or to use existing KMS keys in cryptographic operations will fail. This action can prevent users from storing and accessing sensitive data.
To better estimate the effect of disconnecting your custom key store, [identify the KMS keys](find-cmk-in-keystore.md) in the custom key store and [determine their past use](deleting-keys-determining-usage.md).
You might disconnect an AWS CloudHSM key store for reasons such as the following:
+ **To rotate of the `kmsuser` password.** AWS KMS changes the `kmsuser` password each time that it connects to the AWS CloudHSM cluster. To force a password rotation, just disconnect and reconnect.
+ **To audit the key material** for the KMS keys in the AWS CloudHSM cluster. When you disconnect the custom key store, AWS KMS logs out of the [`kmsuser` crypto user](keystore-cloudhsm.md#concept-kmsuser) account in the AWS CloudHSM client. This allows you to log into the cluster as the `kmsuser` CU and audit and manage the key material for the KMS key.
+ **To immediately disable all KMS keys** in the AWS CloudHSM key store. You can [disable and re-enable KMS keys](enabling-keys.md) in an AWS CloudHSM key store by using the AWS Management Console or the [DisableKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DisableKey.html) operation. These operations complete quickly, but they act on one KMS key at a time. Disconnecting the AWS CloudHSM key store immediately changes the key state of all KMS keys in the AWS CloudHSM key store to `Unavailable`, which prevents them from being used in any cryptographic operation.
+ **To repair a failed connection attempt**. If an attempt to connect an AWS CloudHSM key store fails (the connection state of the custom key store is `FAILED`), you must disconnect the AWS CloudHSM key store before you try to connect it again.
## Disconnect your AWS CloudHSM key store
You can disconnect your AWS CloudHSM key store in the AWS KMS console or by using the [DisconnectCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_DisconnectCustomKeyStore.html) operation.
### Disconnect using the AWS KMS console
To disconnect a connected AWS CloudHSM key store in the AWS KMS console, begin by choosing the AWS CloudHSM key store from the **Custom Key Stores** page.
1. Sign in to the AWS Management Console and open the AWS Key Management Service (AWS KMS) console at [https://console.aws.amazon.com/kms](https://console.aws.amazon.com/kms).
1. To change the AWS Region, use the Region selector in the upper-right corner of the page.
1. In the navigation pane, choose **Custom key stores**, **AWS CloudHSM key stores**.
1. Choose the row of the external key store you want to disconnect.
1. From the **Key store actions** menu, choose **Disconnect**.
When the operation completes, the connection state changes from **Disconnecting** to **Disconnected**. If the operation fails, an error message appears that describes the problem and provides help on how to fix it. If you need more help, see [Troubleshooting a custom key store](fix-keystore.md).
### Disconnect using the AWS KMS API
To disconnect a connected AWS CloudHSM key store, use the [DisconnectCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_DisconnectCustomKeyStore.html) operation. If the operation is successful, AWS KMS returns an HTTP 200 response and a JSON object with no properties.
The examples in this section use the [AWS Command Line Interface (AWS CLI)](https://aws.amazon.com/cli/), but you can use any supported programming language.
This example disconnects an AWS CloudHSM key store. Before running this example, replace the example ID with a valid one.
```
$ aws kms disconnect-custom-key-store --custom-key-store-id cks-1234567890abcdef0
```
To verify that the AWS CloudHSM key store is disconnected, use the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) operation. By default, this operation returns all custom keys stores in your account and Region. But you can use either the `CustomKeyStoreId` and `CustomKeyStoreName` parameter (but not both) to limit the response to particular custom key stores. The `ConnectionState` value of `DISCONNECTED` indicates that this example AWS CloudHSM key store is not connected to its AWS CloudHSM cluster.
```
$ aws kms describe-custom-key-stores --custom-key-store-id cks-1234567890abcdef0
{
"CustomKeyStores": [
"CloudHsmClusterId": "cluster-1a23b4cdefg",
"ConnectionState": "DISCONNECTED",
"CreationDate": "1.499288695918E9",
"CustomKeyStoreId": "cks-1234567890abcdef0",
"CustomKeyStoreName": "ExampleKeyStore",
"CustomKeyStoreType": "AWS_CLOUDHSM",
"TrustAnchorCertificate": ""
],
}
```
# Delete an AWS CloudHSM key store
When you delete an AWS CloudHSM key store, AWS KMS deletes all metadata about the AWS CloudHSM key store from KMS, including information about its association with an AWS CloudHSM cluster. This operation does not affect the AWS CloudHSM cluster, its HSMs, or its users. You can create a new AWS CloudHSM key store that is associated with the same AWS CloudHSM cluster, but you cannot undo the delete operation.
You can only delete an AWS CloudHSM key store that is disconnected from its AWS CloudHSM cluster and does not contain any AWS KMS keys. Before you delete a custom key store, do the following.
+ Verify that you will never need to use any of the KMS keys in the key store for any [cryptographic operations](manage-cmk-keystore.md#use-cmk-keystore). Then [schedule deletion](deleting-keys.md#delete-cmk-keystore) of all of the KMS keys from the key store. For help finding the KMS keys in an AWS CloudHSM key store, see [Find the KMS keys in an AWS CloudHSM key store](find-cmk-in-keystore.md).
+ Confirm that all KMS keys have been deleted. To view the KMS keys in an AWS CloudHSM key store, see [Identify KMS keys in AWS CloudHSM key stores](identify-key-types.md#identify-key-hsm-keystore).
+ [Disconnect the AWS CloudHSM key store](disconnect-keystore.md) from its AWS CloudHSM cluster.
Instead of deleting the AWS CloudHSM key store, consider [disconnecting it](disconnect-keystore.md) from its associated AWS CloudHSM cluster. While an AWS CloudHSM key store is disconnected, you can manage the AWS CloudHSM key store and its AWS KMS keys. But you cannot create or use KMS keys in the AWS CloudHSM key store. You can reconnect the AWS CloudHSM key store at any time.
## Delete your AWS CloudHSM key store
You can delete your AWS CloudHSM key store in the AWS KMS console or by using the [DeleteCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeleteCustomKeyStore.html) operation.
### Using the AWS KMS console
To delete an AWS CloudHSM key store in the AWS Management Console, begin by selecting the AWS CloudHSM key store from the **Custom key stores** page.
1. Sign in to the AWS Management Console and open the AWS Key Management Service (AWS KMS) console at [https://console.aws.amazon.com/kms](https://console.aws.amazon.com/kms).
1. To change the AWS Region, use the Region selector in the upper-right corner of the page.
1. In the navigation pane, choose **Custom key stores**, **AWS CloudHSM key stores**.
1. Find the row that represents the AWS CloudHSM key store that you want to delete. If the **Connection state** of the AWS CloudHSM key store is not **Disconnected**, you must [disconnect the AWS CloudHSM key store](disconnect-keystore.md) before you delete it.
1. From the **Key store actions** menu, choose **Delete**.
When the operation completes, a success message appears and the AWS CloudHSM key store no longer appears in the key stores list. If the operation is unsuccessful, an error message appears that describes the problem and provides help on how to fix it. If you need more help, see [Troubleshooting a custom key store](fix-keystore.md).
### Using the AWS KMS API
To delete an AWS CloudHSM key store, use the [DeleteCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeleteCustomKeyStore.html) operation. If the operation is successful, AWS KMS returns an HTTP 200 response and a JSON object with no properties.
To begin, verify that the AWS CloudHSM key store does not contain any AWS KMS keys. You cannot delete a custom key store that contains KMS keys. The first example command uses [ListKeys](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListKeys.html) and [DescribeKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html) to search for AWS KMS keys in the AWS CloudHSM key store with the example *cks-1234567890abcdef0* custom key store ID. In this case, the command does not return any KMS keys. If it does, use the [ScheduleKeyDeletion](https://docs.aws.amazon.com/kms/latest/APIReference/API_ScheduleKeyDeletion.html) operation to schedule deletion of each of the KMS keys.
------
#### [ Bash ]
```
for key in $(aws kms list-keys --query 'Keys[*].KeyId' --output text) ;
do aws kms describe-key --key-id $key |
grep '"CustomKeyStoreId": "cks-1234567890abcdef0"' --context 100; done
```
------
#### [ PowerShell ]
```
PS C:\> Get-KMSKeyList | Get-KMSKey | where CustomKeyStoreId -eq 'cks-1234567890abcdef0'
```
------
Next, disconnect the AWS CloudHSM key store. This example command uses the [DisconnectCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_DisconnectCustomKeyStore.html) operation to disconnect an AWS CloudHSM key store from its AWS CloudHSM cluster. Before running this command, replace the example custom key store ID with a valid one.
------
#### [ Bash ]
```
$ aws kms disconnect-custom-key-store --custom-key-store-id cks-1234567890abcdef0
```
------
#### [ PowerShell ]
```
PS C:\> Disconnect-KMSCustomKeyStore -CustomKeyStoreId cks-1234567890abcdef0
```
------
After the custom key store is disconnected, you can use the [DeleteCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeleteCustomKeyStore.html) operation to delete it.
------
#### [ Bash ]
```
$ aws kms delete-custom-key-store --custom-key-store-id cks-1234567890abcdef0
```
------
#### [ PowerShell ]
```
PS C:\> Remove-KMSCustomKeyStore -CustomKeyStoreId cks-1234567890abcdef0
```
------
# Troubleshooting a custom key store
AWS CloudHSM key stores are designed to be available and resilient. However, there are some error conditions that you might have to repair to keep your AWS CloudHSM key store operational.
**Topics**
+ [
## How to fix unavailable KMS keys
](#fix-unavailable-cmks)
+ [
## How to fix a failing KMS key
](#fix-cmk-failed)
+ [
## How to fix a connection failure
](#fix-keystore-failed)
+ [
## How to respond to a cryptographic operation failure
](#fix-keystore-communication)
+ [
## How to fix invalid `kmsuser` credentials
](#fix-keystore-password)
+ [
## How to delete orphaned key material
](#fix-keystore-orphaned-key)
+ [
## How to recover deleted key material for a KMS key
](#fix-keystore-recover-backing-key)
+ [
## How to log in as `kmsuser`
](#fix-login-as-kmsuser)
## How to fix unavailable KMS keys
The [key state](key-state.md) of AWS KMS keys in an AWS CloudHSM key store is typically `Enabled`. Like all KMS keys, the key state changes when you disable the KMS keys in an AWS CloudHSM key store or schedule them for deletion. However, unlike other KMS keys, the KMS keys in a custom key store can also have a [key state](key-state.md) of `Unavailable`.
A key state of `Unavailable` indicates that the KMS key is in a custom key store that was intentionally [disconnected](disconnect-keystore.md) and attempts to reconnect it, if any, failed. While a KMS key is unavailable, you can view and manage the KMS key, but you cannot use it for [cryptographic operations](manage-cmk-keystore.md#use-cmk-keystore).
To find the key state of a KMS key, on the **Customer managed keys** page, view the **Status** field of the KMS key. Or, use the [DescribeKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html) operation and view the `KeyState` element in the response. For details, see [Identify and view keys](viewing-keys.md).
The KMS keys in a disconnected custom key store will have a key state of `Unavailable` or `PendingDeletion`. KMS keys that are scheduled for deletion from a custom key store have a `Pending Deletion` key state, even when the custom key store is disconnected. This allows you to cancel the scheduled key deletion without reconnecting the custom key store.
To fix an unavailable KMS key, [reconnect the custom key store](disconnect-keystore.md). After the custom key store is reconnected, the key state of the KMS keys in the custom key store is automatically restored to its previous state, such as `Enabled` or `Disabled`. KMS keys that are pending deletion remain in the `PendingDeletion` state. However, while the problem persists, [enabling and disabling an unavailable KMS key](enabling-keys.md) does not change its key state. The enable or disable action takes effect only when the key becomes available.
For help with failed connections, see [How to fix a connection failure](#fix-keystore-failed).
## How to fix a failing KMS key
Problems with creating and using KMS keys in AWS CloudHSM key stores can be caused by a problem with your AWS CloudHSM key store, its associated AWS CloudHSM cluster, the KMS key, or its key material.
When an AWS CloudHSM key store is disconnected from its AWS CloudHSM cluster, the key state of KMS keys in the custom key store is `Unavailable`. All requests to create KMS keys in a disconnected AWS CloudHSM key store return a `CustomKeyStoreInvalidStateException` exception. All requests to encrypt, decrypt, re-encrypt, or generate data keys return a `KMSInvalidStateException` exception. To fix the problem, [reconnect the AWS CloudHSM key store](connect-keystore.md).
However, your attempts to use a KMS key in an AWS CloudHSM key store for [cryptographic operations](manage-cmk-keystore.md#use-cmk-keystore) might fail even when its key state is `Enabled` and the connection state of the AWS CloudHSM key store is `Connected`. This might be caused by any of the following conditions.
+ The key material for the KMS key might have been deleted from the associated AWS CloudHSM cluster. To investigate, [find the key id](find-handle-for-cmk-id.md) of the key material for a KMS key and, if necessary, try to [recover the key material](#fix-keystore-recover-backing-key).
+ All HSMs were deleted from the AWS CloudHSM cluster that is associated with the AWS CloudHSM key store. To use a KMS key in an AWS CloudHSM key store in a cryptographic operation, its AWS CloudHSM cluster must contain at least one active HSM. To verify the number and state of HSMs in an AWS CloudHSM cluster, [use the AWS CloudHSM console](https://docs.aws.amazon.com/cloudhsm/latest/userguide/add-remove-hsm.html) or the [DescribeClusters](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DescribeClusters.html) operation. To add an HSM to the cluster, use the AWS CloudHSM console or the [CreateHsm](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_CreateHsm.html) operation.
+ The AWS CloudHSM cluster associated with the AWS CloudHSM key store was deleted. To fix the problem, [create a cluster from a backup](https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-cluster-from-backup.html) that is related to the original cluster, such as a backup of the original cluster, or a backup that was used to create the original cluster. Then, [edit the cluster ID](update-keystore.md) in the custom key store settings. For instructions, see [How to recover deleted key material for a KMS key](#fix-keystore-recover-backing-key).
+ The AWS CloudHSM cluster associated with the custom key store did not have any available PKCS \$111 sessions. This typically occurs during periods of high burst traffic when additional sessions are needed to service the traffic. To respond to a `KMSInternalException` with an error message about PKCS \$111 sessions, back off and retry the request again.
## How to fix a connection failure
If you try to [connect an AWS CloudHSM key store](connect-keystore.md) to its AWS CloudHSM cluster, but the operation fails, the connection state of the AWS CloudHSM key store changes to `FAILED`. To find the connection state of an AWS CloudHSM key store, use the AWS KMS console or the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) operation.
Alternatively, some connection attempts fail quickly due to easily detected cluster configuration errors. In this case, the connection state is still `DISCONNECTED`. These failures return an error message or [exception](https://docs.aws.amazon.com/kms/latest/APIReference/API_ConnectCustomKeyStore.html#API_ConnectCustomKeyStore_Errors) that explains why the attempt failed. Review the exception description and [cluster requirements](create-keystore.md#before-keystore), fix the problem, [update the AWS CloudHSM key store](update-keystore.md), if necessary, and try to connect again.
When the connection state is `FAILED`, run the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) operation and see the `ConnectionErrorCode` element in the response.
**Note**
When the connection state of an AWS CloudHSM key store is `FAILED`, you must [disconnect the AWS CloudHSM key store](disconnect-keystore.md) before attempting to reconnect it. You cannot connect an AWS CloudHSM key store with a `FAILED` connection state.
+ `CLUSTER_NOT_FOUND` indicates that AWS KMS cannot find an AWS CloudHSM cluster with the specified cluster ID. This might occur because the wrong cluster ID was provided to an API operation or the cluster was deleted and not replaced. To fix this error, verify the cluster ID, such as by using the AWS CloudHSM console or the [DescribeClusters](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DescribeClusters.html) operation. If the cluster was deleted, [create a cluster from a recent backup](https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-cluster-from-backup.html) of the original. Then, [disconnect the AWS CloudHSM key store](disconnect-keystore.md), [edit the AWS CloudHSM key store](update-keystore.md) cluster ID setting, and [reconnect the AWS CloudHSM key store](connect-keystore.md) to the cluster.
+ `INSUFFICIENT_CLOUDHSM_HSMS` indicates that the associated AWS CloudHSM cluster does not contain any HSMs. To connect, the cluster must have at least one HSM. To find the number of HSMs in the cluster, use the [DescribeClusters](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DescribeClusters.html) operation. To resolve this error, [add at least one HSM](https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-hsm.html) to the cluster. If you add multiple HSMs, it's best to create them in different Availability Zones.
+ `INSUFFICIENT_FREE_ADDRESSES_IN_SUBNET` indicates that AWS KMS could not connect the AWS CloudHSM key store to its AWS CloudHSM cluster because at least one [private subnet associated with the cluster](https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-subnets.html) doesn't have any available IP addresses. An AWS CloudHSM key store connection requires one free IP address in each of the associated private subnets, although two are preferable.
You [can't add IP addresses](https://aws.amazon.com/premiumsupport/knowledge-center/vpc-ip-address-range/) (CIDR blocks) to an existing subnet. If possible, move or delete other resources that are using the IP addresses in the subnet, such as unused EC2 instances or elastic network interfaces. Otherwise, you can [create a cluster from a recent backup](https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-cluster-from-backup.html) of the AWS CloudHSM cluster with new or existing private subnets that have [more free address space](https://docs.aws.amazon.com/vpc/latest/userguide/configure-subnets.html#subnet-sizing). Then, to associate the new cluster with your AWS CloudHSM key store, [disconnect the custom key store](disconnect-keystore.md), [change the cluster ID](update-keystore.md) of the AWS CloudHSM key store to the ID of the new cluster, and try to connect again.
**Tip**
To avoid [resetting the `kmsuser` password](#fix-keystore-password), use the most recent backup of the AWS CloudHSM cluster.
+ `INTERNAL_ERROR` indicates that AWS KMS could not complete the request due to an internal error. Retry the request. For `ConnectCustomKeyStore` requests, disconnect the AWS CloudHSM key store before trying to connect again.
+ `INVALID_CREDENTIALS` indicates that AWS KMS cannot log into the associated AWS CloudHSM cluster because it doesn't have the correct `kmsuser` account password. For help with this error, see [How to fix invalid `kmsuser` credentials](#fix-keystore-password).
+ `NETWORK_ERRORS` usually indicates transient network issues. [Disconnect the AWS CloudHSM key store](disconnect-keystore.md), wait a few minutes, and try to connect again.
+ `SUBNET_NOT_FOUND` indicates that at least one subnet in the AWS CloudHSM cluster configuration was deleted. If AWS KMS cannot find all of the subnets in the cluster configuration, attempts to connect the AWS CloudHSM key store to the AWS CloudHSM cluster fail.
To fix this error, [create a cluster from a recent backup](https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-cluster-from-backup.html) of the same AWS CloudHSM cluster. (This process creates a new cluster configuration with a VPC and private subnets.) Verify that the new cluster meets the [requirements for a custom key store](create-keystore.md#before-keystore), and note the new cluster ID. Then, to associate the new cluster with your AWS CloudHSM key store, [disconnect the custom key store](disconnect-keystore.md), [change the cluster ID](update-keystore.md) of the AWS CloudHSM key store to the ID of the new cluster, and try to connect again.
**Tip**
To avoid [resetting the `kmsuser` password](#fix-keystore-password), use the most recent backup of the AWS CloudHSM cluster.
+ `USER_LOCKED_OUT` indicates that the [`kmsuser` crypto user (CU) account](keystore-cloudhsm.md#concept-kmsuser) is locked out of the associated AWS CloudHSM cluster due to too many failed password attempts. For help with this error, see [How to fix invalid `kmsuser` credentials](#fix-keystore-password).
To fix this error, [disconnect the AWS CloudHSM key store](disconnect-keystore.md) and use the [https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-user-change-password.html](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-user-change-password.html) command in CloudHSM CLI to change the `kmsuser` account password. Then, [edit the `kmsuser` password setting](update-keystore.md) for the custom key store, and try to connect again. For help, use the procedure described in the [How to fix invalid `kmsuser` credentials](#fix-keystore-password) topic.
+ `USER_LOGGED_IN` indicates that the `kmsuser` CU account is logged into the associated AWS CloudHSM cluster. This prevents AWS KMS from rotating the `kmsuser` account password and logging into the cluster. To fix this error, log the `kmsuser` CU out of the cluster. If you changed the `kmsuser` password to log into the cluster, you must also and update the key store password value for the AWS CloudHSM key store. For help, see [How to log out and reconnect](#login-kmsuser-2).
+ `USER_NOT_FOUND` indicates that AWS KMS cannot find a `kmsuser` CU account in the associated AWS CloudHSM cluster. To fix this error, [create a `kmsuser` CU account](create-keystore.md#kmsuser-concept) in the cluster, and then [update the key store password value](update-keystore.md) for the AWS CloudHSM key store. For help, see [How to fix invalid `kmsuser` credentials](#fix-keystore-password).
## How to respond to a cryptographic operation failure
A cryptographic operation that uses a KMS key in a custom key store might fail with a `KMSInvalidStateException`. The following error messages might accompany the `KMSInvalidStateException`.
| |
| --- |
| KMS cannot communicate with your CloudHSM cluster. This might be a transient network issue. If you see this error repeatedly, verify that the Network ACLs and the security group rules for the VPC of your AWS CloudHSM cluster are correct. |
+ Although this is an HTTPS 400 error, it might result from transient network issues. To respond, begin by retrying the request. However, if it continues to fail, examine the configuration of your networking components. This error is most likely caused by the misconfiguration of a networking component, such as a firewall rule or VPC security group rule that is blocking outgoing traffic. For example, KMS cannot communicate with AWS CloudHSM clusters over IPv6. For details on prerequisites, see [Create an AWS CloudHSM key store](create-keystore.md).
| |
| --- |
| KMS cannot communicate with your AWS CloudHSM cluster because the kmsuser is locked out. If you see this error repeatedly, disconnect the AWS CloudHSM key store and reset the kmsuser account password. Update the kmsuser password for the custom key store and try the request again. |
+ This error message indicates that the [`kmsuser` crypto user (CU) account](keystore-cloudhsm.md#concept-kmsuser) is locked out of the associated AWS CloudHSM cluster due to too many failed password attempts. For help with this error, see [How to disconnect and log in](#login-kmsuser-1).
## How to fix invalid `kmsuser` credentials
When you [connect an AWS CloudHSM key store](connect-keystore.md), AWS KMS logs into the associated AWS CloudHSM cluster as the [`kmsuser` crypto user](keystore-cloudhsm.md#concept-kmsuser) (CU). It remains logged in until the AWS CloudHSM key store is disconnected. The [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) response shows a `ConnectionState` of `FAILED` and `ConnectionErrorCode` value of `INVALID_CREDENTIALS`, as shown in the following example.
If you disconnect the AWS CloudHSM key store and change the `kmsuser` password, AWS KMS cannot log into the AWS CloudHSM cluster with the credentials of the `kmsuser` CU account. As a result, all attempts to connect the AWS CloudHSM key store fail. The `DescribeCustomKeyStores` response shows a `ConnectionState` of `FAILED` and `ConnectionErrorCode` value of `INVALID_CREDENTIALS`, as shown in the following example.
```
$ aws kms describe-custom-key-stores --custom-key-store-name ExampleKeyStore
{
"CustomKeyStores": [
"CloudHsmClusterId": "cluster-1a23b4cdefg",
"ConnectionErrorCode": "INVALID_CREDENTIALS"
"CustomKeyStoreId": "cks-1234567890abcdef0",
"CustomKeyStoreName": "ExampleKeyStore",
"TrustAnchorCertificate": "",
"CreationDate": "1.499288695918E9",
"ConnectionState": "FAILED"
],
}
```
Also, after five failed attempts to log into the cluster with an incorrect password, AWS CloudHSM locks the user account. To log into the cluster, you must change the account password.
If AWS KMS gets a lockout response when it tries to log into the cluster as the `kmsuser` CU, the request to connect the AWS CloudHSM key store fails. The [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) response includes a `ConnectionState` of `FAILED` and `ConnectionErrorCode` value of `USER_LOCKED_OUT`, as shown in the following example.
```
$ aws kms describe-custom-key-stores --custom-key-store-name ExampleKeyStore
{
"CustomKeyStores": [
"CloudHsmClusterId": "cluster-1a23b4cdefg",
"ConnectionErrorCode": "USER_LOCKED_OUT"
"CustomKeyStoreId": "cks-1234567890abcdef0",
"CustomKeyStoreName": "ExampleKeyStore",
"TrustAnchorCertificate": "",
"CreationDate": "1.499288695918E9",
"ConnectionState": "FAILED"
],
}
```
To repair any of these conditions, use the following procedure.
1. [Disconnect the AWS CloudHSM key store](disconnect-keystore.md).
1. Run the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) operation and view the value of the `ConnectionErrorCode` element in the response.
+ If the `ConnectionErrorCode` value is `INVALID_CREDENTIALS`, determine the current password for the `kmsuser` account. If necessary, use the [https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-user-change-password.html](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-user-change-password.html) command in CloudHSM CLI to set the password to a known value.
+ If the `ConnectionErrorCode` value is `USER_LOCKED_OUT`, you must use the [https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-user-change-password.html](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-user-change-password.html) command in CloudHSM CLI to change the `kmsuser` password.
1. [Edit the `kmsuser` password setting](update-keystore.md) so it matches the current `kmsuser` password in the cluster. This action tells AWS KMS which password to use to log into the cluster. It does not change the `kmsuser` password in the cluster.
1. [Connect the custom key store](connect-keystore.md).
## How to delete orphaned key material
After scheduling deletion of a KMS key from an AWS CloudHSM key store, you might need to manually delete the corresponding key material from the associated AWS CloudHSM cluster.
When you create a KMS key in an AWS CloudHSM key store, AWS KMS creates the KMS key metadata in AWS KMS and generates the key material in the associated AWS CloudHSM cluster. When you schedule deletion of a KMS key in an AWS CloudHSM key store, after the waiting period, AWS KMS deletes the KMS key metadata. Then AWS KMS makes a best effort to delete the corresponding key material from the AWS CloudHSM cluster. The attempt might fail if AWS KMS cannot access the cluster, such as when it's disconnected from the AWS CloudHSM key store or the `kmsuser` password changes. AWS KMS does not attempt to delete key material from cluster backups.
AWS KMS reports the results of its attempt to delete the key material from the cluster in the `DeleteKey` event entry of your AWS CloudTrail logs. It appears in the `backingKeysDeletionStatus` element of the `additionalEventData` element, as shown in the following example entry. The entry also includes the KMS key ARN, the AWS CloudHSM cluster ID, and the ID (`backing-key-id`) of the key material.
```
{
"eventVersion": "1.08",
"userIdentity": {
"accountId": "111122223333",
"invokedBy": "AWS Internal"
},
"eventTime": "2021-12-10T14:23:51Z",
"eventSource": "kms.amazonaws.com",
"eventName": "DeleteKey",
"awsRegion": "us-west-2",
"sourceIPAddress": "AWS Internal",
"userAgent": "AWS Internal",
"requestParameters": null,
"responseElements": {
"keyId":"arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
},
"additionalEventData": {
"customKeyStoreId": "cks-1234567890abcdef0",
"clusterId": "cluster-1a23b4cdefg",
"backingKeys": "[{\"backingKeyId\":\"backing-key-id\"}]",
"backingKeysDeletionStatus": "[{\"backingKeyId\":\"backing-key-id\",\"deletionStatus\":\"FAILURE\"}]"
},
"eventID": "c21f1f47-f52b-4ffe-bff0-6d994403cf40",
"readOnly": false,
"resources": [
{
"accountId": "111122223333",
"type": "AWS::KMS::Key",
"ARN": "arn:aws:kms:eu-west-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
}
],
"eventType": "AwsServiceEvent",
"recipientAccountId": "111122223333",
"managementEvent": true,
"eventCategory": "Management"
}
```
**Notes**
The following procedures use the AWS CloudHSM Client SDK 5 command line tool, [CloudHSM CLI](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli.html). The CloudHSM CLI replaces `key-handle` with `key-reference`.
On January 1, 2025, AWS CloudHSM will end support for the Client SDK 3 command line tools, the CloudHSM Management Utility (CMU) and the Key Management Utility (KMU). For more information on the differences between the Client SDK 3 command line tools and the Client SDK 5 command line tool, see [Migrate from Client SDK 3 CMU and KMU to Client SDK 5 CloudHSM CLI](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-migrate-from-kmu-cmu.html) in the *AWS CloudHSM User Guide*.
The following procedures demonstrate how to delete the orphaned key material from the associated AWS CloudHSM cluster.
1. Disconnect the AWS CloudHSM key store, if it is not already disconnected, then [https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-login.html](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-login.html), as explained in [How to disconnect and log in](#login-kmsuser-1).
**Note**
While a custom key store is disconnected, all attempts to create KMS keys in the custom key store or to use existing KMS keys in cryptographic operations will fail. This action can prevent users from storing and accessing sensitive data.
1. Use the [key delete](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-key-delete.html) command in CloudHSM CLI to delete the key from the HSMs in the cluster.
All CloudTrail log entries for cryptographic operation with a KMS key in a AWS CloudHSM key store include an `additionalEventData` field with the `customKeyStoreId` and `backingKey`. The value returned in the `backingKeyId` field is the CloudHSM key `id` attribute. We recommend filtering the **key delete** operation by `id` to delete the orphaned key material you identified in your CloudTrail logs.
AWS CloudHSM recognizes the `backingKeyId` value as a hexadecimal value. To filter by `id`, you must prepend the `backingKeyId` with `Ox`. For example, if the `backingKeyId` in your CloudTrail log is `1a2b3c45678abcdef`, you would filter by `0x1a2b3c45678abcdef`.
The following example deletes a key from the HSMs in your cluster. The `backing-key-id` is listed in the CloudTrail log entry. Before running this command, replace the example `backing-key-id` with a valid one from your account.
```
aws-cloudhsm key delete --filter attr.id="0x"
{
"error_code": 0,
"data": {
"message": "Key deleted successfully"
}
}
```
1. Log out and reconnect the AWS CloudHSM key store as described in [How to log out and reconnect](#login-kmsuser-2).
## How to recover deleted key material for a KMS key
If the key material for an AWS KMS key is deleted, the KMS key is unusable and all ciphertext that was encrypted under the KMS key cannot be decrypted. This can happen if the key material for a KMS key in an AWS CloudHSM key store is deleted from the associated AWS CloudHSM cluster. However, it might be possible to recover the key material.
When you create an AWS KMS key (KMS key) in an AWS CloudHSM key store, AWS KMS logs into the associated AWS CloudHSM cluster and creates the key material for the KMS key. It also changes the password to a value that only it knows and remains logged in as long as the AWS CloudHSM key store is connected. Because only the key owner, that is, the CU who created a key, can delete the key, it is unlikely that the key will be deleted from the HSMs accidentally.
However, if the key material for a KMS key is deleted from the HSMs in a cluster, the key state of the KMS key eventually changes to `UNAVAILABLE`. If you attempt to use the KMS key for a cryptographic operation, the operation fails with a `KMSInvalidStateException` exception. Most importantly, any data that was encrypted under the KMS key cannot be decrypted.
Under certain circumstances, you can recover deleted key material by [creating a cluster from a backup](https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-cluster-from-backup.html) that contains the key material. This strategy works only when at least one backup was created while the key existed and before it was deleted.
Use the following process to recover the key material.
1. Find a cluster backup that contains the key material. The backup must also contain all users and keys that you need to support the cluster and its encrypted data.
Use the [DescribeBackups](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DescribeBackups.html) operation to list the backups for a cluster. Then use the backup timestamp to help you select a backup. To limit the output to the cluster that is associated with the AWS CloudHSM key store, use the `Filters` parameter, as shown in the following example.
```
$ aws cloudhsmv2 describe-backups --filters clusterIds=
{
"Backups": [
{
"ClusterId": "cluster-1a23b4cdefg",
"BackupId": "backup-9g87f6edcba",
"CreateTimestamp": 1536667238.328,
"BackupState": "READY"
},
...
]
}
```
1. [Create a cluster from the selected backup](https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-cluster-from-backup.html). Verify that the backup contains the deleted key and other users and keys that the cluster requires.
1. [Disconnect the AWS CloudHSM key store](disconnect-keystore.md) so you can edit its properties.
1. [Edit the cluster ID](update-keystore.md) of the AWS CloudHSM key store. Enter the cluster ID of the cluster that you created from the backup. Because the cluster shares a backup history with the original cluster, the new cluster ID should be valid.
1. [Reconnect the AWS CloudHSM key store](connect-keystore.md).
## How to log in as `kmsuser`
To create and manage the key material in the AWS CloudHSM cluster for your AWS CloudHSM key store, AWS KMS uses the [`kmsuser` crypto user (CU) account](keystore-cloudhsm.md#concept-kmsuser). You [create the `kmsuser` CU account](create-keystore.md#before-keystore) in your cluster and provide its password to AWS KMS when you create your AWS CloudHSM key store.
In general, AWS KMS manages the `kmsuser` account. However, for some tasks, you need to disconnect the AWS CloudHSM key store, log into the cluster as the `kmsuser` CU, and use the [CloudHSM Command Line Interface (CLI)](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli.html).
**Note**
While a custom key store is disconnected, all attempts to create KMS keys in the custom key store or to use existing KMS keys in cryptographic operations will fail. This action can prevent users from storing and accessing sensitive data.
This topic explains how to [disconnect your AWS CloudHSM key store and log in](#login-kmsuser-1) as `kmsuser`, run the AWS CloudHSM command line tool, and [log out and reconnect your AWS CloudHSM key store](#login-kmsuser-2).
**Topics**
+ [
### How to disconnect and log in
](#login-kmsuser-1)
+ [
### How to log out and reconnect
](#login-kmsuser-2)
### How to disconnect and log in
Use the following procedure each time to need to log into an associated cluster as the `kmsuser` crypto user.
**Notes**
The following procedures use the AWS CloudHSM Client SDK 5 command line tool, [CloudHSM CLI](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli.html). The CloudHSM CLI replaces `key-handle` with `key-reference`.
On January 1, 2025, AWS CloudHSM will end support for the Client SDK 3 command line tools, the CloudHSM Management Utility (CMU) and the Key Management Utility (KMU). For more information on the differences between the Client SDK 3 command line tools and the Client SDK 5 command line tool, see [Migrate from Client SDK 3 CMU and KMU to Client SDK 5 CloudHSM CLI](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-migrate-from-kmu-cmu.html) in the *AWS CloudHSM User Guide*.
1. Disconnect the AWS CloudHSM key store, if it is not already disconnected. You can use the AWS KMS console or AWS KMS API.
While your AWS CloudHSM key is connected, AWS KMS is logged in as the `kmsuser`. This prevents you from logging in as `kmsuser` or changing the `kmsuser` password.
For example, this command uses [DisconnectCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_DisconnectCustomKeyStore.html) to disconnect an example key store. Replace the example AWS CloudHSM key store ID with a valid one.
```
$ aws kms disconnect-custom-key-store --custom-key-store-id cks-1234567890abcdef0
```
1. Use the **login** command to login as an admin. Use the procedures described in the [Using CloudHSM CLI](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-getting-started.html#w17aac19c11c13b7) section of the *AWS CloudHSM User Guide*.
```
aws-cloudhsm > login --username admin --role admin
Enter password:
{
"error_code": 0,
"data": {
"username": "admin",
"role": "admin"
}
}
```
1. Use the [https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-user-change-password.html](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-user-change-password.html) command in CloudHSM CLI to change the password of the `kmsuser` account to one that you know. (AWS KMS rotates the password when you connect your AWS CloudHSM key store.) The password must consist of 7-32 alphanumeric characters. It is case-sensitive and cannot contain any special characters.
1. Login as `kmsuser` using the password that you set. For detailed instructions, see the [Using CloudHSM CLI](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-getting-started.html#w17aac19c11c13b7) section of the *AWS CloudHSM User Guide*.
```
aws-cloudhsm > login --username kmsuser --role crypto-user
Enter password:
{
"error_code": 0,
"data": {
"username": "kmsuser",
"role": "crypto-user"
}
}
```
### How to log out and reconnect
Use the following procedure each time you need to log out as the `kmsuser` crypto user and reconnect your key store.
**Notes**
The following procedures use the AWS CloudHSM Client SDK 5 command line tool, [CloudHSM CLI](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli.html). The CloudHSM CLI replaces `key-handle` with `key-reference`.
On January 1, 2025, AWS CloudHSM will end support for the Client SDK 3 command line tools, the CloudHSM Management Utility (CMU) and the Key Management Utility (KMU). For more information on the differences between the Client SDK 3 command line tools and the Client SDK 5 command line tool, see [Migrate from Client SDK 3 CMU and KMU to Client SDK 5 CloudHSM CLI](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-migrate-from-kmu-cmu.html) in the *AWS CloudHSM User Guide*.
1. Perform the task, then use the [https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-logout.html](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-logout.html) command in CloudHSM CLI to log out. If you do not log out, attempts to reconnect your AWS CloudHSM key store will fail.
```
aws-cloudhsm logout
{
"error_code": 0,
"data": "Logout successful"
}
```
1. [Edit the `kmsuser` password setting](update-keystore.md) for the custom key store.
This tells AWS KMS the current password for `kmsuser` in the cluster. If you omit this step, AWS KMS will not be able to log into the cluster as `kmsuser`, and all attempts to reconnect your custom key store will fail. You can use the AWS KMS console or the `KeyStorePassword` parameter of the [UpdateCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_UpdateCustomKeyStore.html) operation.
For example, this command tells AWS KMS that the current password is `tempPassword`. Replace the example password with the actual one.
```
$ aws kms update-custom-key-store --custom-key-store-id cks-1234567890abcdef0 --key-store-password tempPassword
```
1. Reconnect the AWS KMS key store to its AWS CloudHSM cluster. Replace the example AWS CloudHSM key store ID with a valid one. During the connection process, AWS KMS changes the `kmsuser` password to a value that only it knows.
The [ConnectCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_ConnectCustomKeyStore.html) operation returns quickly, but the connection process can take an extended period of time. The initial response does not indicate the success of the connection process.
```
$ aws kms connect-custom-key-store --custom-key-store-id cks-1234567890abcdef0
```
1. Use the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) operation to verify that the AWS CloudHSM key store is connected. Replace the example AWS CloudHSM key store ID with a valid one.
In this example, the connection state field shows that the AWS CloudHSM key store is now connected.
```
$ aws kms describe-custom-key-stores --custom-key-store-id cks-1234567890abcdef0
{
"CustomKeyStores": [
"CustomKeyStoreId": "cks-1234567890abcdef0",
"CustomKeyStoreName": "ExampleKeyStore",
"CloudHsmClusterId": "cluster-1a23b4cdefg",
"TrustAnchorCertificate": "",
"CreationDate": "1.499288695918E9",
"ConnectionState": "CONNECTED"
],
}
```
# External key stores
External key stores allow you to protect your AWS resources using cryptographic keys outside of AWS. This advanced feature is designed for regulated workloads that you must protect with encryption keys stored in an external key management system that you control. External key stores support the [AWS digital sovereignty pledge](https://aws.amazon.com/blogs/security/aws-digital-sovereignty-pledge-control-without-compromise/) to give you sovereign control over your data in AWS, including the ability to encrypt with key material that you own and control outside of AWS.
An *external key store* is a [custom key store](key-store-overview.md#custom-key-store-overview) backed by an *external key manager* that you own and manage outside of AWS. Your external key manager can be a physical or virtual hardware security modules (HSMs), or any hardware-based or software-based system capable of generating and using cryptographic keys. Encryption and decryption operations that use a KMS key in an external key store are performed by your external key manager using your cryptographic key material, a feature known as *hold your own keys* (HYOKs).
AWS KMS never interacts directly with your external key manager, and cannot create, view, manage, or delete your keys. Instead, AWS KMS interacts only with [external key store proxy](#concept-xks-proxy) (XKS proxy) software that you provide. Your external key store proxy mediates all communication between AWS KMS and your external key manager. It transmits all requests from AWS KMS to your external key manager, and transmits responses from your external key manager back to AWS KMS. The external key store proxy also translates generic requests from AWS KMS into a vendor-specific format that your external key manager can understand, allowing you to use external key stores with key managers from a variety of vendors.
You can use KMS keys in an external key store for client-side encryption, including with the [AWS Encryption SDK](https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/). But external key stores are an important resource for server-side encryption, allowing you to protect your AWS resources in multiple AWS services with your cryptographic keys outside of AWS. AWS services that support [customer managed keys](concepts.md#customer-mgn-key) for symmetric encryption also support KMS keys in an external key store. For service support details, see [AWS Service Integration](https://aws.amazon.com/kms/features/#AWS_service_integration).
External key stores allow you to use AWS KMS for regulated workloads where encryption keys must be stored and used outside of AWS. But they are a major departure from the standard shared responsibility model, and require additional operational burdens. The greater risk to availability and latency will, for most customers, exceed the perceived security benefits of external key stores.
External key stores let you control the root of trust. Data encrypted under KMS keys in your external key store can be decrypted only by using the external key manager that you control. If you temporarily revoke access to your external key manager, such as by disconnecting the external key store or disconnecting your external key manager from the external key store proxy, AWS loses all access to your cryptographic keys until you restore it. During that interval, ciphertext encrypted under your KMS keys can't be decrypted. If you permanently revoke access to your external key manager, all ciphertext encrypted under a KMS key in your external key store becomes unrecoverable. The only exceptions are AWS services that briefly cache the [data keys](data-keys.md) protected by your KMS keys. These data keys continue to work until you deactivate the resource or the cache expires. For details, see [How unusable KMS keys affect data keys](unusable-kms-keys.md).
External key stores unblock the few use cases for regulated workloads where encryption keys must remain solely under your control and inaccessible to AWS. But this is a major change in the way you operate cloud-based infrastructure and a significant shift in the shared responsibility model. For most workloads, the additional operational burden and greater risks to availability and performance will exceed the perceived security benefits of external key stores.
**Do I need an external key store?**
For most users, the default AWS KMS key store, which is protected by [FIPS 140-3 Security Level 3 validated hardware security modules](https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/4884), fulfills their security, control, and regulatory requirements. External key store users incur substantial cost, maintenance, and troubleshooting burden, and risks to latency, availability and reliability.
When considering an external key store, take some time to understand the alternatives, including an [AWS CloudHSM key store](keystore-cloudhsm.md) backed by an AWS CloudHSM cluster that you own and manage, and KMS keys with [imported key material](importing-keys.md) that you generate in your own HSMs and can delete from KMS keys on demand. In particular, importing key material with a very brief expiration interval might provide a similar level of control without the performance or availability risks.
An external key store might be the right solution for your organization if you have the following requirements:
+ You are required to use cryptographic keys in your on-premises key manager or a key manager outside of AWS that you control.
+ You must demonstrate that your cryptographic keys are retained solely under your control outside of the cloud.
+ You must encrypt and decrypt using cryptographic keys with independent authorization.
+ Key material must be subject to a secondary, independent audit path.
If you choose an external key store, limit its use to workloads that require protection with cryptographic keys outside of AWS.
**Shared responsibility model**
Standard KMS keys use key material that is generated and used in HSMs that AWS KMS owns and manages. You establish the access control policies on your KMS keys and configure AWS services that use KMS keys to protect your resources. AWS KMS assumes responsibility for the security, availability, latency, and durability of the key material in your KMS keys.
KMS keys in external key stores rely on key material and operations in your external key manager. As such, the balance of responsibility shifts in your direction. You are responsible for the security, reliability, durability, and performance of the cryptographic keys in your external key manager. AWS KMS is responsible for responding promptly to requests and communicating with your external key store proxy, and for maintaining our security standards. To ensure that every external key store ciphertext at least as strong than standard AWS KMS ciphertext, AWS KMS first encrypts all plaintext with AWS KMS key material specific to your KMS key, and then sends it to your external key manager for encryption with your external key, a procedure known as [*double encryption*](#concept-double-encryption). As a result, neither AWS KMS nor the owner of the external key material can decrypt double-encrypted ciphertext alone.
You are responsible for maintaining an external key manager that meet your regulatory and performance standards, for supplying and maintaining an external key store proxy that conforms to the [AWS KMS External Key Store Proxy API Specification](https://github.com/aws/aws-kms-xksproxy-api-spec/), and for ensuring the availability and durability of your key material. You must also create, configure, and maintain an external key store. When errors arise that are caused by components that you maintain, you must be prepared to identify and resolve the errors so that AWS services can access your resources without undue disruption. AWS KMS provides [troubleshooting guidance](xks-troubleshooting.md) to help you determine the cause of problems and the most likely resolutions.
Review the [Amazon CloudWatch metrics and dimensions](monitoring-cloudwatch.md#kms-metrics) that AWS KMS records for external key stores. AWS KMS strongly recommends that you create CloudWatch alarms to monitor your external key store so you can detect the early signs of performance and operational problems before they occur.
**What is changing?**
External key stores support only symmetric encryption KMS keys. Within AWS KMS, you use and manage KMS keys in an external key store in much the same way that you manage other [customer managed keys](concepts.md#customer-mgn-key), including [setting access control policies](authorize-xks-key-store.md) and [monitoring key use](monitoring-overview.md). You use the same APIs with the same parameters to request a cryptographic operation with a KMS key in an external key store that you use for any KMS key. Pricing is also the same as for standard KMS keys. For details, see [KMS keys in external key stores](keystore-external-key-manage.md) and [AWS Key Management Service Pricing](https://aws.amazon.com/kms/pricing/).
However, with external key stores the following principles change:
+ You are responsible for the availability, durability, and latency of key operations.
+ You are responsible for all costs for developing, purchasing, operating, and licensing your external key manager system.
+ You can implement [independent authorization](authorize-xks-key-store.md#xks-proxy-authorization) of all requests from AWS KMS to your external key store proxy.
+ You can monitor, audit, and log all operations of your external key store proxy, and all operations of your external key manager related to AWS KMS requests.
**Where do I start?**
To create and manage an external key store, you need to [choose your external key store proxy connectivity option](choose-xks-connectivity.md), [assemble the prerequisites](create-xks-keystore.md#xks-requirements), and [create and configure your external key store](create-xks-keystore.md).
**Quotas**
AWS KMS allows up to [10 custom key stores](resource-limits.md) in each AWS account and Region, including both [AWS CloudHSM key stores](https://docs.aws.amazon.com/kms/latest/developerguide/keystore-cloudhsm.html) and [external key stores](https://docs.aws.amazon.com/kms/latest/developerguide/keystore-external.html), regardless of their connection state. In addition, there are AWS KMS request quotas on the [use of KMS keys in an external key store](requests-per-second.md#rps-key-stores).
If you choose [VPC proxy connectivity](#concept-xks-connectivity) for your external key store proxy, there might also be quotas on the required components, such as VPCs, subnets, and network load balancers. For information about these quotas, use the [Service Quotas console](https://console.aws.amazon.com/servicequotas/home).
**Regions**
To minimize network latency, create your external key store components in the AWS Region closest to your [external key manager](#concept-ekm). If possible, choose a Region with a network round-trip time (RTT) of 35 milliseconds or less.
External key stores are supported in all AWS Regions in which AWS KMS is supported except for China (Beijing) and China (Ningxia).
**Unsupported features**
AWS KMS does not support the following features in custom key stores.
+ [Asymmetric KMS keys](symmetric-asymmetric.md)
+ [HMAC KMS keys](hmac.md)
+ [KMS keys with imported key material](importing-keys.md)
+ [Automatic key rotation](rotate-keys.md)
+ [Multi-Region keys](multi-region-keys-overview.md)
**Learn more**:
+ [Announcing AWS KMS External Key Store](https://aws.amazon.com/blogs/aws/announcing-aws-kms-external-key-store-xks/) in the *AWS News Blog*.
## External key store concepts
Learn the basic terms and concepts used in external key stores.
### External key store
An *external key store* is an AWS KMS [custom key store](key-store-overview.md#custom-key-store-overview) backed by an external key manager outside of AWS that you own and manage. Each KMS key in an external key store is associated with an [external key](#concept-external-key) in your external key manager. When you use a KMS key in an external key store for encryption or decryption, the operation is performed in your external key manager using your external key, an arrangement known as *Hold your Own Keys* (HYOK). This feature is designed for organizations that are required to maintain their cryptographic keys in their own external key manager.
External key stores ensure that the cryptographic keys and operations that protect your AWS resources remain in your external key manager under your control. AWS KMS sends requests to your external key manager to encrypt and decrypt data, but AWS KMS cannot create, delete, or manage any external keys. All requests from AWS KMS to your external key manager are mediated by an [external key store proxy](#concept-xks-proxy) software component that you supply, own, and manage.
AWS services that support AWS KMS [customer managed keys](concepts.md) can use the KMS keys in your external key store to protect your data. As a result, your data is ultimately protected by your keys using your encryption operations in your external key manager.
The KMS keys in an external key store have fundamentally different trust models, [shared responsibility arrangements](#xks-shared-responsibility), and performance expectations than standard KMS keys. With external key stores, you are responsible for the security and integrity of the key material and the cryptographic operations. The availability and latency of KMS keys in an external key store are affected by the hardware, software, networking components, and the distance between AWS KMS and your external key manager. You are also likely to incur additional costs for your external key manager and for the networking and load balancing infrastructure you need for your external key manager to communicate with AWS KMS
You can use your external key store as part of your broader data protection strategy. For each AWS resource that you protect, you can decide which require a KMS key in an external key store and which can be protected by a standard KMS key. This gives you the flexibility to chose KMS keys for specific data classifications, applications, or projects.
### External key manager
An *external key manager* is a component outside of AWS that can generate 256-bit AES symmetric keys and perform symmetric encryption and decryption. The external key manager for an external key store can be a physical hardware security module (HSM), a virtual HSM, or a software key manager with or without an HSM component. It can be located anywhere outside of AWS, including on your premises, in a local or remote data center, or in any cloud. Your external key store can be backed by a single external key manager or multiple related key manager instances that share cryptographic keys, such as an HSM cluster. External key stores are designed to support a variety of external managers from different vendors. For details about connecting to your external key manager, see [Choose an external key store proxy connectivity option](choose-xks-connectivity.md).
### External key
Each KMS key in an external key store is associated with a cryptographic key in your [external key manager](#concept-ekm) known as an *external key*. When you encrypt or decrypt with a KMS key in your external key store, the cryptographic operation is performed in your [external key manager](#concept-ekm) using your external key.
**Warning**
The external key is essential to the operation of the KMS key. If the external key is lost or deleted, ciphertext encrypted under the associated KMS key is unrecoverable.
For external key stores, an external key must be a 256-bit AES key that is enabled and can perform encryption and decryption. For detailed external key requirements, see [Requirements for a KMS key in an external key store](create-xks-keys.md#xks-key-requirements).
AWS KMS cannot create, delete, or manage any external keys. Your cryptographic key material never leaves your external key manager.When you create a KMS key in an external key store, you provide the ID of an external key (`XksKeyId`). You cannot change the external key ID associated with a KMS key, although your external key manager can rotate the key material associated with the external key ID.
In addition to your external key, a KMS key in an external key store also has AWS KMS key material. Data protected by the KMS key is encrypted first by AWS KMS using the AWS KMS key material, and then by your external key manager using your external key. This [double encryption](#concept-double-encryption) process ensures that ciphertext protected by your KMS key is always at least as strong as ciphertext protected only by AWS KMS.
Many cryptographic keys have different types of identifiers. When creating a KMS key in an external key store, provide the ID of the external key that the [external key store proxy](#concept-xks-proxy) uses to refer to the external key. If you use the wrong identifier, your attempt to create a KMS key in your external key store fails.
### External key store proxy
The *external key store proxy* ("XKS proxy") is a customer-owned and customer-managed software application that mediates all communication between AWS KMS and your external key manager. It also translates generic AWS KMS requests into a format that your vendor-specific external key manager understand. An external key store proxy is required for an external key store. Each external key store is associated with one external key store proxy.
![\[External key store proxy\]](http://docs.aws.amazon.com/kms/latest/developerguide/images/xks-proxy-concept-40.png)
AWS KMS cannot create, delete, or manage any external keys. Your cryptographic key material never leaves your external key manager. All communication between AWS KMS and your external key manager is mediated by your external key store proxy. AWS KMS sends requests to the external key store proxy and receives responses from the external key store proxy. The external key store proxy is responsible for transmitting requests from AWS KMS to your external key manager and transmitting responses from your external key manager back to AWS KMS
You own and manage the external key store proxy for your external key store, and you are responsible for its maintenance and operation. You can develop your external key store proxy based on the open-source [external key store proxy API specification](https://github.com/aws/aws-kms-xksproxy-api-spec/) that AWS KMS publishes or purchase a proxy application from a vendor. Your external key store proxy might be included in your external key manager. To support proxy development, AWS KMS also provides a sample external key store proxy ([aws-kms-xks-proxy](https://github.com/aws-samples/aws-kms-xks-proxy)) and a test client ([xks-kms-xksproxy-test-client](https://github.com/aws-samples/aws-kms-xksproxy-test-client)) that verifies that your external key store proxy conforms to the specification.
To authenticate to AWS KMS, the proxy uses server-side TLS certificates. To authenticate to your proxy, AWS KMS signs all requests to your external key store proxy with a SigV4 [proxy authentication credential](#concept-xks-credential).
Your external key store proxy must support HTTP/1.1 or later and TLS 1.2 or later with at least one of the following cipher suites:
+ TLS\$1AES\$1256\$1GCM\$1SHA384 (TLS 1.3)
+ TLS\$1CHACHA20\$1POLY1305\$1SHA256 (TLS 1.3)
**Note**
The AWS GovCloud (US) Region does not support TLS\$1CHACHA20\$1POLY1305\$1SHA256.
+ TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1GCM\$1SHA384 (TLS 1.2)
+ TLS\$1ECDHE\$1ECDSA\$1WITH\$1AES\$1256\$1GCM\$1SHA384 (TLS 1.2)
To create and use the KMS keys in your external key store, you must first [connect the external key store](xks-connect-disconnect.md) to its external key store proxy. You can also disconnect your external key store from its proxy on demand. When you do, all KMS keys in the external key store become [unavailable](key-state.md); they cannot be used in any cryptographic operation.
### External key store proxy connectivity
The external key store proxy connectivity ("XKS proxy connectivity") describes the method that AWS KMS uses to communicate with your external key store proxy.
You specify your proxy connectivity option when you create your external key store, and it becomes a property of the external key store. You can change your proxy connectivity option by updating the custom key store property, but you must be certain that your external key store proxy can still access the same external keys.
AWS KMS supports the following connectivity options.
+ [Public endpoint connectivity](choose-xks-connectivity.md#xks-connectivity-public-endpoint) — AWS KMS sends requests for your external key store proxy over the internet to a public endpoint that you control. This option is simple to create and maintain, but it might not fulfill the security requirements for every installation.
+ [VPC endpoint service connectivity](choose-xks-connectivity.md#xks-vpc-connectivity) — AWS KMS sends requests to a Amazon Virtual Private Cloud (Amazon VPC) endpoint service that you create and maintain. You can host your external key store proxy inside your Amazon VPC, or host your external key store proxy outside of AWS and use the Amazon VPC only for communication. You can also connect your external key store to an Amazon VPC endpoint service owned by another AWS account.
For details about the external key store proxy connectivity options, see [Choose an external key store proxy connectivity option](choose-xks-connectivity.md).
### External key store proxy authentication credential
To authenticate to your external key store proxy, AWS KMS signs all requests to your external key store proxy with a [Signature V4 (SigV4)](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html) authentication credential. You establish and maintain the authentication credential on your proxy, then provide this credential to AWS KMS when you create your external store.
**Note**
The SigV4 credential that AWS KMS uses to sign requests to the XKS proxy is unrelated to any SigV4 credentials associated with AWS Identity and Access Management principals in your AWS accounts. Do not reuse any IAM SigV4 credentials for your external key store proxy.
Each proxy authentication credential has two parts. You must provide both parts when creating an external key store or updating the authentication credential for your external key store.
+ Access key ID: Identifies the secret access key. You can provide this ID in plaintext.
+ Secret access key: The secret part of the credential. AWS KMS encrypts the secret access key in the credential before storing it.
You can [edit the credential setting](update-xks-keystore.md) at any time, such as when you enter incorrect values, when you change your credential on the proxy, or when your proxy rotates the credential. For technical details about AWS KMS authentication to the external key store proxy, see [Authentication](https://github.com/aws/aws-kms-xksproxy-api-spec/blob/main/xks_proxy_api_spec.md#authentication) in the AWS KMS External Key Store Proxy API Specification.
To allow you to rotate your credential without disrupting the AWS services that use KMS keys in your external key store, we recommend that the external key store proxy support at least two valid authentication credentials for AWS KMS. This ensures that your previous credential continues to work while you provide your new credential to AWS KMS.
To help you track the age of your proxy authentication credential, AWS KMS defines an Amazon CloudWatch metric, [XksProxyCredentialAge](monitoring-cloudwatch.md#metric-xks-proxy-credential-age). You can use this metric to create a CloudWatch alarm that notifies you when the age of your credential reaches a threshold you establish.
### Proxy APIs
To support an AWS KMS external key store, an [external key store proxy](#concept-xks-proxy) must implement the required proxy APIs as described in the [AWS KMS External Key Store Proxy API Specification](https://github.com/aws/aws-kms-xksproxy-api-spec/). These proxy API requests are the only requests that AWS KMS sends to the proxy. Although you never send these requests directly, knowing about them might help you fix any issues that might arise with your external key store or its proxy. For example, AWS KMS includes information about the latency and success rates of these API calls in its [Amazon CloudWatch metrics](monitoring-cloudwatch.md) for external key stores. For details, see [Monitor external key stores](xks-monitoring.md).
The following table lists and describes each of the proxy APIs. It also includes the AWS KMS operations that trigger a call to the proxy API and any AWS KMS operation exceptions related to the proxy API.
| Proxy API | Description | Related AWS KMS operations |
| --- | --- | --- |
| Decrypt | AWS KMS sends the ciphertext to be decrypted, and the ID of the [external key](#concept-external-key) to use. The required encryption algorithm is AES\$1GCM. | [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html), [ReEncrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReEncrypt.html) |
| Encrypt | AWS KMS sends data to be encrypted, and the ID of the [external key](#concept-external-key) to use. The required encryption algorithm is AES\$1GCM. | [Encrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html), [GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html), [GenerateDataKeyWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html), [ReEncrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReEncrypt.html) |
| GetHealthStatus | AWS KMS requests information about the status of the proxy and your external key manager. The status of each external key manager can be one of the following.[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/kms/latest/developerguide/keystore-external.html) | [CreateCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateCustomKeyStore.html) (for [public endpoint connectivity](choose-xks-connectivity.md#xks-connectivity-public-endpoint)), [ConnectCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_ConnectCustomKeyStore.html) (for [VPC endpoint service connectivity](choose-xks-connectivity.md#xks-vpc-connectivity))If all external key manager instances are `Unavailable`, attempts to create or connect the key store fail with [`XksProxyUriUnreachableException`](xks-troubleshooting.md#fix-xks-latency). |
| GetKeyMetadata | AWS KMS requests information about the [external key](#concept-external-key) associated with a KMS key in your external key store. The response includes the key spec (`AES_256`), the key usage (`[ENCRYPT, DECRYPT]`), and the whether the external key is `ENABLED` or `DISABLED`. | [CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html)If the key spec is not `AES_256`, or the key usage is not `[ENCRYPT, DECRYPT]`, or the status is `DISABLED`, the `CreateKey` operation fails with `XksKeyInvalidConfigurationException`. |
### Double encryption
Data encrypted by a KMS key in an external key store is encrypted twice. First, AWS KMS encrypts the data with AWS KMS key material specific to the KMS key. Then the AWS KMS-encrypted ciphertext is encrypted by your [external key manager](#concept-ekm) using your [external key](#concept-external-key). This process is known as *double encryption*.
Double encryption ensures that data encrypted by a KMS key in an external key store is at least as strong as ciphertext encrypted by a standard KMS key. It also protects your plaintext in transit from AWS KMS to your external key store proxy. With double encryption, you retain full control of your ciphertexts. If you permanently revoke AWS access to your external key through your external proxy, any ciphertext remaining in AWS is effectively crypto-shredded.
![\[Double encryption of data protected by a KMS key in an external key store\]](http://docs.aws.amazon.com/kms/latest/developerguide/images/xks-double-encrypt-40.png)
To enable double encryption, each KMS key in an external key store has *two* cryptographic backing keys:
+ An AWS KMS key material unique to the KMS key. This key material is generated and only used in AWS KMS [FIPS 140-3 Security Level 3](https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/4884) certified hardware security modules (HSMs).
+ An [external key](#concept-external-key) in your external key manager.
Double encryption has the following effects:
+ AWS KMS cannot decrypt any ciphertext encrypted by a KMS key in an external key store without access to your external keys via your external key store proxy.
+ You cannot decrypt any ciphertext encrypted by a KMS key in an external key store outside of AWS, even if you have its external key material.
+ You cannot recreate a KMS key that was deleted from an external key store, even if you have its external key material. Each KMS key has unique metadata that it includes in the symmetric ciphertext. A new KMS key would not be able to decrypt ciphertext encrypted by the original key, even if it used the same external key material.
For an example of double encryption in practice, see [How external key stores work](#xks-how-it-works).
## How external key stores work
Your [external key store](#concept-external-key-store), [external key store proxy,](#concept-xks-proxy) and [external key manager](#concept-ekm) work together to protect your AWS resources. The following procedure depicts the encryption workflow of a typical AWS service that encrypts each object under a unique data key protected by a KMS key. In this case, you've chosen a KMS key in an external key store to protect the object. The example shows how AWS KMS uses [double encryption](#concept-double-encryption) to protect the data key in transit and ensure that ciphertext generated by a KMS key in an external key store is always at least as strong as ciphertext encrypted by a standard symmetric KMS key with key material in AWS KMS.
The encryption methods used by each actual AWS service that integrates with AWS KMS vary. For details, see the "Data protection" topic in the Security chapter of the AWS service documentation.
![\[How external key stores work\]](http://docs.aws.amazon.com/kms/latest/developerguide/images/xks-how-it-works-jan26.png)
1. You add a new object to your AWS service resource. To encrypt the object, the AWS service sends a [GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) request to AWS KMS using a KMS key in your external key store.
1. AWS KMS generates a 256-bit symmetric [data key](data-keys.md) and prepares to send a copy of the plaintext data key to your external key manager via your external key store proxy. AWS KMS begins the [double encryption](#concept-double-encryption) process by encrypting the plaintext data key with the [AWS KMS key material](#concept-double-encryption) associated with the KMS key in the external key store.
1. AWS KMS sends an [encrypt](#concept-proxy-apis) request to the external key store proxy associated with the external key store. The request includes the data key ciphertext to be encrypted and the ID of the [external key](#concept-external-key) that is associated with the KMS key. AWS KMS signs the request using the [proxy authentication credential](#concept-xks-credential) for your external key store proxy.
The plaintext copy of the data key is not sent to the external key store proxy.
1. The external key store proxy authenticates the request, and then passes the encrypt request to your external key manager.
Some external key store proxies also implement an optional [authorization policy](authorize-xks-key-store.md#xks-proxy-authorization) that allows only selected principals to perform operations under specific conditions.
1. Your external key manager encrypts the data key ciphertext using the specified external key. The external key manager returns the double-encrypted data key to your external key store proxy, which returns it to AWS KMS.
1. AWS KMS returns the plaintext data key and the double-encrypted copy of that data key to the AWS service.
1. The AWS service uses the plaintext data key to encrypt the resource object, destroys the plaintext data key, and stores the encrypted data key with the encrypted object.
Some AWS services might cache the plaintext data key to use for multiple objects, or to reuse while the resource is in use. For details, see [How unusable KMS keys affect data keys](unusable-kms-keys.md).
To decrypt the encrypted object, the AWS service must send the encrypted data key back to AWS KMS in a [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) request. To decrypt the encrypted data key, AWS KMS must send the encrypted data key back to your external key store proxy with the ID of the external key. If the decrypt request to the external key store proxy fails for any reason, AWS KMS cannot decrypt the encrypted data key, and the AWS service cannot decrypt the encrypted object.
# Control access to your external key store
All AWS KMS access control features — [key policies](key-policies.md), [IAM policies](iam-policies.md), and [grants](grants.md) — that you use with standard KMS keys, work the same way for KMS keys in an external key store. You can use IAM policies to control access to the API operations that create and manage external key stores. You use IAM policies and key policies to control access to the AWS KMS keys in your external key store. You can also use [service control policies](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_scps.html) for your AWS organization and [VPC endpoint policies](https://docs.aws.amazon.com/vpc/latest/privatelink/interface-endpoints.html#edit-vpc-endpoint-policy) to control access to KMS keys in your external key store.
We recommend that you provide users and roles only the permissions that they require for the tasks that they are likely to perform.
**Topics**
+ [
## Authorizing external key store managers
](#authorize-xks-managers)
+ [
## Authorizing users of KMS keys in external key stores
](#authorize-xks-users)
+ [
## Authorizing AWS KMS to communicate with your external key store proxy
](#allowlist-kms-xks)
+ [
## External key store proxy authorization (optional)
](#xks-proxy-authorization)
+ [
## mTLS authentication (deprecated)
](#xks-mtls)
## Authorizing external key store managers
Principals who create and manage an external key store need permissions to the custom key store operations. The following list describes the minimum permissions required for external key store managers. Because a custom key store is not an AWS resource, you cannot provide permission to an external key store for principals in other AWS accounts.
+ `kms:CreateCustomKeyStore`
+ `kms:DescribeCustomKeyStores`
+ `kms:ConnectCustomKeyStore`
+ `kms:DisconnectCustomKeyStore`
+ `kms:UpdateCustomKeyStore`
+ `kms:DeleteCustomKeyStore`
To create an external key store with [Amazon VPC endpoint service connectivity](choose-xks-connectivity.md#xks-vpc-connectivity) and the VPC endpoint service is owned by a different AWS account, you'll also need the following permission:
+ `ec2:DescribeVPCEndpointServices`
Principals who create an external key store need permission to create and configure the external key store components. Principals can create external key stores only in their own accounts. To create an external key store with [VPC endpoint service connectivity](choose-xks-connectivity.md#xks-vpc-connectivity), principals must have permission to create the following components:
+ An Amazon VPC
+ Public and private subnets
+ A network load balancer and target group
+ An Amazon VPC endpoint service
For details, see [Identity and access management for Amazon VPC](https://docs.aws.amazon.com/vpc/latest/userguide/security-iam.html), [Identity and access management for VPC endpoints and VPC endpoint services](https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints-iam.html) and [Elastic Load Balancing API permissions](https://docs.aws.amazon.com/elasticloadbalancing/latest/userguide/elb-api-permissions.html).
## Authorizing users of KMS keys in external key stores
Principals who create and manage AWS KMS keys in your external key store require [the same permissions](create-keys.md#create-key-permissions) as those who create and manage any KMS key in AWS KMS. The [default key policy](key-policy-default.md) for KMS key in an external key store is identical to the default key policy for KMS keys in AWS KMS. [Attribute-based access control](abac.md) (ABAC), which uses tags and aliases to control access to KMS keys, is also effective on KMS keys in an external key stores.
Principals who use the KMS keys in your custom key store for [cryptographic operations](manage-cmk-keystore.md#use-cmk-keystore) need permission to perform the cryptographic operation with the KMS key, such as [kms:Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html). You can provide these permissions in an IAM or key policy. But, they do not need any additional permissions to use a KMS key in a custom key store.
To set a permission that applies only to KMS keys in an external key store, use the [`kms:KeyOrigin`](conditions-kms.md#conditions-kms-key-origin) policy condition with a value of `EXTERNAL_KEY_STORE`. You can use this condition to limit the [kms:CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) permission or any permission that is specific to a KMS key resource. For example, the following IAM policy allows the identity to which it is attached to call the specified operations on all KMS keys in the account, provided that the KMS keys are in an external key store. Notice that you can limit the permission to KMS keys in an external key store, and KMS keys in an AWS account, but not to any particular external key store in the account.
```
{
"Sid": "AllowKeysInExternalKeyStores",
"Effect": "Allow",
"Action": [
"kms:Encrypt",
"kms:Decrypt",
"kms:ReEncrypt*",
"kms:GenerateDataKey*",
"kms:DescribeKey"
],
"Resource": "arn:aws:kms:us-west-2:111122223333:key/*",
"Condition": {
"StringEquals": {
"kms:KeyOrigin": "EXTERNAL_KEY_STORE"
}
}
}
```
## Authorizing AWS KMS to communicate with your external key store proxy
AWS KMS communicates with your external key manager only through the [external key store proxy](keystore-external.md#concept-xks-proxy) that you provide. AWS KMS authenticates to your proxy by signing its requests using the [Signature Version 4 (SigV4) process](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html) with the [external key store proxy authentication credential](keystore-external.md#concept-xks-credential) that you specify. If you are using [public endpoint connectivity](choose-xks-connectivity.md#xks-connectivity-public-endpoint) for your external key store proxy, AWS KMS does not require any additional permissions.
However, if you are using [VPC endpoint service connectivity](choose-xks-connectivity.md#xks-vpc-connectivity), you must give AWS KMS permission to create an interface endpoint to your Amazon VPC endpoint service. This permission is required regardless of whether the external key store proxy is in your VPC or the external key store proxy is located elsewhere, but uses the VPC endpoint service to communicate with AWS KMS.
To allow AWS KMS to create an interface endpoint, use the [Amazon VPC console](https://docs.aws.amazon.com/vpc/latest/privatelink/configure-endpoint-service.html#add-remove-permissions) or the [ModifyVpcEndpointServicePermissions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyVpcEndpointServicePermissions.html) operation. Allow permissions for the following principal: `cks.kms..amazonaws.com`.
If your Amazon VPC endpoint service is owned by a different AWS account other than the AWS account owning the external key store (XKS), you’ll also need to allow XKS access to the VPC endpoint service. To do so, [allowlist the XKS AWS account ID as a principal](https://docs.aws.amazon.com/vpc/latest/privatelink/configure-endpoint-service.html#add-remove-permissions) for the Amazon VPC endpoint service.
------
#### [ Same AWS account ]
When your VPC endpoint service is owned by the same AWS account as your external key store, you must add AWS KMS to the **Allow principals** list for your VPC endpoint service.
The following example uses the [https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-vpc-endpoint-service-permissions.html](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-vpc-endpoint-service-permissions.html) AWS CLI command to allow AWS KMS to connect to the specified VPC endpoint service in the US West (Oregon) (us-west-2) Region. Before using this command, replace the Amazon VPC service ID and AWS Region with valid values for your configuration.
```
modify-vpc-endpoint-service-permissions
--service-id vpce-svc-12abc34567def0987
--add-allowed-principals '["cks.kms.us-west-2.amazonaws.com"]'
```
To remove this permission, use the [Amazon VPC console](https://docs.aws.amazon.com/vpc/latest/privatelink/configure-endpoint-service.html#add-remove-permissions) or the [ModifyVpcEndpointServicePermissions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyVpcEndpointServicePermissions.html) with the `RemoveAllowedPrincipals` parameter.
------
#### [ Cross AWS account ]
When your VPC endpoint service is owned by the another AWS account, you must add both AWS KMS and your external key store to the **Allow principals** list for your VPC endpoint service.
The following example uses the [https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-vpc-endpoint-service-permissions.html](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-vpc-endpoint-service-permissions.html) AWS CLI command to allow both AWS KMS and your external key store (XKS) to connect to the specified VPC endpoint service in the US West (Oregon) (us-west-2) Region. Before using this command, replace the Amazon VPC service ID, AWS Region, and IAM principal ARN with valid values for your configuration. The IAM principal should be replaced with a principal in the XKS owner AWS account.
In this example, `arn:aws:iam::123456789012:role/cks_role` is the IAM principal in the XKS owner account, which will be used to create, update, or connect the XKS to your VPC endpoint service. If you would like to allow all principals in the XKS owner account to access your VPC endpoint service, you can specify `arn:aws:iam::123456789012:root`.
```
modify-vpc-endpoint-service-permissions
--service-id vpce-svc-12abc34567def0987
--add-allowed-principals '["cks.kms.us-west-2.amazonaws.com", "arn:aws:iam::123456789012:role/cks_role"]'
```
To remove this permission, use the [Amazon VPC console](https://docs.aws.amazon.com/vpc/latest/privatelink/configure-endpoint-service.html#add-remove-permissions) or the [ModifyVpcEndpointServicePermissions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyVpcEndpointServicePermissions.html) with the `RemoveAllowedPrincipals` parameter.
------
## External key store proxy authorization (optional)
Some external key store proxies implement authorization requirements for the use of its external keys. An external key store proxy is permitted, but not required, to design and implement an authorization scheme that allows particular users to request particular operations only under certain conditions. For example, a proxy might be configured to allow user A to encrypt with a particular external key, but not to decrypt with it.
Proxy authorization is independent of the [SigV4-based proxy authentication](keystore-external.md#concept-xks-credential) that AWS KMS requires for all external key store proxies. It is also independent of the key policies, IAM policies, and grants that authorize access to operations affecting the external key store or its KMS keys.
To enable authorization by the external key store proxy, AWS KMS includes metadata in each [proxy API request](keystore-external.md#concept-proxy-apis), including the caller, the KMS key, the AWS KMS operation, the AWS service (if any). The request metadata for version 1 (v1) of the external key proxy API is as follows.
```
"requestMetadata": {
"awsPrincipalArn": string,
"awsSourceVpc": string, // optional
"awsSourceVpce": string, // optional
"kmsKeyArn": string,
"kmsOperation": string,
"kmsRequestId": string,
"kmsViaService": string // optional
}
```
For example, you might configure your proxy to allow requests from a particular principal (`awsPrincipalArn`), but only when the request is made on the principal's behalf by a particular AWS service (`kmsViaService`).
If proxy authorization fails, the related AWS KMS operation fails with a message that explains the error. For details , see [Proxy authorization issues](xks-troubleshooting.md#fix-xks-authorization).
## mTLS authentication (deprecated)
Prior versions of this guide mentioned *mutual Transport Layer Security* (mTLS) as an optional, secondary authentication mechanism to authenticate requests from AWS KMS. With mTLS, both parties (AWS KMS as client and the XKS proxy as server) communicating over a TLS channel use certificates to authenticate to each other.
However, changes to the [Chrome Root Program Policy (Section 4.2.2)](https://googlechrome.github.io/chromerootprogram/policy-archive/policy-version-1-7/#422-pki-hierarchies-included-in-the-chrome-root-store) prohibit publicly trusted root CAs included in the Chrome Root Store from issuing certificates with the clientAuth Extended Key Usage (EKU) extension after June 15th, 2026. As a result, AWS KMS can no longer obtain a client certificate suitable for mTLS from [Amazon Trust Services](https://www.amazontrust.com/repository/). Any XKS proxy used to create a new external key store in AWS KMS after March 16th, 2026 must not require mTLS. After June 15th, 2026, any XKS proxy configured to require mTLS will be unable to communicate with AWS KMS. Customers must rely on SigV4 authentication to verify that requests originate from AWS KMS. For more information, see [External key store proxy authentication credential](keystore-external.md#concept-xks-credential).
# Choose an external key store proxy connectivity option
Before creating your external key store, choose the connectivity option that determines how AWS KMS communicates with your external key store components. The connectivity option that you choose determines the remainder of the planning process.
If you are creating an external key store, you need to determine how AWS KMS communicates with your [external key store proxy](keystore-external.md#concept-xks-proxy). This choice will determine which components you need and how you configure them. AWS KMS supports the following connectivity options.
+ [Public endpoint connectivity](#xks-connectivity-public-endpoint)
+ [VPC endpoint service connectivity](#xks-vpc-connectivity)
Choose the option that meets your performance and security goals.
Before you begin, [confirm that you need an external key store](keystore-external.md#do-i-need-xks). Most customer can use KMS keys backed by AWS KMS key material.
**Considerations**
+ If your external key store proxy is built into your external key manager, your connectivity might be predetermined. For guidance, consult the documentation for your external key manager or external key store proxy.
+ You can [change your external key store proxy connectivity option](update-xks-keystore.md) even on an operating external key store. However, the process must be carefully planned and executed to minimize disruption, avoid errors, and ensure continued access to the cryptographic keys that encrypt your data.
## Public endpoint connectivity
AWS KMS connects to the external key store proxy (XKS proxy) over the internet using a public endpoint.
This connectivity option is easier to set up and maintain, and it aligns well with some models of key management. However, it might not fulfill the security requirements of some organizations.
![\[Public endpoint connectivity\]](http://docs.aws.amazon.com/kms/latest/developerguide/images/xks-public-endpoint-60.png)
**Requirements**
If you choose public endpoint connectivity, the following are required.
+ Your external key store proxy must be reachable at a publicly routable endpoint.
+ You can use the same public endpoint for multiple external key stores provided that they use different [proxy URI path](create-xks-keystore.md#require-path) values.
+ You cannot use the same endpoint for an external key store with public endpoint connectivity and any external key store with VPC endpoint services connectivity in the same AWS Region, even if the key stores are in different AWS accounts.
+ You must obtain a TLS certificate issued by a public certificate authority supported for external key stores. For a list, see [Trusted Certificate Authorities](https://github.com/aws/aws-kms-xksproxy-api-spec/blob/main/TrustedCertificateAuthorities).
The subject common name (CN) on the TLS certificate must match the domain name in the [proxy URI endpoint](create-xks-keystore.md#require-endpoint) for the external key store proxy. For example, if the public endpoint is `https://myproxy.xks.example.com`, the TLS, the CN on the TLS certificate must be `myproxy.xks.example.com` or `*.xks.example.com`.
+ Ensure that any firewalls between AWS KMS and the external key store proxy allow traffic to and from port 443 on the proxy. AWS KMS communicates on port 443 over IPv4. This value is not configurable.
For all requirements for an external key store, see the [Assemble the prerequisites](create-xks-keystore.md#xks-requirements).
## VPC endpoint service connectivity
AWS KMS connects to the external key store proxy (XKS proxy) by creating an interface endpoint to an Amazon VPC endpoint service that you create and configure. You are responsible for [creating the VPC endpoint service](vpc-connectivity.md) and for connecting your VPC to your external key manager.
Your endpoint service can use any of the [supported network-to-Amazon VPC options](https://docs.aws.amazon.com/whitepapers/latest/aws-vpc-connectivity-options/network-to-amazon-vpc-connectivity-options.html) for communications, including [AWS Direct Connect](https://docs.aws.amazon.com/directconnect/latest/UserGuide/).
This connectivity option is more complicated to set up and maintain. But it uses AWS PrivateLink, which enables AWS KMS to privately connect to your Amazon VPC and your external key store proxy without using the public internet.
You can locate your external key store proxy in your Amazon VPC.
![\[VPC endpoint service connectivity - XKS proxy in your VPC\]](http://docs.aws.amazon.com/kms/latest/developerguide/images/xks-proxy-in-vpc-60.png)
Alternatively, you can locate your external key store proxy outside of AWS Cloud and use your Amazon VPC endpoint service only for secure communication with AWS KMS.
![\[VPC endpoint service connectivity - XKS proxy outside of AWS\]](http://docs.aws.amazon.com/kms/latest/developerguide/images/xks-proxy-via-vpc-60.png)
You can also connect an external key store to an Amazon VPC endpoint service owned by another AWS account. Both AWS accounts need the [necessary permissions](authorize-xks-key-store.md#authorize-xks-managers) to allow communications between AWS KMS and the VPC endpoint service
**Learn more**:
+ Review the process for creating an external key store, including [assembling the prerequisites](create-xks-keystore.md#xks-requirements). It will help you to ensure that you have all of the components you need when you create your external key store.
+ Learn how to [control access to your external key store](authorize-xks-key-store.md), including the permissions that external key store administrators and users require.
+ Learn about the [Amazon CloudWatch metrics and dimensions](monitoring-cloudwatch.md#kms-metrics) that AWS KMS records for external key stores. We strongly recommend that you create alarms to monitor your external key store so you can detect the early signs of performance and operational problems.
# Configure VPC endpoint service connectivity
Use the guidance in this section to create and configure the AWS resources and related components that are required for an external key store that uses [VPC endpoint service connectivity](choose-xks-connectivity.md#xks-vpc-connectivity). The resources listed for this connectivity option are a supplement to the [resources required for all external key stores](create-xks-keystore.md#xks-requirements). After you create and configure the required resources, you can [create your external key store](create-xks-keystore.md).
You can locate your external key store proxy in your Amazon VPC or locate the proxy outside of AWS and use your VPC endpoint service for communication.
Before you begin, [confirm that you need an external key store](keystore-external.md#do-i-need-xks). Most customer can use KMS keys backed by AWS KMS key material.
**Note**
Some of the elements required for VPC endpoint service connectivity might be included in your external key manager. Also, your software might have additional configuration requirements. Before creating and configuring the AWS resources in this section, consult your proxy and key manager documentation.
**Topics**
+ [
## Requirements for VPC endpoint service connectivity
](#xks-vpce-service-requirements)
+ [
## Step 1: Create an Amazon VPC and subnets
](#xks-create-vpc)
+ [
## Step 2: Create a target group
](#xks-target-group)
+ [
## Step 3: Create a network load balancer
](#xks-nlb)
+ [
## Step 4: Create a VPC endpoint service
](#xks-vpc-svc)
+ [
## Step 5: Verify your private DNS name domain
](#xks-private-dns)
+ [
## Step 6: Authorize AWS KMS to connect to the VPC endpoint service
](#xks-vpc-authorize-kms)
## Requirements for VPC endpoint service connectivity
If you choose VPC endpoint service connectivity for your external key store, the following resources are required.
+ An Amazon VPC that is connected to your external key manager. It must have at least two private [subnets](https://docs.aws.amazon.com/vpc/latest/userguide/configure-subnets.html) in two different Availability Zones.
You can use an existing Amazon VPC for your external key store, provided that it [fulfills the requirements](#xks-vpc-requirements) for use with an external key store. Multiple external key stores can share an Amazon VPC, but each external key store must have its own VPC endpoint service and private DNS name.
+ An [Amazon VPC endpoint service powered by AWS PrivateLink](https://docs.aws.amazon.com/vpc/latest/privatelink/privatelink-share-your-services.html) with a [network load balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/introduction.html) and [target group](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-target-groups.html).
The endpoint service cannot require acceptance. Also, you must add AWS KMS as an allowed principal. This allows AWS KMS to create interface endpoints so it can communicate with your external key store proxy.
+ A private DNS name for the VPC endpoint service that is unique in its AWS Region.
The private DNS name must be a subdomain of a higher-level public domain. For example, if the private DNS name is `myproxy-private.xks.example.com`, it must be a subdomain of a public domain such as `xks.example.com` or `example.com`.
You must [verify ownership](#xks-private-dns) of the DNS domain for private DNS name.
+ A TLS certificate issued by a [supported public certificate authority](https://github.com/aws/aws-kms-xksproxy-api-spec/blob/main/TrustedCertificateAuthorities) for your external key store proxy.
The subject common name (CN) on the TLS certificate must match the private DNS name. For example, if the private DNS name is `myproxy-private.xks.example.com`, the CN on the TLS certificate must be `myproxy-private.xks.example.com` or `*.xks.example.com`.
+ To minimize network latency, create your AWS components in the [supported AWS Region](keystore-external.md#xks-regions) that is closest to your [external key manager](keystore-external.md#concept-ekm). If possible, choose a Region with a network round-trip time (RTT) of 35 milliseconds or less.
For all requirements for an external key store, see the [Assemble the prerequisites](create-xks-keystore.md#xks-requirements).
## Step 1: Create an Amazon VPC and subnets
VPC endpoint service connectivity requires an Amazon VPC that is connected to your external key manager with at least two private subnets. You can create an Amazon VPC or use an existing Amazon VPC that fulfills the requirements for external key stores. For help with creating a new Amazon VPC, see [Create a VPC](https://docs.aws.amazon.com/vpc/latest/userguide/working-with-vpcs.html#Create-VPC) in the *Amazon Virtual Private Cloud User Guide*.
### Requirements for your Amazon VPC
The Amazon VPC endpoint service must have the following properties to work with external key stores.
+ Must be in a [supported Region](keystore-external.md#xks-regions) as your external key store.
+ Requires at least two private subnets, each in a different Availability Zone.
+ The private IP address range of your Amazon VPC must not overlap with the private IP address range of the data center hosting your [external key manager](keystore-external.md#concept-ekm).
+ All components must use IPv4.
You have many options for connecting the Amazon VPC to your external key store proxy. Choose an option that meets your performance and security needs. For a list, see [Connect your VPC to other networks](https://docs.aws.amazon.com/vpc/latest/userguide/extend-intro.html) and [Network-to-Amazon VPC connectivity options](https://docs.aws.amazon.com/whitepapers/latest/aws-vpc-connectivity-options/network-to-amazon-vpc-connectivity-options.html). For more details, see [Direct Connect](https://docs.aws.amazon.com/directconnect/latest/UserGuide/Welcome.html), and the [AWS Site-to-Site VPN User Guide](https://docs.aws.amazon.com/vpn/latest/s2svpn/).
### Creating an Amazon VPC for your external key store
Use the following instructions to create the Amazon VPC for your external key store. An Amazon VPC is required only if you choose the [VPC endpoint service connectivity](choose-xks-connectivity.md) option. You can use an existing Amazon VPC that fulfills the requirements for an external key store.
Follow the instructions in the [Create a VPC, subnets, and other VPC resources](https://docs.aws.amazon.com/vpc/latest/userguide/working-with-vpcs.html#create-vpc-and-other-resources) topic using the following required values. For other fields, accept the default values and provide names as requested.
| Field | Value |
| --- | --- |
| IPv4 CIDR block | Enter the IP addresses for your VPC. The private IP address range of your Amazon VPC must not overlap with the private IP address range of the data center hosting your [external key manager](keystore-external.md#concept-ekm). |
| Number of Availability Zones (AZs) | 2 or more |
| Number of public subnets | None are required (0) |
| Number of private subnets | One for each AZ |
| NAT gateways | None are required. |
| VPC endpoints | None are required. |
| Enable DNS hostnames | Yes |
| Enable DNS resolution | Yes |
Be sure to test your VPC communication. For example, if your external key store proxy is not located in your Amazon VPC, create an Amazon EC2 instance in your Amazon VPC, verify that the Amazon VPC can communicate with your external key store proxy.
### Connecting the VPC to the external key manager
Connect the VPC to the data center that hosts your external key manager using any of the [network connectivity options](https://docs.aws.amazon.com/whitepapers/latest/aws-vpc-connectivity-options/network-to-amazon-vpc-connectivity-options.html) that Amazon VPC supports. Ensure that the Amazon EC2 instance in the VPC (or the external key store proxy, if it is in the VPC), can communicate with the data center and the external key manager.
## Step 2: Create a target group
Before you create the required VPC endpoint service, create its required components, a network load balancer (NLB) and a target group. The network load balancer (NLB) distributes requests among multiple healthy targets, any of which can service the request. In this step, you create a target group with at least two hosts for your external key store proxy, and register your IP addresses with the target group.
Follow the instructions in the [Configure a target group](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/create-network-load-balancer.html#configure-target-group) topic using the following required values. For other fields, accept the default values and provide names as requested.
| Field | Value |
| --- | --- |
| Target type | IP addresses |
| Protocol | TCP |
| Port | 443 |
| IP address type | IPv4 |
| VPC | Choose the VPC where you will create the VPC endpoint service for your external key store. |
| Health check protocol and path | Your health check protocol and path will differ with your external key store proxy configuration. Consult the documentation for your external key manager or external key store proxy.For general information about configuring health checks for your target groups, see [Health checks for your target groups](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/target-group-health-checks.html) in the Elastic Load Balancing User Guide for Network Load Balancers. |
| Network | Other private IP address |
| IPv4 address | The private addresses of your external key store proxy |
| Ports | 443 |
## Step 3: Create a network load balancer
The network load balancer distributes the network traffic, including requests from AWS KMS to your external key store proxy, to the configured targets.
Follow the instructions in the [Configure a load balancer and a listener](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/create-network-load-balancer.html#configure-load-balancer) topic to configure and add a listener and create a load balancer using the following required values. For other fields, accept the default values and provide names as requested.
| Field | Value |
| --- | --- |
| Scheme | Internal |
| IP address type | IPv4 |
| Network mapping | Choose the VPC where you will create the VPC endpoint service for your external key store. |
| Mapping | Choose both of the availability zones (at least two) that you configured for your VPC subnets. Verify the subnet names and private IP address. |
| Protocol | TCP |
| Port | 443 |
| Default action: Forward to | Choose the [target group](#xks-target-group) for your network load balancer. |
## Step 4: Create a VPC endpoint service
Typically, you create an endpoint to a service. However, when you create a VPC endpoint service, you are the provider, and AWS KMS creates an endpoint to your service. For an external key store, create a VPC endpoint service with the network load balancer that you created in the previous step. The VPC endpoint service can be in the same AWS account as your external key store or a different AWS account.
Multiple external key stores can share an Amazon VPC, but each external key store must have its own VPC endpoint service and private DNS name.
Follow the instructions in the [Create an endpoint service](https://docs.aws.amazon.com/vpc/latest/privatelink/create-endpoint-service.html#create-endpoint-service-nlb) topic to create your VPC endpoint service with the following required values. For other fields, accept the default values and provide names as requested.
| Field | Value |
| --- | --- |
| Load balancer type | Network |
| Available load balancers | Choose the [network load balancer](#xks-nlb) that you created in the previous step.If your new load balancer does not appear in the list, verify that its state is active. It might take a few minutes for the load balancer state to change from provisioning to active. |
| Acceptance required | False. Uncheck the check box.*Do not require acceptance*. AWS KMS cannot connect to the VPC endpoint service without a manual acceptance. If acceptance is required, attempts to [create the external key store](create-xks-keystore.md) fail with an `XksProxyInvalidConfigurationException` exception. |
| Enable private DNS name | Associate a private DNS name with the service |
| Private DNS name | Enter a private DNS name that is unique in its AWS Region. The private DNS name must be a subdomain of a higher level public domain. For example, if the private DNS name is `myproxy-private.xks.example.com`, it must be a subdomain of a public domain such as `xks.example.com` or `example.com`.This private DNS name must match the subject common name (CN) in the TLS certificate configured on your external key store proxy. For example, if the private DNS name is `myproxy-private.xks.example.com`, the CN on the TLS certificate must be `myproxy-private.xks.example.com` or `*.xks.example.com`.If the certificate and private DNS name do not match, attempts to connect an external key store to its external key store proxy fail with a connection error code of `XKS_PROXY_INVALID_TLS_CONFIGURATION`. For details, see [General configuration errors](xks-troubleshooting.md#fix-xks-gen-configuration). |
| Supported IP address types | IPv4 |
## Step 5: Verify your private DNS name domain
When you create your VPC endpoint service, its domain verification status is `pendingVerification`. Before using the VPC endpoint service to create an external key store, this status must be `verified`. To verify that you own the domain associated with your private DNS name, you must create a TXT record in a public DNS server.
For example, if the private DNS name for your VPC endpoint service is `myproxy-private.xks.example.com`, you must create a TXT record in a public domain, such as `xks.example.com` or `example.com`, whichever is public. AWS PrivateLink looks for the TXT record first on `xks.example.com` and then on `example.com`.
**Tip**
After you add a TXT record, it might take a few minutes for the **Domain verification status** value to change from `pendingVerification` to `verify`.
To begin, find the verification status of your domain using either of the following methods. Valid values are `verified`, `pendingVerification`, and `failed`.
+ In the [Amazon VPC console](https://console.aws.amazon.com/vpc), choose **Endpoint services**, and choose your endpoint service. In the detail pane, see **Domain verification status**.
+ Use the [DescribeVpcEndpointServiceConfigurations](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeVpcEndpointServiceConfigurations.html) operation. The `State` value is in the `ServiceConfigurations.PrivateDnsNameConfiguration.State` field.
If the verification status is not `verified`, follow the instructions in the [Domain ownership verification](https://docs.aws.amazon.com/vpc/latest/privatelink/manage-dns-names.html#verify-domain-ownership) topic to add a TXT record to your domain's DNS server and verify that the TXT record is published. Then check your verification status again.
You are not required to create an A record for the private DNS domain name. When AWS KMS creates an interface endpoint to your VPC endpoint service, AWS PrivateLink automatically creates a hosted zone with the required A record for the private domain name in the AWS KMS VPC. For external key stores with VPC endpoint service connectivity, this happens when you [connect your external key store](xks-connect-disconnect.md) to its external key store proxy.
## Step 6: Authorize AWS KMS to connect to the VPC endpoint service
See the following procedures for managing your Amazon VPC endpoint service permissions. Each step depends on your connectivity and configuration between your external key store, VPC endpoint service, and AWS account.
------
#### [ Same AWS account ]
When your VPC endpoint service is owned by the same AWS account as your external key store, you must add AWS KMS to the **Allow principals** list for your VPC endpoint service. This allows AWS KMS to create interface endpoints to your VPC endpoint service. If AWS KMS is not an allowed principal, attempts to create an external key store will fail with an `XksProxyVpcEndpointServiceNotFoundException` exception.
Follow the instructions in the [Manage permissions](https://docs.aws.amazon.com/vpc/latest/privatelink/configure-endpoint-service.html#add-remove-permissions) topic in the *AWS PrivateLink Guide*. Use the following required value.
| Field | Value |
| --- | --- |
| AWS KMS ARN | cks.kms..amazonaws.com.rproxy.goskope.comFor example, `cks.kms.us-east-1.amazonaws.com` |
------
#### [ Cross AWS account ]
When your VPC endpoint service is owned by another AWS account you must add both AWS KMS and your account to the **Allow principals** list. This allows AWS KMS and your external key store to create interface endpoints to your VPC endpoint service. If AWS KMS is not an allowed principal, attempts to create an external key store will fail with an `XksProxyVpcEndpointServiceNotFoundException` exception. You'll need to provide the AWS account ARN where the external key store resides.
Follow the instructions in the [Manage permissions](https://docs.aws.amazon.com/vpc/latest/privatelink/configure-endpoint-service.html#add-remove-permissions) topic in the *AWS PrivateLink Guide*. Use the following required value.
| Field | Value |
| --- | --- |
| AWS KMS ARN | cks.kms..amazonaws.com.rproxy.goskope.comFor example, `cks.kms.us-east-1.amazonaws.com` |
| AWS account ARN | arn:aws:iam::111122223333:role/role\$1nameFor example, `arn:aws:iam::123456789012:role/cks_role` |
------
**Next**: [Create an external key store](create-xks-keystore.md)
# Create an external key store
You can create one or many external key stores in each AWS account and Region. Each external key store must be associated with an external key manager outside of AWS, and an external key store proxy (XKS proxy) that mediates communication between AWS KMS and your external key manager. For details, see [Choose an external key store proxy connectivity option](choose-xks-connectivity.md). Before you begin, [confirm that you need an external key store](keystore-external.md#do-i-need-xks). Most customer can use KMS keys backed by AWS KMS key material.
**Tip**
Some external key managers provide a simpler method for creating an external key store. For details, see your external key manager documentation.
Before you create your external key store, you need to [assemble the prerequisites](#xks-requirements). During the creation process, you specify the properties of your external key store. Most importantly, you indicate whether your external key store in AWS KMS uses a [public endpoint](choose-xks-connectivity.md#xks-connectivity-public-endpoint) or a [VPC endpoint service](choose-xks-connectivity.md#xks-vpc-connectivity) to connect to its external key store proxy. You also specify the connection details, including the URI endpoint of the proxy and the path within that proxy endpoint where AWS KMS sends API requests to the proxy.
**Considerations**
+ KMS cannot communicate over IPv6 with External key stores.
+ If you use public endpoint connectivity, make sure that AWS KMS can communicate with your proxy over the internet using an HTTPS connection. This includes configuring TLS on the external key store proxy and ensuring that any firewalls between AWS KMS and the proxy allow IPv4 traffic to and from port 443 on the proxy. While creating an external key store with public endpoint connectivity, AWS KMS tests the connection by sending a status request to the external key store proxy. This test verifies that the endpoint is reachable and that your external key store proxy will accept a request signed with your [external key store proxy authentication credential](keystore-external.md#concept-xks-credential). If this test request fails, the operation to create the external key store fails.
+ If you use VPC endpoint service connectivity, make sure that the network load balancer, private DNS name, and VPC endpoint service are configured correctly and operational. If the external key store proxy isn't in the VPC, you need to ensure that the VPC endpoint service can communicate with the external key store proxy. (AWS KMS tests VPC endpoint service connectivity when you [connect the external key store](xks-connect-disconnect.md) to its external key store proxy.)
+ AWS KMS records [Amazon CloudWatch metrics and dimensions](monitoring-cloudwatch.md#kms-metrics) especially for external key stores. Monitoring graphs based on some of these metrics appear in the AWS KMS console for each external key store. We strongly recommend that you use these metrics to create alarms that monitor your external key store. These alarms alert you to early signs of performance and operational problems before they occur. For instructions, see [Monitor external key stores](xks-monitoring.md).
+ External key stores are subject to [resource quotas](resource-limits.md#cks-resource-quota). Use of KMS keys in an external key store are subject to [request quotas](requests-per-second.md#rps-key-stores). Review these quotas before designing your external key store implementation.
**Note**
Review your configuration for circular dependencies that might prevent it from working.
For example, if you create your external key store proxy using AWS resources, make sure that operating the proxy does not require the availability of a KMS key in an external key store that is accessed via that proxy.
All new external key stores are created in a disconnected state. Before you can create KMS keys your external key store, you must [connect it](about-xks-connecting.md) to its external key store proxy. To change the properties of your external key store, [edit your external key store settings](update-xks-keystore.md).
**Topics**
+ [
## Assemble the prerequisites
](#xks-requirements)
+ [
## Create a new external key store
](#create-xks)
## Assemble the prerequisites
Before you create an external key store, you need to assemble the required components, including the [external key manager](keystore-external.md#concept-ekm) that you will use to support the external key store and the [external key store proxy](keystore-external.md#concept-xks-proxy) that translates AWS KMS requests into a format that your external key manager can understand.
The following components are required for all external key stores. In addition to these components, you need to provide the components to support the [external key store proxy connectivity option](choose-xks-connectivity.md) that you choose.
**Tip**
Your external key manager might include some of these components, or they might be configured for you. For details, see your external key manager documentation.
If you are creating your external key store in the AWS KMS console, you have the option to upload a JSON-based [proxy configuration file](#proxy-configuration-file) that specifies the [proxy URI path](#require-path) and [proxy authentication credential](keystore-external.md#concept-xks-credential). Some external key store proxies generate this file for you. For details, see the documentation for your external key store proxy or external key manager.
### External key manager
Each external key store requires at least one [external key manager](keystore-external.md#concept-ekm) instance. This can be a physical or virtual hardware security module (HSM), or key management software.
You can use a single key manager, but we recommend at least two related key manager instances that share cryptographic keys for redundancy. The external key store does not require exclusive use of the external key manager. However, the external key manager must have the capacity to handle the expected frequency of encryption and decryption requests from the AWS services that use KMS keys in the external key store to protect your resources. Your external key manager should be configured to handle up to 1800 requests per second and to respond within the 250 millisecond timeout for each request. We recommend that you locate the external key manager close to an AWS Region so that the network round-trip time (RTT) is 35 milliseconds or less.
If your external key store proxy allows it, you can change the external key manager that you associate with your external key store proxy, but the new external key manager must be a backup or snapshot with the same key material. If the external key that you associate with a KMS key is no longer available to your external key store proxy, AWS KMS cannot decrypt the ciphertext encrypted with the KMS key.
The external key manager must be accessible to the external key store proxy. If the [GetHealthStatus](keystore-external.md#xks-concepts) response from the proxy reports that all external key manager instances are `Unavailable`, all attempts to create an external key store fail with an [`XksProxyUriUnreachableException`](xks-troubleshooting.md#fix-xks-proxy).
### External key store proxy
You must specify an [external key store proxy](keystore-external.md#concept-xks-proxy) (XKS proxy) that conforms to the design requirements in the [AWS KMS External Key Store Proxy API Specification](https://github.com/aws/aws-kms-xksproxy-api-spec/). You can develop or buy an external key store proxy, or use an external key store proxy provided by or built into your external key manager. AWS KMS recommends that your external key store proxy be configured to handle up to 1800 requests per second and respond within the 250 millisecond timeout for each request. We recommend that you locate the external key manager close to an AWS Region so that the network round-trip time (RTT) is 35 milliseconds or less.
You can use an external key store proxy for more than one external key store, but each external key store must have a unique URI endpoint and path within the external key store proxy for its requests.
If you are using VPC endpoint service connectivity, you can locate your external key store proxy in your Amazon VPC, but that is not required. You can locate your proxy outside of AWS, such as in your private data center, and use the VPC endpoint service only to communicate with the proxy.
### Proxy authentication credential
To create an external key store, you must specify your external key store proxy authentication credential (`XksProxyAuthenticationCredential`).
You must establish an [authentication credential](keystore-external.md#concept-xks-credential) (`XksProxyAuthenticationCredential`) for AWS KMS on your external key store proxy. AWS KMS authenticates to your proxy by signing its requests using the [Signature Version 4 (SigV4) process](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html) with the external key store proxy authentication credential. You specify the authentication credential when you create your external key store and [you can change it](update-xks-keystore.md) at any time. If your proxy rotates your credential, be sure to update the credential values for your external key store.
The proxy authentication credential has two parts. You must provide both parts for your external key store.
+ Access key ID: Identifies the secret access key. You can provide this ID in plain text.
+ Secret access key: The secret part of the credential. AWS KMS encrypts the secret access key in the credential before storing it.
The SigV4 credential that AWS KMS uses to sign requests to the external key store proxy are unrelated to any SigV4 credentials associated with any AWS Identity and Access Management principals in your AWS accounts. Do not reuse any IAM SigV4 credentials for your external key store proxy.
### Proxy connectivity
To create an external key store, you must specify your external key store proxy connectivity option (`XksProxyConnectivity`).
AWS KMS can communicate with your external key store proxy by using a [public endpoint](choose-xks-connectivity.md#xks-connectivity-public-endpoint) or an [Amazon Virtual Private Cloud (Amazon VPC) endpoint service](choose-xks-connectivity.md#xks-vpc-connectivity). While a public endpoint is simpler to configure and maintain, it might not meet the security requirements for every installation. If you choose the Amazon VPC endpoint service connectivity option, you must create and maintain the required components, including an Amazon VPC with at least two subnets in two different Availability Zones, a VPC endpoint service with a network load balancer and target group, and a private DNS name for the VPC endpoint service.
You can [change the proxy connectivity option](update-xks-keystore.md) for your external key store. However, you must ensure that the continued availability of the key material associated with the KMS keys in your external key store. Otherwise, AWS KMS cannot decrypt any ciphertext encrypted with those KMS keys.
For help deciding which proxy connectivity option is best for your external key store, see [Choose an external key store proxy connectivity option](choose-xks-connectivity.md). For help creating an configuring VPC endpoint service connectivity, see [Configure VPC endpoint service connectivity](vpc-connectivity.md).
### Proxy URI endpoint
To create an external key store, you must specify the endpoint (`XksProxyUriEndpoint`) that AWS KMS uses to send requests to the external key store proxy.
The protocol must be HTTPS. AWS KMS communicates over IPv4 on port 443. Do not specify the port in the proxy URI endpoint value.
+ [Public endpoint connectivity](choose-xks-connectivity.md#xks-connectivity-public-endpoint) — Specify the publicly available endpoint for your external key store proxy. This endpoint must be reachable before you create your external key store.
+ [VPC endpoint service connectivity](choose-xks-connectivity.md#xks-vpc-connectivity) — Specify `https://` followed by the private DNS name of the VPC endpoint service.
The TLS server certificate configured on the external key store proxy must match the domain name in the external key store proxy URI endpoint and be issued by a certificate authority supported for external key stores. For a list, see [Trusted Certificate Authorities](https://github.com/aws/aws-kms-xksproxy-api-spec/blob/main/TrustedCertificateAuthorities). Your certificate authority will require proof of domain ownership before issuing the TLS certificate.
The subject common name (CN) on the TLS certificate must match the private DNS name. For example, if the private DNS name is `myproxy-private.xks.example.com`, the CN on the TLS certificate must be `myproxy-private.xks.example.com` or `*.xks.example.com`.
You can [change your proxy URI endpoint](update-xks-keystore.md), but be sure that the external key store proxy has access to the key material associated with the KMS keys in your external key store. Otherwise, AWS KMS cannot decrypt any ciphertext encrypted with those KMS keys.
**Uniqueness requirements**
+ The combined proxy URI endpoint (`XksProxyUriEndpoint`) and proxy URI path (`XksProxyUriPath`) value must be unique in the AWS account and Region.
+ External key stores with public endpoint connectivity can share the same proxy URI endpoint, provided that they have different proxy URI path values.
+ An external key store with public endpoint connectivity cannot use the same proxy URI endpoint value as any external key store with VPC endpoint services connectivity in the same AWS Region, even if the key stores are in different AWS accounts.
+ Each external key store with VPC endpoint connectivity must have its own private DNS name. The proxy URI endpoint (private DNS name) must be unique in the AWS account and Region.
### Proxy URI path
To create an external key store, you must specify the base path in your external key store proxy to the [required proxy APIs](keystore-external.md#concept-proxy-apis). The value must start with `/` and must end with /kms/xks/v1 where `v1` represents the version of the AWS KMS API for the external key store proxy. This path can include an optional prefix between the required elements such as `/example-prefix/kms/xks/v1`. To find this value, see the documentation for your external key store proxy.
AWS KMS sends proxy requests to the address specified by the concatenation of the proxy URI endpoint and proxy URI path. For example, if the proxy URI endpoint is `https://myproxy.xks.example.com` and the proxy URI path is `/kms/xks/v1`, AWS KMS sends its proxy API requests to `https://myproxy.xks.example.com/kms/xks/v1`.
You can [change your proxy URI path](update-xks-keystore.md), but be sure that the external key store proxy has access to the key material associated with the KMS keys in your external key store. Otherwise, AWS KMS cannot decrypt any ciphertext encrypted with those KMS keys.
**Uniqueness requirements**
+ The combined proxy URI endpoint (`XksProxyUriEndpoint`) and proxy URI path (`XksProxyUriPath`) value must be unique in the AWS account and Region.
### VPC endpoint service
Specifies the name of the Amazon VPC endpoint service that is used to communicate with your external key store proxy. This component is required only for external key stores that use VPC endpoint service connectivity. For help setting up and configuring your VPC endpoint service for an external key store, see [Configure VPC endpoint service connectivity](vpc-connectivity.md).
The VPC endpoint service must have the following properties:
+ The VPC endpoint service can reside in the same or a different AWS account as the external key store.
+ The VPC endpoint service must reside in the same AWS Region as the external key store.
+ You'll need to provide the AWS account ID of the VPC endpoint service if it resides in a different AWS account.
+ It must have a network load balancer (NLB) connected to at least two subnets, each in a different Availability Zone.
+ The *allow principals list* for the VPC endpoint service must include the AWS KMS service principal for the Region: `cks.kms..amazonaws.com`, such as `cks.kms.us-east-1.amazonaws.com`.
+ If your Amazon VPC endpoint service is owned by a different AWS account other than the AWS account owning the external key store (XKS), you’ll also need to allow XKS access to the VPC endpoint service. To do so, [allowlist the XKS AWS account ID as a principal](https://docs.aws.amazon.com/vpc/latest/privatelink/configure-endpoint-service.html#add-remove-permissions) for the Amazon VPC endpoint service.
+ It must not require acceptance of connection requests.
+ It must have a private DNS name within a higher level public domain. For example, you could have a private DNS name of myproxy-private.xks.example.com in the public `xks.example.com` domain.
The private DNS name for an external key store with VPC endpoint service connectivity must be unique in its AWS Region.
+ The [domain verification status](vpc-connectivity.md#xks-private-dns) of the private DNS name domain must be `verified`.
+ The TLS server certificate configured on the external key store proxy must specify the private DNS hostname at which the endpoint is reachable.
**Uniqueness requirements**
+ External key stores with VPC endpoint connectivity can share an `Amazon VPC`, but each external key store must have its own VPC endpoint service and private DNS name.
### Proxy configuration file
A *proxy configuration file* is an optional JSON-based file that contains values for the [proxy URI path](#require-path) and [proxy authentication credential](#require-credential) properties of your external key store. When creating or [editing an external key store](update-xks-keystore.md) in the AWS KMS console, you can upload a proxy configuration file to supply configuration values for your external key store. Using this file avoids typing and pasting errors, and ensures that the values in your external key store match the values in your external key store proxy.
Proxy configuration files are generated by the external key store proxy. To learn whether your external key store proxy offers a proxy configuration file, see your external key store proxy documentation.
The following is an example of a well-formed proxy configuration file with fictitious values.
```
{
"XksProxyUriPath": "/example-prefix/kms/xks/v1",
"XksProxyAuthenticationCredential": {
"AccessKeyId": "ABCDE12345670EXAMPLE",
"RawSecretAccessKey": "0000EXAMPLEFA5FT0mCc3DrGUe2sti527BitkQ0Zr9MO9+vE="
}
}
```
You can upload a proxy configuration file only when creating or editing an external key store in the AWS KMS console. You cannot use it with the [CreateCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateCustomKeyStore.html) or [UpdateCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_UpdateCustomKeyStore.html) operations, but you can use the values in the proxy configuration file to ensure that your parameter values are correct.
## Create a new external key store
Once you've assembled the necessary prerequisites, you can create a new external key store in the AWS KMS console or by using the [CreateCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateCustomKeyStore.html) operation.
### Using the AWS KMS console
Before creating an external key store, [choose your proxy connectivity type](choose-xks-connectivity.md) and ensure that you have created and configured all of the [required components](#xks-requirements). If you need help finding any of the required values, consult the documentation for your external key store proxy or key management software.
**Note**
When you create an external key store in the AWS Management Console, you can upload a JSON-based *proxy configuration file* with values for the [proxy URI path](#require-path) and [proxy authentication credential](#require-credential). Some proxies generate this file for you. It is not required.
1. Sign in to the AWS Management Console and open the AWS Key Management Service (AWS KMS) console at [https://console.aws.amazon.com/kms](https://console.aws.amazon.com/kms).
1. To change the AWS Region, use the Region selector in the upper-right corner of the page.
1. In the navigation pane, choose **Custom key stores**, **External key stores**.
1. Choose **Create external key store**.
1. Enter a friendly name for the external key store. The name must be unique among all external key stores in your account.
**Important**
Do not include confidential or sensitive information in this field. This field may be displayed in plaintext in CloudTrail logs and other output.
1. Choose your [proxy connectivity](#require-connectivity) type.
Your proxy connectivity choice determines the [components required](#xks-requirements) for your external key store proxy. For help making this choice, see [Choose an external key store proxy connectivity option](choose-xks-connectivity.md).
1. Select **Cross-account VPC endpoint service** if your VPC endpoint service resides in a different AWS account. Then enter the AWS account ID for the VPC endpoint owner in the **VPC endpoint service owner account ID** field.
1. Choose or enter the name of the [VPC endpoint service](#require-vpc-service-name) for this external key store. This step only appears when your external key store proxy connectivity type is **VPC endpoint service**.
The VPC endpoint service and its VPCs must fulfill the requirements for an external key store. For details, see [Assemble the prerequisites](#xks-requirements).
1. Choose or enter the name of the [VPC endpoint service](#require-vpc-service-name) for this external key store. This step appears only when your external key store proxy connectivity type is **VPC endpoint service**.
The VPC endpoint service and its VPCs must fulfill the requirements for an external key store. For details, see [Assemble the prerequisites](#xks-requirements).
1. Enter your [proxy URI endpoint](#require-endpoint). The protocol must be HTTPS. AWS KMS communicates over IPv4 on port 443. Do not specify the port in the proxy URI endpoint value.
If AWS KMS recognizes the VPC endpoint service that you specified in the previous step, it completes this field for you.
For public endpoint connectivity, enter a publicly available endpoint URI. For VPC endpoint connectivity, enter `https://` followed by the private DNS name of the VPC endpoint service.
1. To enter the values for the [proxy URI path](#require-path) prefix and [proxy authentication credential](#require-credential), upload a proxy configuration file, or enter the values manually.
+ If you have an optional [proxy configuration file](#proxy-configuration-file) that contains values for your [proxy URI path](#require-path.title) and [proxy authentication credential](#require-credential), choose **Upload configuration file**. Follow the steps to upload the file.
When the file is uploaded, the console displays the values from the file in editable fields. You can change the values now or [edit these values](update-xks-keystore.md) after the external key store is created.
To display the value of the secret access key, choose **Show secret access key**.
+ If you don't have a proxy configuration file, you can enter the proxy URI path and proxy authentication credential values manually.
1. If you don't have a proxy configuration file, you can enter your proxy URI manually. The console supplies the required **/kms/xks/v1** value.
If your [proxy URI path](#require-path) includes an optional prefix, such as the `example-prefix` in `/example-prefix/kms/xks/v1`, enter the prefix in the** Proxy URI path prefix** field. Otherwise, leave the field empty.
1. If you don't have a proxy configuration file, you can enter your [proxy authentication credential](keystore-external.md#concept-xks-credential) manually. Both the access key ID and secret access key are required.
+ In **Proxy credential: Access key ID**, enter the access key ID of the proxy authentication credential. The access key ID identifies the secret access key.
+ In **Proxy credential: Secret access key**, enter the secret access key of the proxy authentication credential.
To display the value of the secret access key, choose **Show secret access key**.
This procedure does not set or change the authentication credential you established on your external key store proxy. It just associates these values with your external key store. For information about setting, changing, and your rotating proxy authentication credential, see the documentation for your external key store proxy or key management software.
If your proxy authentication credential changes, [edit the credential setting](update-xks-keystore.md) for your external key store.
1. Choose **Create external key store**.
When the procedure is successful, the new external key store appears in the list of external key stores in the account and Region. If it is unsuccessful, an error message appears that describes the problem and provides help on how to fix it. If you need more help, see [CreateKey errors for the external key](xks-troubleshooting.md#fix-external-key-create).
**Next**: New external key stores are not automatically connected. Before you can create AWS KMS keys in your external key store, you must [connect the external key store](xks-connect-disconnect.md) to its external key store proxy.
### Using the AWS KMS API
You can use the [CreateCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateCustomKeyStore.html) operation to create a new external key store. For help finding the values for the required parameters, see the documentation for your external key store proxy or key management software.
**Tip**
You cannot upload a [proxy configuration file](#proxy-configuration-file) when using the `CreateCustomKeyStore` operation. However, you can use the values in the proxy configuration file to ensure that your parameter values are correct.
To create an external key store, the `CreateCustomKeyStore` operation requires the following parameter values.
+ `CustomKeyStoreName` – A friendly name for the external key store that is unique in the account.
**Important**
Do not include confidential or sensitive information in this field. This field may be displayed in plaintext in CloudTrail logs and other output.
+ `CustomKeyStoreType` — Specify `EXTERNAL_KEY_STORE`.
+ [`XksProxyConnectivity`](#require-connectivity) – Specify `PUBLIC_ENDPOINT` or `VPC_ENDPOINT_SERVICE`.
+ [`XksProxyAuthenticationCredential`](keystore-external.md#concept-xks-credential) — Specify both the access key ID and the secret access key.
+ [`XksProxyUriEndpoint`](#require-endpoint) — The endpoint that AWS KMS uses to communicate with your external key store proxy.
+ [`XksProxyUriPath`](#require-path) — The path within the proxy to the proxy APIs.
+ [`XksProxyVpcEndpointServiceName`](#require-vpc-service-name) — Required only when your `XksProxyConnectivity` value is `VPC_ENDPOINT_SERVICE`.
**Note**
If you use AWS CLI version 1.0, run the following command before specifying a parameter with an HTTP or HTTPS value, such as the `XksProxyUriEndpoint` parameter.
```
aws configure set cli_follow_urlparam false
```
Otherwise, AWS CLI version 1.0 replaces the parameter value with the content found at that URI address, causing the following error:
```
Error parsing parameter '--xks-proxy-uri-endpoint': Unable to retrieve
https:// : received non 200 status code of 404
```
The following examples use fictitious values. Before running the command, replace them with valid values for your external key store.
Create an external key store with public endpoint connectivity.
```
$ aws kms create-custom-key-store
--custom-key-store-name ExampleExternalKeyStorePublic \
--custom-key-store-type EXTERNAL_KEY_STORE \
--xks-proxy-connectivity PUBLIC_ENDPOINT \
--xks-proxy-uri-endpoint https://myproxy.xks.example.com \
--xks-proxy-uri-path /kms/xks/v1 \
--xks-proxy-authentication-credential AccessKeyId=,RawSecretAccessKey=
```
Create an external key store with VPC endpoint service connectivity.
```
$ aws kms create-custom-key-store
--custom-key-store-name ExampleExternalKeyStoreVPC \
--custom-key-store-type EXTERNAL_KEY_STORE \
--xks-proxy-connectivity VPC_ENDPOINT_SERVICE \
--xks-proxy-vpc-endpoint-service-name com.amazonaws.vpce.us-east-1.vpce-svc-example \
--xks-proxy-uri-endpoint https://myproxy-private.xks.example.com \
--xks-proxy-uri-path /kms/xks/v1 \
--xks-proxy-authentication-credential AccessKeyId=,RawSecretAccessKey=
```
When the operation is successful, `CreateCustomKeyStore` returns the custom key store ID, as shown in the following example response.
```
{
"CustomKeyStoreId": cks-1234567890abcdef0
}
```
If the operation fails, correct the error indicated by the exception, and try again. For additional help, see [Troubleshooting external key stores](xks-troubleshooting.md).
**Next**: To use the external key store, [connect it to its external key store proxy](xks-connect-disconnect.md).
# Edit external key store properties
You can edit selected properties of an existing external key store.
You can edit some properties while the external key store is connected or disconnected. For other properties, you must first [disconnect your external key store](xks-connect-disconnect.md) from its external key store proxy. The [connection state](xks-connect-disconnect.md#xks-connection-state) of the external key store must be `DISCONNECTED`. While your external key store is disconnected, you can manage the key store and its KMS keys, but you cannot create or use KMS keys in the external key store. To find the [connection state](xks-connect-disconnect.md#xks-connection-state) of your external key store, use the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) operation or see the **General configuration** section on the detail page for the external key store.
Before updating the properties your external key store, AWS KMS sends a [GetHealthStatus](keystore-external.md#concept-proxy-apis) request to the external key store proxy using the new values. If the request succeeds, it indicates that you can connect and authenticate to an external key store proxy with the updated property values. If the request fails, the edit operation fails with an exception that identifies the error.
When the edit operation completes, the updated property values for your external key store appear in the AWS KMS console and the `DescribeCustomKeyStores` response. However, it can take up to five minutes for the changes to be fully effective.
If you edit your external key store in the AWS KMS console, you have the option to upload a JSON-based [proxy configuration file](create-xks-keystore.md#proxy-configuration-file) that specifies the [proxy URI path](create-xks-keystore.md#require-path) and [proxy authentication credential](keystore-external.md#concept-xks-credential). Some external key store proxies generate this file for you. For details, see the documentation for your external key store proxy or external key manager.
**Warning**
The updated property values must connect your external key store to a proxy for the same external key manager as the previous values, or for a backup or snapshot of the external key manager with the same cryptographic keys. If your external key store permanently loses its access to the external keys associated with its KMS keys, ciphertext encrypted under those external keys is unrecoverable. In particular, changing the proxy connectivity of an external key store can prevent AWS KMS from accessing your external keys.
**Tip**
Some external key managers provide a simpler method for editing external key store properties. For details, see your external key manager documentation.
You can change the following properties of an external key store.
| Editable external key store properties | Any connection state | Require Disconnected state |
| --- | --- | --- |
| Custom key store name A required friendly name for a custom key store. Do not include confidential or sensitive information in this field. This field may be displayed in plaintext in CloudTrail logs and other output. | ![\[Green checkmark icon indicating success or completion.\]](http://docs.aws.amazon.com/kms/latest/developerguide/images/icon-successful.png) | |
| [Proxy authentication credential](keystore-external.md#concept-xks-credential) (XksProxyAuthenticationCredential)(You must specify both the access key ID and the secret access key, even if you are changing only one element.) | ![\[Green checkmark icon indicating success or completion.\]](http://docs.aws.amazon.com/kms/latest/developerguide/images/icon-successful.png) | |
| [Proxy URI path](create-xks-keystore.md#require-path) (XksProxyUriPath) | ![\[Green checkmark icon indicating success or completion.\]](http://docs.aws.amazon.com/kms/latest/developerguide/images/icon-successful.png) | |
| [Proxy connectivity](keystore-external.md#concept-xks-connectivity) (XksProxyConnectivity)(You must also update the proxy URI endpoint. If you are changing to VPC endpoint service connectivity, you must specify a proxy VPC endpoint service name.) | | ![\[Green checkmark icon indicating success or completion.\]](http://docs.aws.amazon.com/kms/latest/developerguide/images/icon-successful.png) |
| [Proxy URI endpoint](create-xks-keystore.md#require-endpoint) (XksProxyUriEndpoint)If you change the proxy endpoint URI, you might also need to change the associated TLS certificate. | | ![\[Green checkmark icon indicating success or completion.\]](http://docs.aws.amazon.com/kms/latest/developerguide/images/icon-successful.png) |
| [Proxy VPC endpoint service name](create-xks-keystore.md#require-vpc-service-name) (XksProxyVpcEndpointServiceName)(This field is required for VPC endpoint service connectivity) | | ![\[Green checkmark icon indicating success or completion.\]](http://docs.aws.amazon.com/kms/latest/developerguide/images/icon-successful.png) |
| [VPC endpoint service owner ](create-xks-keystore.md#require-vpc-service-name) (XksProxyVpcEndpointServiceOwner)(This field is required for VPC endpoint service connectivity) | | ![\[Green checkmark icon indicating success or completion.\]](http://docs.aws.amazon.com/kms/latest/developerguide/images/icon-successful.png) |
## Edit your external key store's properties
You can edit your external key store's properties in the AWS KMS console or by using the [UpdateCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_UpdateCustomKeyStore.html) operation.
### Using the AWS KMS console
When you edit a key store, you can change any of the editable values. Some changes require that the external key store be disconnected from its external key store proxy.
If you are editing the proxy URI path or proxy authentication credential, you can enter the new values or upload an external key store [proxy configuration file](create-xks-keystore.md#proxy-configuration-file) that includes the new values.
1. Sign in to the AWS Management Console and open the AWS Key Management Service (AWS KMS) console at [https://console.aws.amazon.com/kms](https://console.aws.amazon.com/kms).
1. To change the AWS Region, use the Region selector in the upper-right corner of the page.
1. In the navigation pane, choose **Custom key stores**, **External key stores**.
1. Choose the key store you want to edit.
1. If necessary, disconnect the external key store from its external key store proxy. From the **Key store actions** menu, choose **Disconnect**.
1. From the **Key store actions** menu, choose **Edit**.
1. Change one or more of the editable external key store properties. You can also upload an external key store [proxy configuration file](create-xks-keystore.md#proxy-configuration-file) with values for the proxy URI path and proxy authentication credential.You can use a proxy configuration file even if some values specified in the file haven't changed.
1. Choose **Update external key store**.
1. Review the warning, and if you decide to continue, confirm the warning, and then choose **Update external key store**.
When the procedure is successful, a message describes the properties that you edited. When it is unsuccessful, an error message appears that describes the problem and provides help on how to fix it.
1. If necessary, reconnect the external key store. From the **Key store actions** menu, choose **Connect**.
You can leave the external key store disconnected. But while it is disconnected, you cannot create KMS keys in the external key store or use the KMS keys in the external key store in [cryptographic operations](manage-cmk-keystore.md#use-cmk-keystore).
### Using the AWS KMS API
To change the properties of an external key store, use the [UpdateCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_UpdateCustomKeyStore.html) operation. You can change multiple properties of an external key store in the same operation. If the operation is successful, AWS KMS returns an HTTP 200 response and a JSON object with no properties.
Use the `CustomKeyStoreId` parameter to identify the external key store. Use the other parameters to change the properties. You cannot use a [proxy configuration file](create-xks-keystore.md#proxy-configuration-file) with the `UpdateCustomKeyStore` operation. The proxy configuration file is supported only by the AWS KMS console. However, you can use the proxy configuration file to help you determine the correct parameter values for your external key store proxy.
The examples in this section use the [AWS Command Line Interface (AWS CLI)](https://aws.amazon.com/cli/), but you can use any supported programming language.
Before you begin, [if necessary](#update-xks-keystore), [disconnect the external key store](xks-connect-disconnect.md) from its external key store proxy. After updating, if necessary, you can [reconnect the external key store](xks-connect-disconnect.md) to its external key store proxy. You can leave the external key store in the disconnected state, but you must reconnect it before you can create new KMS keys in the key store or use existing KMS keys in the key store for cryptographic operations.
**Note**
If you use AWS CLI version 1.0, run the following command before specifying a parameter with an HTTP or HTTPS value, such as the `XksProxyUriEndpoint` parameter.
```
aws configure set cli_follow_urlparam false
```
Otherwise, AWS CLI version 1.0 replaces the parameter value with the content found at that URI address, causing the following error:
```
Error parsing parameter '--xks-proxy-uri-endpoint': Unable to retrieve
https:// : received non 200 status code of 404
```
#### Change the name of the external key store
The first example uses the [UpdateCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_UpdateCustomKeyStore.html) operation to change the friendly name of the external key store to `XksKeyStore`. The command uses the `CustomKeyStoreId` parameter to identify the custom key store and the `CustomKeyStoreName` to specify the new name for the custom key store. Replace all example values with actual values for your external key store.
```
$ aws kms update-custom-key-store --custom-key-store-id cks-1234567890abcdef0 --new-custom-key-store-name XksKeyStore
```
#### Change the proxy authentication credential
The following example updates the proxy authentication credential that AWS KMS uses to authenticate to the external key store proxy. You can use a command like this one to update the credential if it is rotated on your proxy.
Update the credential on your external key store proxy first. Then use this feature to report the change to AWS KMS. (Your proxy will briefly support both the old and new credential so you have time to update your credential in AWS KMS.)
You must always specify both the access key ID and the secret access key in the credential, even if only one value is changed.
The first two commands set variables to hold the credential values. The `UpdateCustomKeyStore` operations uses the `CustomKeyStoreId` parameter to identify the external key store. It uses the `XksProxyAuthenticationCredential` parameter with its `AccessKeyId` and `RawSecretAccessKey` fields to specify the new credential. Replace all example values with actual values for your external key store.
```
$ accessKeyID=access key id
$ secretAccessKey=secret access key
$ aws kms update-custom-key-store --custom-key-store-id cks-1234567890abcdef0 \
--xks-proxy-authentication-credential \
AccessKeyId=$accessKeyId,RawSecretAccessKey=$secretAccessKey
```
#### Change the proxy URI path
The following example updates the proxy URI path (`XksProxyUriPath`). The combination of the proxy URI endpoint and the proxy URI path must be unique in the AWS account and Region. Replace all example values with actual values for your external key store.
```
$ aws kms update-custom-key-store --custom-key-store-id cks-1234567890abcdef0 \
--xks-proxy-uri-path /kms/xks/v1
```
#### Change to VPC endpoint service connectivity
The following example uses the [UpdateCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_UpdateCustomKeyStore.html) operation to change the external key store proxy connectivity type to `VPC_ENDPOINT_SERVICE`. To make this change, you must specify the required values for VPC endpoint service connectivity, including the VPC endpoint service name (`XksProxyVpcEndpointServiceName`) and a proxy URI endpoint (`XksProxyUriEndpoint`) value that includes the private DNS name for the VPC endpoint service. Replace all example values with actual values for your external key store.
```
$ aws kms update-custom-key-store --custom-key-store-id cks-1234567890abcdef0 \
--xks-proxy-connectivity "VPC_ENDPOINT_SERVICE" \
--xks-proxy-uri-endpoint https://myproxy-private.xks.example.com \
--xks-proxy-vpc-endpoint-service-name com.amazonaws.vpce.us-east-1.vpce-svc-example
```
#### Change to public endpoint connectivity
The following example changes the external key store proxy connectivity type to `PUBLIC_ENDPOINT`. When you make this change, you must update the proxy URI endpoint (`XksProxyUriEndpoint`) value. Replace all example values with actual values for your external key store.
**Note**
VPC endpoint connectivity provides greater security than public endpoint connectivity. Before changing to public endpoint connectivity, consider other options, including locating your external key store proxy on premises and using the VPC only for communication.
```
$ aws kms update-custom-key-store --custom-key-store-id cks-1234567890abcdef0 \
--xks-proxy-connectivity "PUBLIC_ENDPOINT" \
--xks-proxy-uri-endpoint https://myproxy.xks.example.com
```
# View external key stores
You can view external key stores in each account and Region by using the AWS KMS console or by using the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) operation.
When you view an external key store, you can see the following:
+ Basic information about the key store, including its friendly name, ID, key store type, and creation date.
+ Configuration information for the [external key store proxy](keystore-external.md#concept-xks-proxy), including the [connectivity type](keystore-external.md#concept-xks-connectivity), [proxy URI endpoint](create-xks-keystore.md#require-endpoint) and [path](create-xks-keystore.md#require-path), and the [access key ID](keystore-external.md#concept-xks-credential) of your current [proxy authentication credential](keystore-external.md#concept-xks-credential).
+ If the external key store proxy uses [VPC endpoint service connectivity](choose-xks-connectivity.md#xks-vpc-connectivity), the console displays the name of the VPC endpoint service.
+ The current [connection state](xks-connect-disconnect.md#xks-connection-state).
**Note**
A connection state value of **Disconnected** indicates that the external key store has never been connected, or it was intentionally disconnected from its external key store proxy. However, if your attempts to use a KMS key in a connected external key store fail, that might indicate a problem with the external key store or its proxy. For help, see [External key store connection errors](xks-troubleshooting.md#fix-xks-connection).
+ A [Monitoring](xks-monitoring.md) section with graphs of [Amazon CloudWatch metrics](monitoring-cloudwatch.md#kms-metrics) designed to help you detect and resolve issues with your external key store. For help interpreting the graphs, using them in your planning and troubleshooting, and creating CloudWatch alarms based on the metrics in the graphs, see [Monitor external key stores](xks-monitoring.md).
## External key store properties
The following properties of an external key store are visible in the AWS KMS console and the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) response.
### Custom key store properties
The following values appear in the **General configuration** section of the detail page for each custom key store.These properties apply to all custom key stores, including AWS CloudHSM key stores and external key stores.
**Custom key store ID**
A unique ID that AWS KMS assigns to the custom key store.
**Custom key store name**
A friendly name that you assign to the custom key store when you create it. You can change this value at any time.
**Custom key store type**
The type of custom key store. Valid values are AWS CloudHSM (`AWS_CLOUDHSM`) or External key store (`EXTERNAL_KEY_STORE`). You cannot change the type after you create the custom key store.
**Creation date**
The date that the custom key store was created. This date is displayed in local time for the AWS Region.
**Connection state**
Indicates whether the custom key store is connected to its backing key store. The connection state is `DISCONNECTED` only if the custom key store has never been connected to its backing key store, or it has been intentionally disconnected. For details, see [Connection state](xks-connect-disconnect.md#xks-connection-state).
### External key store configuration properties
The following values appear in the **External key store proxy configuration** section of the detail page for each external key store and in the `XksProxyConfiguration` element of the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) response. For a detailed description of each field, including uniqueness requirements and help with determining the correct value for each field, see [Assemble the prerequisites](create-xks-keystore.md#xks-requirements) in the *Creating an external key store* topic.
**Proxy connectivity**
Indicates whether the external key store uses [public endpoint connectivity](choose-xks-connectivity.md#xks-connectivity-public-endpoint) or [VPC endpoint service connectivity](choose-xks-connectivity.md#xks-vpc-connectivity).
**Proxy URI endpoint**
The endpoint that AWS KMS uses to connect to your [external key store proxy](keystore-external.md#concept-xks-proxy).
**Proxy URI path**
The path from the proxy URI endpoint where AWS KMS sends [proxy API requests](keystore-external.md#concept-proxy-apis).
**Proxy credential: Access key ID**
Part of the [proxy authentication credential](keystore-external.md#concept-xks-credential) that you establish on your external key store proxy. The access key ID identifies the secret access key in the credential.
AWS KMS uses the SigV4 signing process and the proxy authentication credential to sign its requests to your external key store proxy. The credential in the signature allows the external key store proxy to authenticate requests on your behalf from AWS KMS.
**VPC endpoint service name**
The name of the Amazon VPC endpoint service that supports your external key store. This value appears only when the external key store uses [VPC endpoint service connectivity](choose-xks-connectivity.md#xks-vpc-connectivity). You can locate your external key store proxy in the VPC or use the VPC endpoint service to communicate securely with your external key store proxy.
**VPC endpoint service owner ID**
The ID of the Amazon VPC endpoint service that supports your external key store. This value appears only when the external key store uses [VPC endpoint service connectivity](choose-xks-connectivity.md#xks-vpc-connectivity). You can locate your external key store proxy in the VPC or use the VPC endpoint service to communicate securely with your external key store proxy.
## View your external key store properties
You can view your external key store and its associated properties in the AWS KMS console or by using the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) operation.
### Using the AWS KMS console
To view the external key stores in a given account and Region, use the following procedure.
1. Sign in to the AWS Management Console and open the AWS Key Management Service (AWS KMS) console at [https://console.aws.amazon.com/kms](https://console.aws.amazon.com/kms).
1. To change the AWS Region, use the Region selector in the upper-right corner of the page.
1. In the navigation pane, choose **Custom key stores**, **External key stores**.
1. To view detailed information about an external key store, choose the key store name.
### Using the AWS KMS API
To view your external key stores, use the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) operation. By default, this operation returns all custom key stores in the account and Region. But you can use either the `CustomKeyStoreId` or `CustomKeyStoreName` parameter (but not both) to limit the output to a particular custom key store.
For custom key stores, the output consists of the custom key store ID, name, and type, and the [connection state](xks-connect-disconnect.md#xks-connection-state) of the key store. If the connection state is `FAILED`, the output also includes a `ConnectionErrorCode` that describes the reason for the error. For help interpreting the `ConnectionErrorCode` for an external key store, see [Connection error codes for external key stores](xks-troubleshooting.md#xks-connection-error-codes).
For external key stores, the output also includes the `XksProxyConfiguration` element. This element includes the [connectivity type](create-xks-keystore.md#require-connectivity), [proxy URI endpoint](create-xks-keystore.md#require-endpoint), [proxy URI path](create-xks-keystore.md#require-path), and the access key ID of the [proxy authentication credential](keystore-external.md#concept-xks-credential).
The examples in this section use the [AWS Command Line Interface (AWS CLI)](https://aws.amazon.com/cli/), but you can use any supported programming language.
For example, the following command returns all custom key stores in the account and Region. You can use the `Limit` and `Marker` parameters to page through the custom key stores in the output.
```
$ aws kms describe-custom-key-stores
```
The following command uses the `CustomKeyStoreName` parameter to get only the example external key store with the `ExampleXksPublic` friendly name. This example key store uses public endpoint connectivity. It is connected to its external key store proxy.
```
$ aws kms describe-custom-key-stores --custom-key-store-name ExampleXksPublic
{
"CustomKeyStores": [
{
"CustomKeyStoreId": "cks-1234567890abcdef0",
"CustomKeyStoreName": "ExampleXksPublic",
"ConnectionState": "CONNECTED",
"CreationDate": "2022-12-14T20:17:36.419000+00:00",
"CustomKeyStoreType": "EXTERNAL_KEY_STORE",
"XksProxyConfiguration": {
"AccessKeyId": "ABCDE12345670EXAMPLE",
"Connectivity": "PUBLIC_ENDPOINT",
"UriEndpoint": "https://xks.example.com:6443",
"UriPath": "/example/prefix/kms/xks/v1"
}
}
]
}
```
The following command gets an example external key store with VPC endpoint service connectivity. In this example, the external key store is connected to its external key store proxy.
```
$ aws kms describe-custom-key-stores --custom-key-store-name ExampleXksVpc
{
"CustomKeyStores": [
{
"CustomKeyStoreId": "cks-9876543210fedcba9",
"CustomKeyStoreName": "ExampleXksVpc",
"ConnectionState": "CONNECTED",
"CreationDate": "2022-12-13T18:34:10.675000+00:00",
"CustomKeyStoreType": "EXTERNAL_KEY_STORE",
"XksProxyConfiguration": {
"AccessKeyId": "ABCDE98765432EXAMPLE",
"Connectivity": "VPC_ENDPOINT_SERVICE",
"UriEndpoint": "https://example-proxy-uri-endpoint-vpc",
"UriPath": "/example/prefix/kms/xks/v1",
"VpcEndpointServiceName": "com.amazonaws.vpce.us-east-1.vpce-svc-example"
}
}
]
}
```
A [`ConnectionState`](xks-connect-disconnect.md#xks-connection-state) of `Disconnected` indicates that an external key store has never been connected or it was intentionally disconnected from its external key store proxy. However, if attempts to use a KMS key in a connected external key store fail, that might indicate a problem with the external key store proxy or other external components.
If the `ConnectionState` of the external key store is `FAILED`, the `DescribeCustomKeyStores` response includes a `ConnectionErrorCode` element that explains the reason for the error.
For example, in the following output, the `XKS_PROXY_TIMED_OUT` value indicates AWS KMS can connect to the external key store proxy, but the connection failed because the external key store proxy did not respond to AWS KMS in the time allotted. If you see this connection error code repeatedly, notify your external key store proxy vendor. For help with this and other connection error failures, see [Troubleshooting external key stores](xks-troubleshooting.md).
```
$ aws kms describe-custom-key-stores --custom-key-store-name ExampleXksVpc
{
"CustomKeyStores": [
{
"CustomKeyStoreId": "cks-9876543210fedcba9",
"CustomKeyStoreName": "ExampleXksVpc",
"ConnectionState": "FAILED",
"ConnectionErrorCode": "XKS_PROXY_TIMED_OUT",
"CreationDate": "2022-12-13T18:34:10.675000+00:00",
"CustomKeyStoreType": "EXTERNAL_KEY_STORE",
"XksProxyConfiguration": {
"AccessKeyId": "ABCDE98765432EXAMPLE",
"Connectivity": "VPC_ENDPOINT_SERVICE",
"UriEndpoint": "https://example-proxy-uri-endpoint-vpc",
"UriPath": "/example/prefix/kms/xks/v1",
"VpcEndpointServiceName": "com.amazonaws.vpce.us-east-1.vpce-svc-example"
}
}
]
}
```
# Monitor external key stores
AWS KMS collects metrics for each interaction with an external key store and publishes them in your CloudWatch account. These metrics are used to generate the graphs in the monitoring section of the detail page for each external key store. The following topic details how to use the graphs to identify and troubleshoot operational and configuration issues impacting your external key store. We recommend using the CloudWatch metrics to set alarms that notify you when your external key store isn't performing as expected. For more information, see [Monitoring with Amazon CloudWatch](monitoring-cloudwatch.md).
**Topics**
+ [
## Viewing the graphs
](#xks-monitoring-navigate)
+ [
## Interpreting the graphs
](#interpreting-graphs)
## Viewing the graphs
You can view the graphs at different levels of detail. By default, each graph uses a three hour time range and five minute aggregation [period](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_concepts.html#CloudWatchPeriods). You can adjust the graph view within the console, but your changes will revert to the default settings when the external key store detail page is closed or the browser is refreshed. For help with Amazon CloudWatch terminology, see [Amazon CloudWatch concepts](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_concepts.html).
### View data point details
The data in each graph is collected by [AWS KMS metrics](https://docs.aws.amazon.com/kms/latest/developerguide/monitoring-cloudwatch.html#kms-metrics). To view more information about a specific data point, pause the mouse over the data point on the line graph. This will display a pop-up with more information about the metric that the graph was derived from. Each list item displays the [dimension](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_concepts.html#Dimension) value recorded at that data point. The pop-up displays a null value (**–**) if there is no metric data available for the dimension value at that data point. Some graphs record multiple dimensions and values for a single data point. Other graphs, like the [reliability graph](#reliability-graph), use the data collected by the metric to calculate a unique value. Each list item is associated with a different line graph color.
### Modify the time range
To modify the [time range](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/modify_graph_date_time.html), select one of the predefined time ranges in the upper right corner of the monitoring section. The predefined time ranges span from 1 hour to 1 week (**1h**, **3h**, **12h**, **1d**, **3d**, or **1w**). This adjusts the time range for all graphs. If you want to view one specific graph in a different time range, or if you want to set a custom time range, enlarge the graph or view it in the Amazon CloudWatch console.
### Zoom in on graphs
You can use the [mini-map zoom feature](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/zoom-graph.html) to focus on sections of line graphs and stacked portions of the graphs without changing between zoomed-in and zoomed-out views. For example, you can use the mini-map zoom feature to focus on a peak in a graph, so that you can compare the spike against other graphs in the monitoring section from the same timeline.
1. Choose and drag on the area of the graph that you want to focus on, and then release the drag.
1. To reset the zoom, choose the **Reset zoom** icon, which looks like a magnifying glass with a minus (-) symbol inside.
### Enlarge a graph
To enlarge a graph, select the menu icon in the upper right corner of an individual graph and choose **Enlarge**. You can also select the enlarge icon that appears next to the menu icon when you hover over a graph.
Enlarging a graph enables you to further modify the view of a graph by specifying a different period, custom time range, or refresh interval. These changes will revert to the default settings when you close the enlarged view.
Modify the period
1. Choose the **Period options** menu. By default, this menu displays the value: **5 minutes**.
1. Choose a period, the predefined periods span from 1 second to 30 days.
For example, you can choose a one-minute view, which can be useful when troubleshooting. Or, choose a less detailed, one-hour view. That can be useful when viewing a broader time range (for example, 3 days) so that you can see trends over time. For more information, see [Periods](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_concepts.html#CloudWatchPeriods) in the *Amazon CloudWatch User Guide*.
Modify the time range or time zone
1. Select one of the predefined time ranges, which span from 1 hour to 1 week (**1h**, **3h**, **12h**, **1d**, **3d**, or **1w**). Alternatively, you can choose **Custom** to set your own time range.
1. Choose **Custom**
1. *Time range:* select the **Absolute** tab in the upper left corner of the box. Use the calendar picker or text field boxes to specify a time range.
1. *Time zone:* choose the dropdown in the upper right corner of the box. You can change the time zone to **UTC** or **Local time zone**.
1. After you specify a time range, choose **Apply**.
Modify how often the data in your graph is refreshed
1. Choose the **Refresh options** menu in the upper-right corner.
1. Choose a refresh interval (**Off**, **10 Seconds**, **1 Minute**, **2 Minutes**, **5 Minutes**, or **15 Minutes**).
### View graphs in the Amazon CloudWatch console
The graphs in the monitoring section are derived from predefined metrics that AWS KMS publishes to Amazon CloudWatch. You can open them within the CloudWatch console and save them to CloudWatch dashboards. If you have multiple external key stores, you can open their respective graphs in CloudWatch and save them to a single dashboard to compare their health and usage.
**Add to CloudWatch dashboard**
Select **Add to dashboard** in the upper right corner to add all of the graphs to an Amazon CloudWatch dashboard. You can either select an existing dashboard or create a new one. For information on using this dashboard to create customized views of the graphs and alarms, see [Using Amazon CloudWatch dashboards](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html) in the *Amazon CloudWatch User Guide*.
**View in CloudWatch metrics**
Select the menu icon in the upper right corner of an individual graph and choose **View in metrics** to view this graph in the Amazon CloudWatch console. From the CloudWatch console, you can add this single graph to a dashboard and modify time ranges, periods, and refresh intervals. For more information see, [Graphing metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/graph_metrics.html) in the *Amazon CloudWatch User Guide*.
## Interpreting the graphs
AWS KMS provides several graphs to monitor the health of your external key store within the AWS KMS console. These graphs are automatically configured and derived from [AWS KMS metrics](https://docs.aws.amazon.com/kms/latest/developerguide/monitoring-cloudwatch.html#kms-metrics).
The graph data is collected as part of the calls you make to your external key store and external keys. You might see data populating graphs during a time range that you did not make any calls, this data comes from the periodic `GetHealthStatus` calls that AWS KMS makes on your behalf to check the status of your external key store proxy and external key manager. If your graphs display the message **No data available**, then there were no calls recorded during that time range or your external key store is in a [`DISCONNECTED`](xks-connect-disconnect.md#xks-connection-state) state. You might be able to identify the time your external key store disconnected by [adjusting your view](#graph-time-range) to a broader time range.
**Topics**
+ [
### Total requests
](#total-requests-graph)
+ [
### Reliability
](#reliability-graph)
+ [
### Latency
](#latency-graph)
+ [
### Top 5 exceptions
](#top-5-exceptions-graph)
+ [
### Certificate days to expire
](#cert-expire-graph)
### Total requests
The total number of AWS KMS requests being received for a specific external key store during a given time range. Use this graph to determine if you are at risk of throttling.
AWS KMS recommends that your external key manager be able to handle up to 1800 requests for cryptographic operations per second. If you approach 540,000 calls in a five-minute period, you are at risk of throttling.
You can monitor the number of requests for cryptographic operations on KMS keys in your external key store that AWS KMS throttles with the [ExternalKeyStoreThrottle](monitoring-cloudwatch.md#metric-throttling) metric.
If you are getting very frequent `KMSInvalidStateException` errors with a message that explains that the request was rejected "due to a very high request rate," it might indicate that your external key manager or external key store proxy cannot keep pace with the current request rate. If possible, lower your request rate. You might also consider requesting a decrease in your custom key store request quota value. Decreasing this quota value might increase throttling, but it indicates that AWS KMS is rejecting excess requests quickly before they are sent to your external key store proxy or external key manager. To request a quota decrease, please visit [AWS Support Center](https://console.aws.amazon.com/support/home) and create a case.
The total requests graph is derived from the [XksProxyErrors](monitoring-cloudwatch.md#metric-xks-proxy-errors) metric, which collects data on both the successful and unsuccessful responses that AWS KMS receives from your external key store proxy. When you [view a specific data point](#graph-data-point), the pop-up displays the value of the `CustomKeyStoreId` dimension alongside the total number of AWS KMS requests recorded at that data point. The `CustomKeyStoreId` will always be the same.
### Reliability
The percentage of AWS KMS requests for which the external key store proxy returned either a successful response or a non-retryable error. Use this graph to evaluate the operational health of your external key store proxy.
When the graph displays a value less than 100%, it indicates cases where the proxy either did not respond or responded with a retryable error. This can indicate problems with the network, slowness of the external key store proxy or external key manager, or implementation bugs.
If the request includes a bad credential and your proxy responds with an `AuthenticationFailedException`, the graph will still indicate 100% reliability because the proxy identified an incorrect value in the [external key store proxy API request](keystore-external.md#concept-proxy-apis), and therefore the failure is expected. If the percentage of your reliability graph is 100%, then your external key store proxy is responding as expected. If the graph displays a value less than 100%, then the proxy either responded with a retryable error or timed out. For example, if the proxy responds with a `ThrottlingException` due to a very high request rate, it will display a lower reliability percentage because the proxy was unable to identify a specific problem in the request that caused it to fail. This is because retryable errors are likely transient problems that can be resolved by retrying the request.
The following error responses will lower the reliability percentage. You can use the [Top 5 exceptions](#top-5-exceptions-graph) graph and the [XksProxyErrors](monitoring-cloudwatch.md#metric-xks-proxy-errors) metric to further monitor how frequently your proxy returns each retryable error.
+ `InternalException`
+ `DependencyTimeoutException`
+ `ThrottlingException`
+ `XksProxyUnreachableException`
The reliability graph is derived from the [XksProxyErrors](monitoring-cloudwatch.md#metric-xks-proxy-errors) metric, which collects data on both the successful and unsuccessful responses that AWS KMS receives from your external key store proxy. The reliability percentage will only lower if the response has an `ErrorType` value of `Retryable`. When you [view a specific data point](#graph-data-point), the pop-up displays the value of the `CustomKeyStoreId` dimension alongside the reliability percentage for AWS KMS requests recorded at that data point. The `CustomKeyStoreId` will always be the same.
We recommend using the [XksProxyErrors](monitoring-cloudwatch.md#metric-xks-proxy-errors) metric to create a CloudWatch alarm that notifies you of potential networking problems by alerting you when more than five retryable errors are recorded in a one minute period. For more information, see [Create an alarm for retryable errors](xks-alarms.md#retryable-errors-alarm).
### Latency
The number of milliseconds it takes for an external key store proxy to respond to an AWS KMS request. Use this graph to evaluate the performance of your external key store proxy and external key manager.
AWS KMS expects the external key store proxy to respond to each request within 250 milliseconds. In the case of network timeouts, AWS KMS will retry the request once. If the proxy fails a second time, the recorded latency is the combined timeout limit for both request attempts and the graph will display approximately 500 milliseconds. In all other cases where the proxy doesn't respond within the 250 millisecond timeout limit, the recorded latency is 250 milliseconds. If the proxy is frequently timing out on encryption and decryption operations, consult your external proxy administrator. For help troubleshooting latency problems, see [Latency and timeout errors](xks-troubleshooting.md#fix-xks-latency).
Slow responses might also indicate that your external key manager cannot handle the current request traffic. AWS KMS recommends that your external key manager be able to handle up to 1800 requests for cryptographic operations per second. If your external key manager cannot handle the 1800 requests per second rate, consider requesting a decrease in your [request quota for KMS keys in a custom key store](requests-per-second.md#rps-key-stores). Requests for cryptographic operations using the KMS keys in your external key store will fail fast with a [throttling exception](throttling.md), rather than being processed and later rejected by your external key store proxy or external key manager.
The latency graph is derived from the [XksProxyLatency](monitoring-cloudwatch.md#metric-xks-proxy-latency) metric. When you [view a specific data point](#graph-data-point), the pop-up displays the corresponding `KmsOperation` and `XksOperation` dimension values alongside the average latency recorded for the operations at that data point. The list items are ordered from highest latency to lowest.
We recommend using the [XksProxyLatency](monitoring-cloudwatch.md#metric-xks-proxy-latency) metric to create a CloudWatch alarm that notifies you when your latency is approaching the timeout limit. For more information, see [Create an alarm for response timeout](xks-alarms.md#latency-alarm).
### Top 5 exceptions
The top five exceptions for failed cryptographic and management operations during a given time range. Use this graph to track the most frequent errors, so you can prioritize your engineering effort.
This count includes exceptions that AWS KMS received from the external key store proxy and the `XksProxyUnreachableException` that AWS KMS returns internally when it cannot establish communication with the external key store proxy.
High rates of retryable errors might indicate networking errors, while high rates of non-retryable errors might indicate a problem with the configuration of your external key store. For example, a spike in `AuthenticationFailedExceptions` indicates a discrepancy between the authentication credentials configured in AWS KMS and the external key store proxy. To view your external key store configuration, see [View external key stores](view-xks-keystore.md). To edit your external key store settings, see [Edit external key store properties](update-xks-keystore.md).
The exceptions that AWS KMS receives from the external key store proxy are different from the exceptions that AWS KMS returns when an operation fails. AWS KMS cryptographic operations return an `KMSInvalidStateException` for all failures related to the external configuration or connection state of the external key store. To identify the problem, use the accompanying error message text.
The following table shows the exceptions that can appear in the top 5 exceptions graph and the corresponding exceptions that AWS KMS returns to you.
| Error type | Exception displayed in the graph | Exception that AWS KMS returned to you |
| --- | --- | --- |
| Non-retryable | AccessDeniedException For troubleshooting help, see [Proxy authorization issues](xks-troubleshooting.md#fix-xks-authorization). | **`CustomKeyStoreInvalidStateException`** in response to `CreateKey` operations. **`KMSInvalidStateException`** in response to cryptographic operations. |
| Non-retryable | AuthenticationFailedException For troubleshooting help, see [Authentication credential errors](xks-troubleshooting.md#fix-xks-credentials). | **`XksProxyIncorrectAuthenticationCredentialException`** in response to `CreateCustomKeyStore` and `UpdateCustomKeyStore` operations.**`CustomKeyStoreInvalidStateException`** in response to `CreateKey` operations. **`KMSInvalidStateException`** in response to cryptographic operations. |
| Retryable | **`DependencyTimeoutException`** For troubleshooting help, see [Latency and timeout errors](xks-troubleshooting.md#fix-xks-latency). | **`XksProxyUriUnreachableException`** in response to `CreateCustomKeyStore` and `UpdateCustomKeyStore` operations. **`CustomKeyStoreInvalidStateException`** in response to `CreateKey` operations. **`KMSInvalidStateException`** in response to cryptographic operations. |
| Retryable | **`InternalException`** The external key store proxy rejected the request because it cannot communicate with the external key manager. Verify that the external key store proxy configuration is correct and that the external key manager is available. | **`XksProxyInvalidResponseException`** in response to `CreateCustomKeyStore` and `UpdateCustomKeyStore` operations. **`CustomKeyStoreInvalidStateException`** in response to `CreateKey` operations. **`KMSInvalidStateException`** in response to cryptographic operations. |
| Non-retryable | **`InvalidCiphertextException`** For troubleshooting help, see [Decryption errors](xks-troubleshooting.md#fix-xks-decrypt). | **`KMSInvalidStateException`** in response to cryptographic operations. |
| Non-retryable | **`InvalidKeyUsageException`** For troubleshooting help, see [Cryptographic operation errors for the external key](xks-troubleshooting.md#fix-external-key-crypto). | **`XksKeyInvalidConfigurationException`** in response to `CreateKey` operations. **`KMSInvalidStateException`** in response to cryptographic operations. |
| Non-retryable | **`InvalidStateException`** For troubleshooting help, see [Cryptographic operation errors for the external key](xks-troubleshooting.md#fix-external-key-crypto). | **`XksKeyInvalidConfigurationException`** in response to `CreateKey` operations. **`KMSInvalidStateException`** in response to cryptographic operations. |
| Non-retryable | **`InvalidUriPathException`** For troubleshooting help, see [General configuration errors](xks-troubleshooting.md#fix-xks-gen-configuration). | **`XksProxyInvalidConfigurationException`** in response to `CreateCustomKeyStore` and `UpdateCustomKeyStore` operations. **`CustomKeyStoreInvalidStateException`** in response to `CreateKey` operations. **`KMSInvalidStateException`** in response to cryptographic operations. |
| Non-retryable | **`KeyNotFoundException`** For troubleshooting help, see [External key errors](xks-troubleshooting.md#fix-external-key). | **`XksKeyNotFoundException`** in response to `CreateKey` operations. **`KMSInvalidStateException`** in response to cryptographic operations. |
| Retryable | **`ThrottlingException`** The external key store proxy rejected the request due to a very high request rate. Reduce the frequency of your calls using KMS keys in this external key store. | **`XksProxyUriUnreachableException`** in response to `CreateCustomKeyStore` and `UpdateCustomKeyStore` operations. **`CustomKeyStoreInvalidStateException`** in response to `CreateKey` operations. **`KMSInvalidStateException`** in response to cryptographic operations. |
| Non-retryable | **`UnsupportedOperationException`** For troubleshooting help, see [Cryptographic operation errors for the external key](xks-troubleshooting.md#fix-external-key-crypto). | **`XksKeyInvalidResponseException`** in response to `CreateKey` operations. **`KMSInvalidStateException`** in response to cryptographic operations. |
| Non-retryable | **`ValidationException`** For troubleshooting help, see [Proxy issues](xks-troubleshooting.md#fix-xks-proxy). | **`XksProxyInvalidResponseException`** in response to `CreateCustomKeyStore` and `UpdateCustomKeyStore` operations. **`CustomKeyStoreInvalidStateException`** in response to `CreateKey` operations. **`KMSInvalidStateException`** in response to cryptographic operations. |
| Retryable | **`XksProxyUnreachableException`** If you see this error repeatedly, verify that your external key store proxy is active and is connected to the network, and that its URI path and endpoint URI or VPC service name are correct in your external key store. | **`XksProxyUriUnreachableException`** in response to `CreateCustomKeyStore` and `UpdateCustomKeyStore` operations. **`CustomKeyStoreInvalidStateException`** in response to `CreateKey` operations. **`KMSInvalidStateException`** in response to cryptographic operations. |
The top 5 exceptions graph is derived from the [XksProxyErrors](monitoring-cloudwatch.md#metric-xks-proxy-errors) metric. When you [view a specific data point](#graph-data-point), the pop-up displays the value of the `ExceptionName` dimension alongside the number of times that the exception was recorded at that data point. The five list items are ordered from most frequent exception to least.
We recommend using the [XksProxyErrors](monitoring-cloudwatch.md#metric-xks-proxy-errors) metric to create a CloudWatch alarm that notifies you of potential configuration problems by alerting you when more than five non-retryable errors are recorded in a one minute period. For more information, see [Create an alarm for non-retryable errors](xks-alarms.md#nonretryable-errors-alarm).
### Certificate days to expire
The number of days until the TLS certificate for your external key store proxy endpoint (`XksProxyUriEndpoint`) expires. Use this graph to monitor upcoming expiration of your TLS certificate.
When the certificate expires, AWS KMS cannot communicate with the external key store proxy. All data protected by KMS keys in your external key store becomes inaccessible until you renew the certificate.
The certificate days to expire graph is derived from the [XksProxyCertificateDaysToExpire](monitoring-cloudwatch.md#metric-xks-proxy-certificate-days-to-expire) metric. We strongly recommend using this metric to create a CloudWatch alarm that notifies you about the upcoming expiration. Certificate expiration might prevent you from accessing your encrypted resources. Set the alarm to give your organization time to renew the certificate before it expires. For more information, see [Create an alarm for certificate expiration](xks-alarms.md#cert-expire-alarm).
# Connect and disconnect external key stores
New external key stores are not connected. To create and use AWS KMS keys in your external key store, you need to connect your external key store to its [external key store proxy](keystore-external.md#concept-xks-proxy). You can connect and disconnect your external key store at any time, and [view its connection state](view-xks-keystore.md).
While your external key store is disconnected, AWS KMS cannot communicate with your external key store proxy. As a result, you can view and manage your external key store and its existing KMS keys. However, you cannot create KMS keys in your external key store, or use its KMS keys in cryptographic operations. You might need to disconnect your external key store at some point, such as when editing its properties, but plan accordingly. Disconnecting the key store might disrupt the operation of AWS services that use its KMS keys.
You are not required to connect your external key store. You can leave an external key store in a disconnected state indefinitely and connect it only when you need to use it. However, you might want to test the connection periodically to verify that the settings are correct and it can be connected.
When you disconnect a custom key store, the KMS keys in the key store become unusable right away (subject to eventual consistency). However, resources encrypted with [data keys](data-keys.md) protected by the KMS key are not affected until the KMS key is used again, such as to decrypt the data key. This issue affects AWS services, many of which use data keys to protect your resources. For details, see [How unusable KMS keys affect data keys](unusable-kms-keys.md).
**Note**
External key stores are in a `DISCONNECTED` state only when the key store has never been connected or you explicitly disconnect it. A `CONNECTED` state does not indicate that external key store or its supporting components are operating efficiently. For information about the performance of your external key store components, see the graphs in **Monitoring** section of the detail page for each external key store. For details, see [Monitor external key stores](xks-monitoring.md).
Your external key manager might provide additional methods of stopping and restarting communication between your AWS KMS external key store and your external key store proxy, or between your external key store proxy and external key manager. For details, see your external key manager documentation.
**Topics**
+ [
## Connection state
](#xks-connection-state)
+ [
# Connect an external key store
](about-xks-connecting.md)
+ [
# Disconnect an external key store
](about-xks-disconnecting.md)
## Connection state
Connecting and disconnecting changes the *connection state* of your custom key store. Connection state values are the same for AWS CloudHSM key stores and external key stores.
To view the connection state of your custom key store, use the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/DescribeCustomKeyStores.html) operation or AWS KMS console. **Connection state** appears in each custom key store table, in the **General configuration** section of the detail page for each custom key store, and on the **Cryptographic configuration** tab of KMS keys in a custom key store. For details, see [View an AWS CloudHSM key store](view-keystore.md) and [View external key stores](view-xks-keystore.md).
An custom key store can have one of the following connection states:
+ `CONNECTED`: The custom key store is connected to its backing key store. You can create and use KMS keys in the custom key store.
The *backing key store* for an AWS CloudHSM key store is its associated AWS CloudHSM cluster. The *backing key store* for an external key store is external key store proxy and the external key manager that it supports.
A CONNECTED state means that a connection succeeded and the custom key store has not been intentionally disconnected. It does not indicate that the connection is operating properly. For information about the status of the AWS CloudHSM cluster associated with your AWS CloudHSM key store, see [Getting CloudWatch metrics for AWS CloudHSM](https://docs.aws.amazon.com/cloudhsm/latest/userguide/hsm-metrics-cw.html) in the AWS CloudHSM User Guide. For information about the status and operation of your external key store, see the graphs in the **Monitoring** section of the detail page for each external key store. For details, see [Monitor external key stores](xks-monitoring.md).
+ `CONNECTING`: The process of connecting an custom key store is in progress. This is a transient state.
+ `DISCONNECTED`: The custom key store has never been connected to its backing, or it was intentionally disconnected by using the AWS KMS console or the [DisconnectCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/DisconnectCustomKeyStores.html) operation.
+ `DISCONNECTING`: The process of disconnecting an custom key store is in progress. This is a transient state.
+ `FAILED`: An attempt to connect the custom key store failed. The `ConnectionErrorCode` in the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/DescribeCustomKeyStores.html) response indicates the problem.
To connect an custom key store, its connection state must be `DISCONNECTED`. If the connection state is `FAILED`, use the `ConnectionErrorCode` to identify and resolve the problem. Then disconnect the custom key store before trying to connect it again. For help with connection failures, see [External key store connection errors](xks-troubleshooting.md#fix-xks-connection). For help responding to a connection error code, see [Connection error codes for external key stores](xks-troubleshooting.md#xks-connection-error-codes).
To view the connection error code:
+ In the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) response, view the value of the `ConnectionErrorCode` element. This element appears in the `DescribeCustomKeyStores` response only when the `ConnectionState` is `FAILED`.
+ To view the connection error code in the AWS KMS console, on detail page for the external key store and hover over the **Failed** value.
![\[Connection error code on the custom key store details page\]](http://docs.aws.amazon.com/kms/latest/developerguide/images/connection-error-code.png)
# Connect an external key store
When your external key store is connected to its external key store proxy, you can [create KMS keys in your external key store](create-cmk-keystore.md) and use its existing KMS keys in [cryptographic operations](manage-cmk-keystore.md#use-cmk-keystore).
The process that connects an external key store to its external key store proxy differs based on the connectivity of the external key store.
+ When you connect an external key store with [public endpoint connectivity](keystore-external.md#concept-xks-connectivity), AWS KMS sends a [GetHealthStatus request](keystore-external.md#concept-proxy-apis) to the external key store proxy to validate the [proxy URI endpoint](create-xks-keystore.md#require-endpoint), [proxy URI path](create-xks-keystore.md#require-path), and [proxy authentication credential](keystore-external.md#concept-xks-credential). A successful response from the proxy confirms that the [proxy URI endpoint](create-xks-keystore.md#require-endpoint) and [proxy URI path](create-xks-keystore.md#require-path) are accurate and accessible, and that the proxy authenticated the request signed with the [proxy authentication credential](keystore-external.md#concept-xks-credential) for the external key store.
+ When you connect an external key store with [VPC endpoint service connectivity](choose-xks-connectivity.md#xks-vpc-connectivity) to its external key store proxy, AWS KMS does the following:
+ Confirms that the domain for the private DNS name specified in the [proxy URI endpoint](create-xks-keystore.md#require-endpoint) is [verified](vpc-connectivity.md#xks-private-dns).
+ Creates an interface endpoint from an AWS KMS VPC to your VPC endpoint service.
+ Creates a private hosted zone for the private DNS name specified in the proxy URI endpoint
+ Sends a [GetHealthStatus request](keystore-external.md#concept-proxy-apis) to the external key store proxy. A successful response from the proxy confirms that the [proxy URI endpoint](create-xks-keystore.md#require-endpoint) and [proxy URI path](create-xks-keystore.md#require-path) are accurate and accessible, and that the proxy authenticated the request signed with the [proxy authentication credential](keystore-external.md#concept-xks-credential) for the external key store.
The connect operation begins the process of connecting your custom key store, but connecting an external key store it its external proxy takes approximately five minutes. A success response from the connect operation does not indicate that the external key store is connected. To confirm that the connection was successful, use the AWS KMS console or the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/DescribeCustomKeyStores.html) operation to view the [connection state](xks-connect-disconnect.md#xks-connection-state) of external your key store.
When the connection state is `FAILED`, a connection error code is displayed in the AWS KMS console and is added to the `DescribeCustomKeyStore` response. For help interpreting connection error codes, see [Connection error codes for external key stores](xks-troubleshooting.md#xks-connection-error-codes).
## Connect and reconnect to your external key store
You can connect, or reconnect, your external key store in the AWS KMS console or by using the [ConnectCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_ConnectCustomKeyStore.html) operation.
### Using the AWS KMS console
You can use the AWS KMS console to connect an external key store to its external key store proxy.
1. Sign in to the AWS Management Console and open the AWS Key Management Service (AWS KMS) console at [https://console.aws.amazon.com/kms](https://console.aws.amazon.com/kms).
1. To change the AWS Region, use the Region selector in the upper-right corner of the page.
1. In the navigation pane, choose **Custom key stores**, **External key stores**.
1. Choose the row of the external key store you want to connect.
If the [connection state](xks-connect-disconnect.md#xks-connection-state) of the external key store is **FAILED**, you must [disconnect the external key store](disconnect-keystore.md#disconnect-keystore-console) before you connect it.
1. From the **Key store actions** menu, choose **Connect**.
The connection process typically takes about five minutes to complete.When the operation completes, the [connection state](xks-connect-disconnect.md#xks-connection-state) changes to **CONNECTED**.
If the connection state is **Failed**, hover over the connection state to see the *connection error code*, which explains the cause of the error. For help responding to a connection error code, see [Connection error codes for external key stores](xks-troubleshooting.md#xks-connection-error-codes). To connect an external key store with a **Failed** connection state, you must first [disconnect the custom key store](disconnect-keystore.md#disconnect-keystore-console).
### Using the AWS KMS API
To connect a disconnected external key store, use the [ConnectCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_ConnectCustomKeyStore.html) operation.
Before connecting, the [connection state](xks-connect-disconnect.md#xks-connection-state) of the external key store must be `DISCONNECTED`. If the current connection state is `FAILED`, [disconnect the external key store](about-xks-disconnecting.md#disconnect-xks-api), and then connect it.
The connection process takes about five minutes to complete. Unless it fails quickly, `ConnectCustomKeyStore` returns an HTTP 200 response and a JSON object with no properties. However, this initial response does not indicate that the connection was successful. To determine whether the external key store is connected, see the connection state in the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) response.
The examples in this section use the [AWS Command Line Interface (AWS CLI)](https://aws.amazon.com/cli/), but you can use any supported programming language.
To identify the external key store, use its custom key store ID. You can find the ID on the **Custom key stores** page in the console or by using the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) operation. Before running this example, replace the example ID with a valid one.
```
$ aws kms connect-custom-key-store --custom-key-store-id cks-1234567890abcdef0
```
The `ConnectCustomKeyStore` operation does not return the `ConnectionState` in its response. To verify that the external key store is connected, use the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) operation. By default, this operation returns all custom keys stores in your account and Region. But you can use either the `CustomKeyStoreId` or `CustomKeyStoreName` parameter (but not both) to limit the response to particular custom key stores. A `ConnectionState` value of `CONNECTED` indicates that the external key store is connected to its external key store proxy.
```
$ aws kms describe-custom-key-stores --custom-key-store-name ExampleXksVpc
{
"CustomKeyStores": [
{
"CustomKeyStoreId": "cks-9876543210fedcba9",
"CustomKeyStoreName": "ExampleXksVpc",
"ConnectionState": "CONNECTED",
"CreationDate": "2022-12-13T18:34:10.675000+00:00",
"CustomKeyStoreType": "EXTERNAL_KEY_STORE",
"XksProxyConfiguration": {
"AccessKeyId": "ABCDE98765432EXAMPLE",
"Connectivity": "VPC_ENDPOINT_SERVICE",
"UriEndpoint": "https://example-proxy-uri-endpoint-vpc",
"UriPath": "/example/prefix/kms/xks/v1",
"VpcEndpointServiceName": "com.amazonaws.vpce.us-east-1.vpce-svc-example"
}
}
]
}
```
If the `ConnectionState` value in the `DescribeCustomKeyStores` response is `FAILED`, the `ConnectionErrorCode` element indicates the reason for the failure.
In the following example, the `XKS_VPC_ENDPOINT_SERVICE_NOT_FOUND` value for the `ConnectionErrorCode` indicates that AWS KMS can't find the VPC endpoint service that it uses to communicate with the external key store proxy. Verify that the `XksProxyVpcEndpointServiceName` is correct, the AWS KMS service principal is an allowed principal on the Amazon VPC endpoint service, and that the VPC endpoint service does not require acceptance of connection requests. For help responding to a connection error code, see [Connection error codes for external key stores](xks-troubleshooting.md#xks-connection-error-codes).
```
$ aws kms describe-custom-key-stores --custom-key-store-name ExampleXksVpc
{
"CustomKeyStores": [
{
"CustomKeyStoreId": "cks-9876543210fedcba9",
"CustomKeyStoreName": "ExampleXksVpc",
"ConnectionState": "FAILED",
"ConnectionErrorCode": "XKS_VPC_ENDPOINT_SERVICE_NOT_FOUND",
"CreationDate": "2022-12-13T18:34:10.675000+00:00",
"CustomKeyStoreType": "EXTERNAL_KEY_STORE",
"XksProxyConfiguration": {
"AccessKeyId": "ABCDE98765432EXAMPLE",
"Connectivity": "VPC_ENDPOINT_SERVICE",
"UriEndpoint": "https://example-proxy-uri-endpoint-vpc",
"UriPath": "/example/prefix/kms/xks/v1",
"VpcEndpointServiceName": "com.amazonaws.vpce.us-east-1.vpce-svc-example"
}
}
]
}
```
# Disconnect an external key store
When you disconnect an external key store with [VPC endpoint service connectivity](choose-xks-connectivity.md#xks-vpc-connectivity) from its external key store proxy, AWS KMS deletes its interface endpoint to the VPC endpoint service and removes the network infrastructure that it created to support the connection. No equivalent process is required for external key stores with public endpoint connectivity. This action does not affect the VPC endpoint service or any of its supporting components, and it does not affect the external key store proxy or any external components.
While the external key store is disconnected, AWS KMS does not send any requests to the external key store proxy. The connection state of the external key store is `DISCONNECTED`. The KMS keys in the disconnected external key store are in an [`UNAVAILABLE` key state](key-state.md) (unless they are [pending deletion](deleting-keys.md)), which means that they cannot be used in cryptographic operations. However, you can still view and manage your external key store and its existing KMS keys.
The disconnected state is designed to be temporary and reversible. You can reconnect your external key store at any time. Typically, no reconfiguration is necessary. However, if any properties of the associated external key store proxy have changed while it was disconnected, such as rotation of its [proxy authentication credential](keystore-external.md#concept-xks-credential), you must [edit the external key store settings](update-xks-keystore.md) before reconnecting.
**Note**
While a custom key store is disconnected, all attempts to create KMS keys in the custom key store or to use existing KMS keys in cryptographic operations will fail. This action can prevent users from storing and accessing sensitive data.
To better estimate the effect of disconnecting your external key store, identify the KMS keys in the external key store and [determine their past use](deleting-keys-determining-usage.md).
You might disconnect an external key store for reasons such as the following:
+ **To edit its properties.** You can edit the custom key store name, proxy URI path, and proxy authentication credential while the external key store is connected. However, to edit the proxy connectivity type, proxy URI endpoint, or VPC endpoint service name, you must first disconnect the external key store. For details, see [Edit external key store properties](update-xks-keystore.md).
+ **To stop all communication** between AWS KMS and the external key store proxy. You can also stop communication between AWS KMS and your proxy by disabling your endpoint or VPC endpoint service. In addition, your external key store proxy or key management software might provide additional mechanisms to prevent AWS KMS from communicating with the proxy or to prevent the proxy from accessing your external key manager.
+ **To disable all KMS keys** in the external key store. You can [disable and re-enable KMS keys](enabling-keys.md) in an external key store by using the AWS KMS console or the [DisableKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DisableKey.html) operation. These operations complete quickly (subject to eventual consistency), but they act on one KMS key at a time. Disconnecting the external key store changes the key state of all KMS keys in the external key store to `Unavailable`, which prevents them from being used in any cryptographic operation.
+ **To repair a failed connection attempt**. If an attempt to connect an external key store fails (the connection state of the custom key store is `FAILED`), you must disconnect the external key store before you try to connect it again.
## Disconnect your external key store
You can disconnect your external key store in the AWS KMS console or by using the [DisconnectCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_DisconnectCustomKeyStore.html) operation.
### Using the AWS KMS console
You can use the AWS KMS console to connect an external key store to its external key store proxy. This process takes about 5 minutes to complete.
1. Sign in to the AWS Management Console and open the AWS Key Management Service (AWS KMS) console at [https://console.aws.amazon.com/kms](https://console.aws.amazon.com/kms).
1. To change the AWS Region, use the Region selector in the upper-right corner of the page.
1. In the navigation pane, choose **Custom key stores**, **External key stores**.
1. Choose the row of the external key store you want to disconnect.
1. From the **Key store actions** menu, choose **Disconnect**.
When the operation completes, the connection state changes from **DISCONNECTING** to **DISCONNECTED**. If the operation fails, an error message appears that describes the problem and provides help on how to fix it. If you need more help, see [External key store connection errors](xks-troubleshooting.md#fix-xks-connection).
### Using the AWS KMS API
To disconnect a connected external key store, use the [DisconnectCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_DisconnectCustomKeyStore.html) operation. If the operation is successful, AWS KMS returns an HTTP 200 response and a JSON object with no properties. The process takes about five minutes to complete. To find the connection state of the external key store, use the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) operation.
The examples in this section use the [AWS Command Line Interface (AWS CLI)](https://aws.amazon.com/cli/), but you can use any supported programming language.
This example disconnects an external key store with VPC endpoint service connectivity. Before running this example, replace the example custom key store ID with a valid one.
```
$ aws kms disconnect-custom-key-store --custom-key-store-id cks-1234567890abcdef0
```
To verify that the external key store is disconnected, use the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) operation. By default, this operation returns all custom keys stores in your account and Region. But you can use either the `CustomKeyStoreId` and `CustomKeyStoreName` parameter (but not both) to limit the response to particular custom key stores. The `ConnectionState` value of `DISCONNECTED` indicates that this example external key store is no longer connected to its external key store proxy.
```
$ aws kms describe-custom-key-stores --custom-key-store-name ExampleXksVpc
{
"CustomKeyStores": [
{
"CustomKeyStoreId": "cks-9876543210fedcba9",
"CustomKeyStoreName": "ExampleXksVpc",
"ConnectionState": "DISCONNECTED",
"CreationDate": "2022-12-13T18:34:10.675000+00:00",
"CustomKeyStoreType": "EXTERNAL_KEY_STORE",
"XksProxyConfiguration": {
"AccessKeyId": "ABCDE98765432EXAMPLE",
"Connectivity": "VPC_ENDPOINT_SERVICE",
"UriEndpoint": "https://example-proxy-uri-endpoint-vpc",
"UriPath": "/example/prefix/kms/xks/v1",
"VpcEndpointServiceName": "com.amazonaws.vpce.us-east-1.vpce-svc-example"
}
}
]
}
```
# Delete an external key store
When you delete an external key store, AWS KMS deletes all metadata about the external key store from AWS KMS, including information about its external key store proxy. This operation does not affect the [external key store proxy](keystore-external.md#concept-xks-proxy), [external key manager](keystore-external.md#concept-ekm), [external keys](keystore-external.md#concept-external-key), or any AWS resources that you created to support the external key store, such as an Amazon VPC or a VPC endpoint service.
Before you delete an external key store, you must [delete all of the KMS keys](deleting-keys.md) from the key store and [disconnect the key store](xks-connect-disconnect.md) from its external key store proxy. Otherwise, attempts to delete the key store fail.
Deleting an external key store is irreversible, but you can create a new external key store and associate it with the same external key store proxy and external key manager. However, you cannot recreate the symmetric encryption KMS keys in the external key store, even you have access to the same external key material. AWS KMS includes metadata in the symmetric ciphertext unique to each KMS key. This security feature ensures that only the KMS key that encrypted the data can decrypt it.
Instead of deleting the external key store, consider disconnecting it. While an external key store is disconnected, you can manage the external key store and its AWS KMS keys but you cannot create or use KMS keys in the external key store. You can reconnect the external key store at any time and resume using its KMS keys to encrypt and decrypt data. There is no cost for a disconnected external key store proxy or its unavailable KMS keys.
You can delete your external key store in the AWS KMS console or by using the [DeleteCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeleteCustomKeyStore.html) operation.
## Using the AWS KMS console
You can use the AWS KMS console to delete an external key store.
1. Sign in to the AWS Management Console and open the AWS Key Management Service (AWS KMS) console at [https://console.aws.amazon.com/kms](https://console.aws.amazon.com/kms).
1. To change the AWS Region, use the Region selector in the upper-right corner of the page.
1. In the navigation pane, choose **Custom key stores**, **External key stores**.
1. Find the row that represents the external key store that you want to delete. If the **Connection state** of the external key store is not **DISCONNECTED**, you must [disconnect the external key store](about-xks-disconnecting.md#disconnect-xks-console) before you delete it.
1. From the **Key store actions** menu, choose **Delete**.
When the operation completes, a success message appears and the external key store no longer appears in the key store list. If the operation is unsuccessful, an error message appears that describes the problem and provides help on how to fix it. If you need more help, see [Troubleshooting external key stores](xks-troubleshooting.md).
## Using the AWS KMS API
To delete an external key store, use the [DeleteCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeleteCustomKeyStore.html) operation. If the operation is successful, AWS KMS returns an HTTP 200 response and a JSON object with no properties.
To begin, disconnect the external key store. Before running this command, replace the example custom key store ID with a valid one.
```
$ aws kms disconnect-custom-key-store --custom-key-store-id cks-1234567890abcdef0
```
After the external key store is disconnected, you can use the [DeleteCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeleteCustomKeyStore.html) operation to delete it.
```
$ aws kms delete-custom-key-store --custom-key-store-id cks-1234567890abcdef0
```
To confirm that the external key store is deleted, use the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) operation.
```
$ aws kms describe-custom-key-stores
{
"CustomKeyStores": []
}
```
If you specify a custom key store name or ID that no longer exists, AWS KMS returns a `CustomKeyStoreNotFoundException` exception.
```
$ aws kms describe-custom-key-stores --custom-key-store-id cks-1234567890abcdef0
An error occurred (CustomKeyStoreNotFoundException) when calling the DescribeCustomKeyStore operation:
```
# Troubleshooting external key stores
The resolution for most problems with external key stores are indicated by the error message that AWS KMS displays with each exception, or by the [connection error code](#fix-xks-connection) that AWS KMS returns when an attempt to [connect the external key store](xks-connect-disconnect.md) to its external key store proxy fails. However, some issues are a bit more complex.
When diagnosing an issue with an external key store, first locate the cause. This will narrow the range of remedies and make your troubleshooting more efficient.
+ AWS KMS — The problem might be within AWS KMS, such as an incorrect value in your [external key store configuration](create-xks-keystore.md#xks-requirements).
+ External — The problem might originate outside of AWS KMS, including problems with the configuration or operation of the external key store proxy, external key manager, external keys, or VPC endpoint service.
+ Networking — It might be a problem with connectivity or networking, such as a problem with your proxy endpoint, port, IP stack, or your private DNS name or domain.
**Note**
When management operations on external key stores fail, they generate several different exceptions. But AWS KMS cryptographic operations return `KMSInvalidStateException` for all failures related to the external configuration or connection state of the external key store. To identify the problem, use the accompanying error message text.
The [ConnectCustomKeyStore](xks-connect-disconnect.md) operation succeeds quickly before the connection process is complete. To determine whether the connection process is successful, view the [connection state](xks-connect-disconnect.md#xks-connection-state) of the external key store. If the connection process fails, AWS KMS returns a [connection error code](#xks-connection-error-codes) that explains the cause and suggests a remedy.
**Topics**
+ [
## Troubleshooting tools for external key stores
](#xks-troubleshooting-tools)
+ [
## Configuration errors
](#fix-xks-configuration)
+ [
## External key store connection errors
](#fix-xks-connection)
+ [
## Latency and timeout errors
](#fix-xks-latency)
+ [
## Authentication credential errors
](#fix-xks-credentials)
+ [
## Key state errors
](#fix-unavailable-xks-keys)
+ [
## Decryption errors
](#fix-xks-decrypt)
+ [
## External key errors
](#fix-external-key)
+ [
## Proxy issues
](#fix-xks-proxy)
+ [
## Proxy authorization issues
](#fix-xks-authorization)
## Troubleshooting tools for external key stores
AWS KMS provides several tools to help you identify and resolve problems with your external key store and its keys. Use these tools in conjunction with the tools provided with your external key store proxy and external key manager.
**Note**
Your external key store proxy and external key manager might provide easier methods of creating and maintaining your external key store and its KMS keys. For details, see the documentation for your external tools.
**AWS KMS exceptions and error messages**
AWS KMS provides a detailed error message about any problem it encounters. You can find additional information about AWS KMS exceptions in the [https://docs.aws.amazon.com/kms/latest/APIReference/](https://docs.aws.amazon.com/kms/latest/APIReference/) and AWS SDKs. Even if you are using the AWS KMS console, you might find these references to be helpful. For example, see the [Errors](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateCustomKeyStore.html#API_CreateCustomKeyStore_Errors) list for the `CreateCustomKeyStores` operation.
To optimize the performance of your external key store proxy, AWS KMS returns exceptions based on your proxy's reliability within a given aggregation period of 5 minutes. In the event of a 500 Internal Server Error, 503 Service Unavailable, or connection timeout, a proxy with high reliability returns `KMSInternalException` and triggers an automatic retry to ensure that requests eventually succeed. However, a proxy with low reliability returns `KMSInvalidStateException`. For more information, see [Monitoring an external key store](https://docs.aws.amazon.com/kms/latest/developerguide/xks-monitoring.html).
If the problem surfaces in a different AWS service, such as when you use a KMS key in your external key store to protect a resource in another AWS service, the AWS service might provide additional information to help you identify the problem. If the AWS service doesn't provide the message, you can view the error message in the [CloudTrail logs](logging-using-cloudtrail.md) that record the use of your KMS key.
**[CloudTrail logs](logging-using-cloudtrail.md)**
Every AWS KMS API operation, including actions in the AWS KMS console, is recorded in AWS CloudTrail logs. AWS KMS records a log entry for successful and failed operations. For failed operations, the log entry includes the AWS KMS exception name (`errorCode`) and the error message (`errorMessage`). You can use this information to help you identify and resolve the error. For an example, see [Decrypt failure with a KMS key in an external key store](ct-decrypt.md#ct-decrypt-xks-fail).
The log entry also includes the request ID. If the request reached your external key store proxy, you can use the request ID in the log entry to find the corresponding request in your proxy logs, if your proxy provides them.
**[CloudWatch metrics](monitoring-cloudwatch.md#kms-metrics)**
AWS KMS records detailed Amazon CloudWatch metrics about the operation and performance of your external key store, including latency, throttling, proxy errors, external key manager status, the number of days until your TLS certificate expires, and the reported age of your proxy authentication credentials. You can use these metrics to develop data models for the operation of your external key store and CloudWatch alarms that alert you to impending problems before they occur.
AWS KMS recommends that you create CloudWatch alarms to monitor the external key store metrics. These alarms will alert you to early signs of problems before they develop.
**[Monitoring graphs](xks-monitoring.md)**
AWS KMS displays graphs of the external key store CloudWatch metrics on the detail page for each external key store in the AWS KMS console. You can use the data in the graphs to help locate the source of errors, detect impending problems, establish baselines, and refine your CloudWatch alarm thresholds. For details about interpreting the monitoring graphs and using their data, see [Monitor external key stores](xks-monitoring.md).
**Displays of external key stores and KMS keys**
AWS KMS displays detailed information about your external key stores and the KMS keys in the external key store in the AWS KMS console, and in the response to the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) and [DescribeKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html) operations. These displays include special fields for external key stores and KMS keys with information that you can use for troubleshooting, such as the [connection state](xks-connect-disconnect.md#xks-connection-state) of the external key store and the ID of the external key that is associated with the KMS key. For details, see [View external key stores](view-xks-keystore.md).
**[XKS Proxy Test Client](https://github.com/aws-samples/aws-kms-xksproxy-test-client)**
AWS KMS provides an open source test client that verifies that your external key store proxy conforms to the [AWS KMS External Key Store Proxy API Specification](https://github.com/aws/aws-kms-xksproxy-api-spec/). You can use this test client to identify and resolve problems with your external key store proxy.
## Configuration errors
When you create an external key store, you specify property values that comprise the *configuration* of your external key store, such as the [proxy authentication credential](create-xks-keystore.md#require-credential), [proxy URI endpoint](create-xks-keystore.md#require-endpoint), [proxy URI path](create-xks-keystore.md#require-path), and [VPC endpoint service name](create-xks-keystore.md#require-vpc-service-name). When AWS KMS detects an error in a property value, the operation fails and returns an error that indicates the faulty value.
Many configuration issues can be resolved by fixing the incorrect value. You can fix an invalid proxy URI path or proxy authentication credential without disconnecting the external key store. For definitions of these values, including uniqueness requirements, see [Assemble the prerequisites](create-xks-keystore.md#xks-requirements). For instructions about updating these values, see [Edit external key store properties](update-xks-keystore.md).
To avoid errors with your proxy URI path and proxy authentication credential values, when creating or updating your external key store, upload a [proxy configuration file](create-xks-keystore.md#proxy-configuration-file) to the AWS KMS console. This is a JSON-based file with proxy URI path and proxy authentication credential values that is provided by your external key store proxy or external key manager. You can't use a proxy configuration file with AWS KMS API operations, but you can use the values in the file to help you provide parameter values for your API requests that match the values in your proxy.
### General configuration errors
**Exceptions**: `CustomKeyStoreInvalidStateException` (`CreateKey`), `KMSInvalidStateException` (cryptographic operations), `XksProxyInvalidConfigurationException` (management operations, except for `CreateKey`)
[**Connection error codes**](#xks-connection-error-codes): `XKS_PROXY_INVALID_CONFIGURATION`, `XKS_PROXY_INVALID_TLS_CONFIGURATION`
For external key stores with [public endpoint connectivity](choose-xks-connectivity.md#xks-connectivity-public-endpoint), AWS KMS tests the property values when you create and update the external key store. For external key stores with [VPC endpoint service connectivity](choose-xks-connectivity.md#xks-vpc-connectivity), AWS KMS tests the property values when you connect and update the external key store.
**Note**
The `ConnectCustomKeyStore` operation, which is asynchronous, might succeed even though the attempt to connect the external key store to its external key store proxy fails. In that case, there is no exception, but the connection state of the external key store is Failed, and a connection error code explains the error message. For more information, see [External key store connection errors](#fix-xks-connection).
If AWS KMS detects an error in a property value, the operation fails and returns `XksProxyInvalidConfigurationException` with one of the following error messages.
| |
| --- |
| The external key store proxy rejected the request because of an invalid URI path. Verify the URI path for your external key store and update if necessary. |
+ The [proxy URI path](create-xks-keystore.md#require-path) is the base path for AWS KMS requests to the proxy APIs. If this path is incorrect, all requests to the proxy fail. To [view the current proxy URI path](view-xks-keystore.md) for your external key store, use the AWS KMS console or the `DescribeCustomKeyStores` operation. To find the correct proxy URI path, see your external key store proxy documentation. For help correcting your proxy URI path value, see [Edit external key store properties](update-xks-keystore.md).
+ The proxy URI path for your external key store proxy can change with updates to your external key store proxy or external key manager. For information about these changes, see the documentation for your external key store proxy or external key manager.
| |
| --- |
| `XKS_PROXY_INVALID_TLS_CONFIGURATION`AWS KMS cannot establish a TLS connection to the external key store proxy. Verify the TLS configuration, including its certificate. |
+ All external key store proxies require a TLS certificate. The TLS certificate must be issued by a public certificate authority (CA) that is supported for external key stores. For list of supported CAs, see [Trusted Certificate Authorities](https://github.com/aws/aws-kms-xksproxy-api-spec/blob/main/TrustedCertificateAuthorities) in the AWS KMS External Key Store Proxy API Specification.
+ For public endpoint connectivity, the subject common name (CN) on the TLS certificate must match the domain name in the [proxy URI endpoint](create-xks-keystore.md#require-endpoint) for the external key store proxy. For example, if the public endpoint is https://myproxy.xks.example.com, the TLS, the CN on the TLS certificate must be `myproxy.xks.example.com` or `*.xks.example.com`.
+ For VPC endpoint service connectivity, the subject common name (CN) on the TLS certificate must match the private DNS name for your [VPC endpoint service](create-xks-keystore.md#require-vpc-service-name). For example, if the private DNS name is myproxy-private.xks.example.com, the CN on the TLS certificate must be `myproxy-private.xks.example.com` or `*.xks.example.com`.
+ The TLS certificate cannot be expired. To get the expiration date of a TLS certificate, use SSL tools, such as [OpenSSL](https://www.openssl.org/). To monitor the expiration date of a TLS certificate associated with an external key store, use the [XksProxyCertificateDaysToExpire](monitoring-cloudwatch.md#metric-xks-proxy-certificate-days-to-expire) CloudWatch metric. The number of days to your TLS certification expiration date also appears in the [**Monitoring** section](xks-monitoring.md) of the AWS KMS console.
+ If you are using [public endpoint connectivity](choose-xks-connectivity.md#xks-connectivity-public-endpoint), use SSL test tools to test your SSL configuration. TLS connection errors can result from incorrect certificate chaining.
### VPC endpoint service connectivity configuration errors
**Exceptions**: `XksProxyVpcEndpointServiceNotFoundException`, `XksProxyVpcEndpointServiceInvalidConfigurationException`
In addition to general connectivity issues, you might encounter the following issues while creating, connecting, or updating an external key store with VPC endpoint service connectivity. AWS KMS tests the property values of an external key store with VPC endpoint service connectivity while [creating](create-xks-keystore.md), [connecting](xks-connect-disconnect.md), and [updating](update-xks-keystore.md) the external key store. When management operations fail due to configuration errors, they generate the following exceptions:
| |
| --- |
| XksProxyVpcEndpointServiceNotFoundException |
The cause might be one of the following:
+ An incorrect VPC endpoint service name. Verify that the VPC endpoint service name for the external key store is correct and matches the proxy URI endpoint value for the external key store. To find the VPC endpoint service name, use the [Amazon VPC console](https://console.aws.amazon.com/vpc) or the [DescribeVpcEndpointServices](https://docs.aws.amazon.com/AmazonVPC/latest/APIReference/DescribeVpcEndpointServices.html) operation. To find the VPC endpoint service name and proxy URI endpoint of an existing external key store, use the AWS KMS console or the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) operation. For details, see [View external key stores](view-xks-keystore.md).
+ The VPC endpoint service might be in a different AWS Region than the external key store. Verify that the VPC endpoint service and external key store are in same Region. (The external name of the Region name, such as `us-east-1`, is part of the VPC endpoint service name, such as com.amazonaws.vpce.us-east-1.vpce-svc-example.) For a list of requirements for the VPC endpoint service for an external key store, see [VPC endpoint service](create-xks-keystore.md#require-vpc-service-name). You cannot move a VPC endpoint service or an external key store to a different Region. However, you can create a new external key store in the same Region as the VPC endpoint service. For details, see [Configure VPC endpoint service connectivity](vpc-connectivity.md) and [Create an external key store](create-xks-keystore.md).
+ AWS KMS is not an allowed principal for the VPC endpoint service. The **Allow principals** list for the VPC endpoint service must include the `cks.kms..amazonaws.com` value, such as `cks.kms.eu-west-3.amazonaws.com`. For instructions about adding this value, see [Manage permissions](https://docs.aws.amazon.com/vpc/latest/privatelink/configure-endpoint-service.html#add-remove-permissions) in the *AWS PrivateLink Guide*.
| |
| --- |
| XksProxyVpcEndpointServiceInvalidConfigurationException |
This error occurs when the VPC endpoint service fails to meet one of the following requirements:
+ The VPC requires at least two private subnets, each in a different Availability Zone. For help adding a subnet to your VPC, see [Create a subnet in your VPC](https://docs.aws.amazon.com/vpc/latest/userguide/working-with-subnets.html#create-subnets) in the *Amazon VPC User Guide*.
+ Your [VPC endpoint service type](https://docs.aws.amazon.com/vpc/latest/privatelink/create-endpoint-service.html) must use a network load balancer, not a gateway load balancer.
+ Acceptance must not be required for the VPC endpoint service (**Acceptance required** must be false.). If manual acceptance of each connection request is required, AWS KMS cannot use the VPC endpoint service to connect to the external key store proxy. For details, see [Accept or reject connection requests](https://docs.aws.amazon.com/vpc/latest/privatelink/configure-endpoint-service.html#accept-reject-connection-requests) in the *AWS PrivateLink Guide*.
+ The VPC endpoint service must have a private DNS name that is a subdomain of a public domain. For example, if the private DNS name is `https://myproxy-private.xks.example.com`, the `xks.example.com` or `example.com` domains must have a public DNS server. To view or change the private DNS name for your VPC endpoint service, see [Manage DNS names for VPC endpoint services](https://docs.aws.amazon.com/vpc/latest/privatelink/manage-dns-names.html) in the *AWS PrivateLink Guide*.
+ The **Domain verification status** of the domain for your private DNS name must be `verified`. To view and update the verification status of the private DNS name domain, see [Step 5: Verify your private DNS name domain](vpc-connectivity.md#xks-private-dns). It might take a few minutes for the updated verification status to appear after you've added the required text record.
**Note**
A private DNS domain can be verified only if it is the subdomain of a public domain. Otherwise, the verification status of the private DNS domain does not change, even after you add the required TXT record.
+ Ensure that any firewalls between AWS KMS and the external key store proxy allow traffic to and from port 443 on the proxy. AWS KMS communicates on port 443 over IPv4. This value is not configurable.
+ The private DNS name of the VPC endpoint service must match the [proxy URI endpoint](create-xks-keystore.md#require-endpoint) value for the external key store. For an external key store with VPC endpoint service connectivity, the proxy URI endpoint must be `https://` followed by the private DNS name of the VPC endpoint service. To view the proxy URI endpoint value, see [View external key stores](view-xks-keystore.md). To change the proxy URI endpoint value, see [Edit external key store properties](update-xks-keystore.md).
## External key store connection errors
The [process of connecting an external key store](about-xks-connecting.md) to its external key store proxy takes about five minutes to complete. Unless it fails quickly, the `ConnectCustomKeyStore` operation returns an HTTP 200 response and a JSON object with no properties. However, this initial response does not indicate that the connection was successful. To determine whether the external key store is connected, see its [connection state](xks-connect-disconnect.md#xks-connection-state). If the connection fails, the connection state of the external key store changes to `FAILED` and AWS KMS returns a [connection error code](#xks-connection-error-codes) that explains the cause of the failure.
**Note**
When the connection state of a custom key store is `FAILED`, you must disconnect the custom key store before attempting to reconnect it. You cannot connect a custom key store with a `FAILED` connection status.
To view the connection state of an external key store:
+ In the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) response, view the value of the `ConnectionState` element.
+ In the AWS KMS console, the **Connection state** appears in the external key store table. Also, on the detail page for each external key store, the **Connection state** appears in the **General configuration** section.
When the connection state is `FAILED`, the connection error code helps to explains the error.
To view the connection error code:
+ In the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) response, view the value of the `ConnectionErrorCode` element. This element appears in the `DescribeCustomKeyStores` response only when the `ConnectionState` is `FAILED`.
+ To view the connection error code in the AWS KMS console, on detail page for the external key store and hover over the **Failed** value.
![\[Connection error code on the custom key store details page\]](http://docs.aws.amazon.com/kms/latest/developerguide/images/connection-error-code.png)
### Connection error codes for external key stores
The following connection error codes apply to external key stores
`INTERNAL_ERROR`
AWS KMS could not complete the request due to an internal error. Retry the request. For `ConnectCustomKeyStore` requests, disconnect the custom key store before trying to connect again.
`INVALID_CREDENTIALS`
One or both of the `XksProxyAuthenticationCredential` values is not valid on the specified external key store proxy.
`NETWORK_ERRORS`
Network errors are preventing AWS KMS from connecting the custom key store to its backing key store.
`XKS_PROXY_ACCESS_DENIED`
AWS KMS requests are denied access to the external key store proxy. If the external key store proxy has authorization rules, verify that they permit AWS KMS to communicate with the proxy on your behalf.
`XKS_PROXY_INVALID_CONFIGURATION`
A configuration error is preventing the external key store from connecting to its proxy. Verify the value of the `XksProxyUriPath`.
`XKS_PROXY_INVALID_RESPONSE`
AWS KMS cannot interpret the response from the external key store proxy. If you see this connection error code repeatedly, notify your external key store proxy vendor.
`XKS_PROXY_INVALID_TLS_CONFIGURATION`
AWS KMS cannot connect to the external key store proxy because the TLS configuration is invalid. Verify that the external key store proxy supports TLS 1.2 or 1.3. Also, verify that the TLS certificate is not expired, that it matches the hostname in the `XksProxyUriEndpoint` value, and that it is signed by a trusted certificate authority included in the [Trusted Certificate Authorities](https://github.com/aws/aws-kms-xksproxy-api-spec/blob/main/TrustedCertificateAuthorities) list.
`XKS_PROXY_NOT_REACHABLE`
AWS KMS can't communicate with your external key store proxy. Verify that the `XksProxyUriEndpoint` and `XksProxyUriPath` are correct. Use the tools for your external key store proxy to verify that the proxy is active and available on its network. Also, verify that your external key manager instances are operating properly. Connection attempts fail with this connection error code if the proxy reports that all external key manager instances are unavailable.
`XKS_PROXY_TIMED_OUT`
AWS KMS can connect to the external key store proxy, but the proxy does not respond to AWS KMS in the time allotted. If you see this connection error code repeatedly, notify your external key store proxy vendor.
`XKS_VPC_ENDPOINT_SERVICE_INVALID_CONFIGURATION`
The Amazon VPC endpoint service configuration doesn't conform to the requirements for an AWS KMS external key store.
+ The VPC endpoint service must be an endpoint service for interface endpoints in the caller's AWS account.
+ It must have a network load balancer (NLB) connected to at least two subnets, each in a different Availability Zone.
+ The `Allow principals` list must include the AWS KMS service principal for the Region, `cks.kms..amazonaws.com`, such as `cks.kms.us-east-1.amazonaws.com`.
+ It must *not* require [acceptance](https://docs.aws.amazon.com/vpc/latest/privatelink/create-endpoint-service.html) of connection requests.
+ It must have a private DNS name. The private DNS name for an external key store with `VPC_ENDPOINT_SERVICE` connectivity must be unique in its AWS Region.
+ The domain of the private DNS name must have a [verification status](https://docs.aws.amazon.com/vpc/latest/privatelink/verify-domains.html) of `verified`.
+ The [TLS certificate](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/create-tls-listener.html) specifies the private DNS hostname at which the endpoint is reachable.
`XKS_VPC_ENDPOINT_SERVICE_NOT_FOUND`
AWS KMS can't find the VPC endpoint service that it uses to communicate with the external key store proxy. Verify that the `XksProxyVpcEndpointServiceName` is correct and the AWS KMS service principal has service consumer permissions on the Amazon VPC endpoint service.
## Latency and timeout errors
**Exceptions**: `CustomKeyStoreInvalidStateException` (`CreateKey`), `KMSInvalidStateException` (cryptographic operations), `XksProxyUriUnreachableException` (management operations)
[**Connection error codes**](#xks-connection-error-codes): `XKS_PROXY_NOT_REACHABLE`, `XKS_PROXY_TIMED_OUT`
When AWS KMS can't contact the proxy within the 250 millisecond timeout interval, it returns an exception. `CreateCustomKeyStore` and `UpdateCustomKeyStore` return `XksProxyUriUnreachableException`. Cryptographic operations return the standard `KMSInvalidStateException` with an error message that describes the problem. If `ConnectCustomKeyStore` fails, AWS KMS returns a [connection error code](#fix-xks-connection) that describes the problem.
Timeout errors might be transient issues that can be resolved by retrying the request. If the problem persists, verify that your external key store proxy is active and is connected to the network, and that its proxy URI endpoint, proxy URI path, and VPC endpoint service name (if any) are correct in your external key store. Also, verify that your external key manager is close to the AWS Region for your external key store. If you need to update any of these values, see [Edit external key store properties](update-xks-keystore.md).
To track latency patterns, use the [`XksProxyLatency`](monitoring-cloudwatch.md#metric-xks-proxy-latency) CloudWatch metric and the **Average latency** graph (based on that metric) in the [**Monitoring** section](xks-monitoring.md) of the AWS KMS console. Your external key store proxy might also generate logs and metrics that track latency and timeouts.
| |
| --- |
| `XksProxyUriUnreachableException`AWS KMS cannot communicate with the external key store proxy. This might be a transient network issue. If you see this error repeatedly, verify that your external key store proxy is active and is connected to the network, and that its endpoint URI is correct in your external key store. |
+ The external key store proxy didn't respond to an AWS KMS proxy API request within the 250 millisecond timeout interval. This might indicate a transient network problem or an operational or performance problem with the proxy. If retrying doesn't solve the problem, notify your external key store proxy administrator.
Latency and timeout errors often manifest as connection failures. When the [ConnectCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_ConnectCustomKeyStore.html) operation fails, the *connection state* of the external key store changes to `FAILED` and AWS KMS returns a *connection error code* that explains the error. For a list of connection error codes and suggestions for resolving the errors, see [Connection error codes for external key stores](#xks-connection-error-codes). The connection codes lists for **All custom key stores** and **External key stores** apply to external key stores. The following connection errors are related to latency and timeouts.
| |
| --- |
| `XKS_PROXY_NOT_REACHABLE`-or-`CustomKeyStoreInvalidStateException`, `KMSInvalidStateException`, `XksProxyUriUnreachableException`AWS KMS cannot communicate with the external key store proxy. Verify that your external key store proxy is active and is connected to the network, and that its URI path and endpoint URI or VPC service name are correct in your external key store. |
This error might occur for the following reasons:
+ The external key store proxy is not active and or not connected to the network.
+ There is an error in the [proxy URI endpoint](create-xks-keystore.md#require-endpoint), [proxy URI path](create-xks-keystore.md#require-path), or [VPC endpoint service name](create-xks-keystore.md#require-vpc-service-name) (if applicable) values in the external key store configuration. To view the external key store configuration, use the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) operation or [view the detail page](view-xks-keystore.md) for the external key store in the AWS KMS console.
+ There might be a network configuration error, such as a port error, on the network path between AWS KMS and the external key store proxy. AWS KMS communicates with the external key store proxy on port 443 over IPv4. This value is not configurable.
+ When the external key store proxy reports (in a [GetHealthStatus](keystore-external.md#concept-proxy-apis) response) that all external key manager instances are `UNAVAILABLE`, the [ConnectCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_ConnectCustomKeyStore.html) operation fails with a `ConnectionErrorCode` of `XKS_PROXY_NOT_REACHABLE`. For help, see your external key manager documentation.
+ This error can result from a long physical distance between the external key manager and the AWS Region with the external key store. The ping latency (network round-trip time (RTT)) between the AWS Region and the external key manager should be no more than 35 milliseconds. You might have to create an external key store in an AWS Region that is closer to the external key manager, or move the external key manager to a data center that is closer to the AWS Region.
| |
| --- |
| `XKS_PROXY_TIMED_OUT`-or-`CustomKeyStoreInvalidStateException`, `KMSInvalidStateException`, `XksProxyUriUnreachableException`AWS KMS rejected the request because the external key store proxy did not respond in time. Retry the request. If you see this error repeatedly, report it to your external key store proxy administrator. |
This error might occur for the following reasons:
+ This error can result from a long physical distance between the external key manager and the external key store proxy. If possible, move the external key store proxy closer to the external key manager.
+ Timeout errors can occur when the proxy is not designed to handle the volume and frequency of requests from AWS KMS. If your CloudWatch metrics indicate a persistent problem, notify your external key store proxy administrator.
+ Timeout errors can occur when the connection between the external key manager and the Amazon VPC for the external key store is not operating properly. If you are using AWS Direct Connect, verify that your VPC and external key manager can communicate effectively. For help resolving any issues, see [Troubleshooting AWS Direct Connect](https://docs.aws.amazon.com/directconnect/latest/UserGuide/Troubleshooting.html) in the Direct Connect User Guide.
| |
| --- |
| `XKS_PROXY_TIMED_OUT`-or-`CustomKeyStoreInvalidStateException`, `KMSInvalidStateException`, `XksProxyUriUnreachableException` The external key store proxy did not respond to the request in the time allotted. Retry the request. If you see this error repeatedly, report it to your external key store proxy administrator. |
+ This error can result from a long physical distance between the external key manager and the external key store proxy. If possible, move the external key store proxy closer to the external key manager.
## Authentication credential errors
**Exceptions**: `CustomKeyStoreInvalidStateException` (`CreateKey`), `KMSInvalidStateException` (cryptographic operations), `XksProxyIncorrectAuthenticationCredentialException` (management operations other than `CreateKey`)
You establish and maintain an authentication credential for AWS KMS on your external key store proxy. Then you tell AWS KMS the credential values when you create an external key store. To change the authentication credential, make the change on your external key store proxy. Then [update the credential](update-xks-keystore.md#xks-edit-name) for your external key store. If your proxy rotates the credential, you must [update the credential](update-xks-keystore.md#xks-edit-name) for your external key store.
If the external key store proxy won't authenticate a request signed with the [proxy authentication credential](keystore-external.md#concept-xks-credential) for your external key store, the effect depends on the request:
+ `CreateCustomKeyStore` and `UpdateCustomKeyStore` fail with an `XksProxyIncorrectAuthenticationCredentialException`.
+ `ConnectCustomKeyStore` succeeds, but the connection fails. The connection state is `FAILED` and the connection error code is `INVALID_CREDENTIALS`. For details, see [External key store connection errors](#fix-xks-connection).
+ Cryptographic operations return `KMSInvalidStateException` for all external configuration errors and connection state errors in an external key store. The accompanying error message describes the problem.
| |
| --- |
| The external key store proxy rejected the request because it could not authenticate AWS KMS. Verify the credentials for your external key store and update if necessary. |
This error might occur for the following reasons:
+ The access key ID or the secret access key for the external key store doesn't match the values established on the external key store proxy.
To fix this error, [update the proxy authentication credential](update-xks-keystore.md#xks-edit-name) for your external key store. You can make this change without disconnecting your external key store.
+ A reverse proxy between AWS KMS and the external key store proxy could be manipulating HTTP headers in a manner that invalidates the SigV4 signatures. To fix this error, notify your proxy administrator.
## Key state errors
**Exceptions**: `KMSInvalidStateException`
`KMSInvalidStateException` is used for two distinct purposes for KMS keys in custom key stores.
+ When a management operation, such as `CancelKeyDeletion`, fails and returns this exception, it indicates that the [key state](key-state.md) of the KMS key is not compatible with the operation.
+ When a [cryptographic operation](kms-cryptography.md#cryptographic-operations) on a KMS key in a custom key store fails with `KMSInvalidStateException`, it can indicate a problem with the key state of the KMS key. But AWS KMS cryptographic operation return `KMSInvalidStateException` for all external configuration errors and connection state errors in an external key store. To identify the problem, use the error message that accompanies the exception.
To find the required key state for an AWS KMS API operations, see [Key states of AWS KMS keys](key-state.md). To find the key state of a KMS key, on the **Customer managed keys** page, view the **Status** field of the KMS key. Or, use the [DescribeKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html) operation and view the `KeyState` element in the response. For details, see [Identify and view keys](viewing-keys.md).
**Note**
The key state of a KMS key in an external key store does not indicate anything about the status of its associated [external key](keystore-external.md#concept-external-key). For information about the external key status, use your external key manager and external key store proxy tools.
The `CustomKeyStoreInvalidStateException` refers to the [connection state](xks-connect-disconnect.md#xks-connection-state) of the external key store, not the [key state](key-state.md) of a KMS key.
A cryptographic operation on a KMS key in a custom store might fail because the key state of the KMS key is `Unavailable` or `PendingDeletion`. (Disabled keys return `DisabledException`.)
+ A KMS key has a `Disabled` key state only when you intentionally disable the KMS key in the AWS KMS console or by using the [DisableKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DisableKey.html) operation. While a KMS key is disabled, you can view and manage the key, but you cannot use it in cryptographic operations. To fix this problem, enable the key. For details, see [Enable and disable keys](enabling-keys.md).
+ A KMS key has an `Unavailable` key state when the external key store is disconnected from its external key store proxy. To fix an unavailable KMS key, [reconnect the external key store](xks-connect-disconnect.md). After the external key store is reconnected, the key state of the KMS keys in the external key store is automatically restored to its previous state, such as `Enabled` or `Disabled`.
A KMS key has a `PendingDeletion` key state when it has been scheduled for deletion and is in its waiting period. A key state error on a KMS key that is pending deletion indicates that the key should not be deleted, either because it's being used for encryption, or it is required for decryption. To re-enable the KMS key, cancel the scheduled deletion, and then [enable the key](enabling-keys.md). For details, see [Schedule key deletion](deleting-keys-scheduling-key-deletion.md).
## Decryption errors
**Exceptions**: `KMSInvalidStateException`
When a [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) operation with a KMS key in an external key store fails, AWS KMS returns the standard `KMSInvalidStateException` that cryptographic operations use for all external configuration errors and connection state errors on an external key store. The error message indicates the problem.
To decrypt a ciphertext that was encrypted using [double encryption](keystore-external.md#concept-double-encryption), the external key manager first uses the external key to decrypt the outer layer of ciphertext. Then AWS KMS uses the AWS KMS key material in the KMS key to decrypt the inner layer of ciphertext. An invalid or corrupt ciphertext can be rejected by the external key manager or AWS KMS.
The following error messages accompany the `KMSInvalidStateException` when decryption fails. It indicates a problem with the ciphertext or the optional encryption context in the request.
| |
| --- |
| The external key store proxy rejected the request because the specified ciphertext or additional authenticated data is corrupted, missing, or otherwise invalid. |
+ When the external key store proxy or external key manager report that a ciphertext or its encryption context is invalid, it typically indicates a problem with the ciphertext or encryption context in the `Decrypt` request sent to AWS KMS. For `Decrypt` operations, AWS KMS sends the proxy the same ciphertext and encryption context it receives in the `Decrypt` request.
This error might be caused by a networking problem in transit, such as a flipped bit. Retry the `Decrypt` request. If the problem persists, verify that the ciphertext was not altered or corrupted. Also, verify that the encryption context in the `Decrypt` request to AWS KMS matches the encryption context in the request that encrypted the data.
| |
| --- |
| The ciphertext that the external key store proxy submitted for decryption, or the encryption context, is corrupted, missing, or otherwise invalid. |
+ When AWS KMS rejects the ciphertext that it received from the proxy, it indicates that the external key manager or proxy returned an invalid or corrupt ciphertext to AWS KMS.
This error might be caused by a networking problem in transit, such as a flipped bit. Retry the `Decrypt` request. If the problem persists, verify that the external key manager is operating properly, and that the external key store proxy does not alter the ciphertext that it receives from the external key manager before it returns it to AWS KMS.
## External key errors
An [external key](keystore-external.md#concept-external-key) is a cryptographic key in the external key manager that serves as the external key material for a KMS key. AWS KMS cannot directly access the external key. It must ask the external key manager (via the external key store proxy) to use the external key to encrypt data or decrypt a ciphertext.
You specify the ID of the external key in its external key manager when you create a KMS key in your external key store. You cannot change the external key ID after the KMS key is created. To prevent problems with the KMS key, the `CreateKey` operation asks the external key store proxy to verify the ID and configuration of the external key. If the external key doesn't [fulfill the requirements](create-xks-keys.md#xks-key-requirements) for use with a KMS key, the `CreateKey` operation fails with an exception and error message that identifies the problem.
However, issues can occur after the KMS key is created. If a cryptographic operation fails because of a problem with the external key, the operation fails and returns an `KMSInvalidStateException` with an error message that indicates the problem.
### CreateKey errors for the external key
**Exceptions**: `XksKeyAlreadyInUseException`, `XksKeyNotFoundException`, `XksKeyInvalidConfigurationException`
The [CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) operation attempts to verify the ID and properties of the external key that you provide in the **External key ID** (console) or `XksKeyId` (API) parameter. This practice is designed to detect errors early before you try to use the external key with the KMS key.
**External key in use**
Each KMS key in an external key store must use a different external key. When `CreateKey` recognizes that the external key ID (XksKeyId) for a KMS key is not unique in the external key store, it fails with an `XksKeyAlreadyInUseException`.
If you use multiple IDs for the same external key, `CreateKey` won't recognize the duplicate. However, KMS keys with the same external key are not interoperable because they have different AWS KMS key material and metadata.
**External key not found**
When the external key store proxy reports that it cannot find the external key using the external key ID (XksKeyId) for the KMS key, the `CreateKey` operation fails and returns `XksKeyNotFoundException` with the following error message.
| |
| --- |
| The external key store proxy rejected the request because it could not find the external key. |
This error might occur for the following reasons:
+ The ID of the external key (`XksKeyId`) for the KMS key might be invalid. To find the ID for your external key proxy uses to identify the external key, see your external key store proxy or external key manager documentation.
+ The external key might have been deleted from your external key manager. To investigate, use your external key manager tools. If the external key is permanently deleted, use a different external key with the KMS key. For a list or requirements for the external key, see [Requirements for a KMS key in an external key store](create-xks-keys.md#xks-key-requirements).
**External key requirements not met**
When the external key store proxy reports that the external key does not [fulfill the requirements](create-xks-keys.md#xks-key-requirements) for use with a KMS key, the `CreateKey` operation fails and returns `XksKeyInvalidConfigurationException` with one of the following error messages.
| |
| --- |
| The key spec of the external key must be AES\$1256. The key spec of specified external key is . |
+ The external key must be a 256-bit symmetric encryption key with a key spec of AES\$1256. If the specified external key is a different type, specify the ID of an external key that fulfills this requirement.
| |
| --- |
| The status of the external key must be ENABLED. The status of specified external key is . |
+ The external key must be enabled in the external key manager. If the specified external key is not enabled, use your external key manager tools to enable it, or specify an enabled external key.
| |
| --- |
| The key usage of the external key must include ENCRYPT and DECRYPT. The key use of specified external key is . |
+ The external key must be configured for encryption and decryption in the external key manager. If the specified external key does not include these operations, use your external key manager tools to change the operations, or specify a different external key.
### Cryptographic operation errors for the external key
**Exceptions**: `KMSInvalidStateException`
When the external key store proxy cannot find the external key associated with the KMS key, or the external key doesn't [fulfill the requirements](create-xks-keys.md#xks-key-requirements) for use with a KMS key, the cryptographic operation fails.
External key issues that are detected during a cryptographic operation are more difficult to resolve than external key issues detected before creating the KMS key. You cannot change the external key ID after the KMS key is created. If the KMS key has not yet encrypted any data, you can delete the KMS key and create a new one with a different external key ID. However, ciphertext generated with the KMS key cannot be decrypted by any other KMS key, even one with the same external key, because keys will have different key metadata and different AWS KMS key material. Instead, to the extent possible, use your external key manager tools to resolve the problem with the external key.
When the external key store proxy reports a problem with the external key, cryptographic operations return `KMSInvalidStateException` with an error message that identifies the problem.
**External key not found**
When the external key store proxy reports that it cannot find the external key using the external key ID (XksKeyId) for the KMS key, cryptographic operations return a `KMSInvalidStateException` with the following error message.
| |
| --- |
| The external key store proxy rejected the request because it could not find the external key. |
This error might occur for the following reasons:
+ The ID of the external key (`XksKeyId`) for the KMS key is no longer valid.
To find the external key ID associated with your KMS key, [view the details of the KMS key](identify-key-types.md#view-xks-key). To find the ID that your external key proxy uses to identify the external key, see your external key store proxy or external key manager documentation.
AWS KMS verifies the external key ID when it creates a KMS key in an external key store. However, the ID might become invalid, especially if the external key ID value is an alias or mutable name. You cannot change the external key ID associated with an existing KMS key. To decrypt any ciphertext encrypted under the KMS key, you must re-associate the external key with the existing external key ID.
If you have not yet used the KMS key to encrypt data, you can create a new KMS key with a valid external key ID. However, if you have generated ciphertext with the KMS key, you cannot use any other KMS key to decrypt the ciphertext, even if uses the same external key.
+ The external key might have been deleted from your external key manager. To investigate, use your external key manager tools. If possible, try to [recover the key material](fix-keystore.md#fix-keystore-recover-backing-key) from a copy or backup of your external key manager. If the external key is permanently deleted, any ciphertext encrypted under the associated KMS key is unrecoverable.
**External key configuration errors**
When the external key store proxy reports that the external key doesn't [fulfill the requirements](create-xks-keys.md#xks-key-requirements) for use with a KMS key, the cryptographic operation returns `KMSInvalidStateException` with the one of the following error messages.
| |
| --- |
| The external key store proxy rejected the request because the external key does not support the requested operation. |
+ The external key must support both encryption and decryption. If the key usage does not include encryption and decryption, use your external key manager tools to change the key usage.
| |
| --- |
| The external key store proxy rejected the request because the external key is not enabled in the external key manager. |
+ The external key must be enabled and available for use in the external key manager. If the status of the external key is not `Enabled`, use your external key manager tools to enable it.
## Proxy issues
**Exceptions**:
`CustomKeyStoreInvalidStateException` (`CreateKey`), `KMSInvalidStateException` (cryptographic operations), `UnsupportedOperationException`, `XksProxyUriUnreachableException`, `XksProxyInvalidResponseException` (management operations other than `CreateKey`)
The external key store proxy mediates all communication between AWS KMS and the external key manager. It translates generic AWS KMS requests into a format that your external key manager can understand. If the external key store proxy doesn't conform to the [AWS KMS External Key Store Proxy API Specification](https://github.com/aws/aws-kms-xksproxy-api-spec/), or if isn't operating properly, or can't communicate with AWS KMS, you won't be able to create or use KMS keys in your external key store.
While many errors mention the external key store proxy because of its critical role in the external key store architecture, those problem might originate in the external key manager or external key.
The issues in this section relate to problems with the design or operation of the external key store proxy. Resolving these issues might require a change to the proxy software. Consult your proxy administrator. To help diagnose proxy issues, AWS KMS provides [XKS Proxy Text Client](https://github.com/aws-samples/aws-kms-xksproxy-test-client), an open source test client that verifies that your external key store proxy conforms to the [AWS KMS External Key Store Proxy API Specification](https://github.com/aws/aws-kms-xksproxy-api-spec/).
| |
| --- |
| `CustomKeyStoreInvalidStateException`, `KMSInvalidStateException` or `XksProxyUriUnreachableException`The external key store proxy is in an unhealthy state. If you see this message repeatedly, notify your external key store proxy administrator. |
+ This error can indicate an operational problem or software error in the external key store proxy. You can find CloudTrail log entries for the AWS KMS API operation that generated each error. This error might be resolved by retrying the operation. However, if it persists, notify your external key store proxy administrator.
+ When the external key store proxy reports (in a [GetHealthStatus](keystore-external.md#concept-proxy-apis) response) that all external key manager instances are `UNAVAILABLE`, attempts to create or update an external key store fail with this exception. If this error persists, consult your external key manager documentation.
| |
| --- |
| `CustomKeyStoreInvalidStateException`, `KMSInvalidStateException` or `XksProxyInvalidResponseException`AWS KMS cannot interpret the response from the external key store proxy. If you see this error repeatedly, consult your external key store proxy administrator. |
+ AWS KMS operations generate this exception when the proxy returns an undefined response that AWS KMS cannot parse or interpret. This error might occur occasionally due to temporarily external issues or sporadic network errors. However, if it persists, it might indicate that the external key store proxy doesn't conform to the [AWS KMS External Key Store Proxy API Specification](https://github.com/aws/aws-kms-xksproxy-api-spec/). Notify your external key store administrator or vendor.
| |
| --- |
| `CustomKeyStoreInvalidStateException`, `KMSInvalidStateException` or `UnsupportedOperationException` The external key store proxy rejected the request because it does not support the requested cryptographic operation. |
+ The external key store proxy should support all [proxy APIs](keystore-external.md#concept-proxy-apis) defined in the [AWS KMS External Key Store Proxy API Specification](https://github.com/aws/aws-kms-xksproxy-api-spec/). This error indicates that the proxy does not support the operation that is related to the request. Notify your external key store administrator or vendor.
## Proxy authorization issues
**Exceptions**: `CustomKeyStoreInvalidStateException`, `KMSInvalidStateException`
Some external key store proxies implement authorization requirements for the use of its external keys. An external key store proxy is permitted, but not required, to design and implement an authorization scheme that allows particular users to request particular operations under certain conditions. For example, a proxy might allow a user to encrypt with a particular external key, but not to decrypt with it. For more information, see [External key store proxy authorization (optional)](authorize-xks-key-store.md#xks-proxy-authorization).
Proxy authorization is based on metadata that AWS KMS includes in its requests to the proxy. The `awsSourceVpc` and `awsSourceVpce` fields are included in the metadata only when the request is from a VPC endpoint and only when the caller is in the same account as the KMS key.
```
"requestMetadata": {
"awsPrincipalArn": string,
"awsSourceVpc": string, // optional
"awsSourceVpce": string, // optional
"kmsKeyArn": string,
"kmsOperation": string,
"kmsRequestId": string,
"kmsViaService": string // optional
}
```
When the proxy rejects a request due to an authorization failure, the related AWS KMS operation fails. `CreateKey` returns `CustomKeyStoreInvalidStateException`. AWS KMS cryptographic operations return `KMSInvalidStateException`. Both use the following error message:
| |
| --- |
| The external key store proxy denied access to the operation. Verify that the user and the external key are both authorized for this operation, and try the request again. |
+ To resolve the error, use your external key manager or external key store proxy tools to determine why authorization failed. Then, update the procedure that caused the unauthorized request or use your external key store proxy tools to update the authorization policy. You cannot resolve this error in AWS KMS.