View external key stores - Amazon Key Management Service
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

View external key stores

You can view external key stores in each account and Region by using the Amazon KMS console or by using the DescribeCustomKeyStores operation.

When you view an external key store, you can see the following:

External key store properties

The following properties of an external key store are visible in the Amazon KMS console and the DescribeCustomKeyStores 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 Amazon CloudHSM key stores and external key stores.

Custom key store ID

A unique ID that Amazon 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 Amazon 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 Amazon Web Services 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.

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 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 in the Creating an external key store topic.

Proxy connectivity

Indicates whether the external key store uses public endpoint connectivity or VPC endpoint service connectivity.

Proxy URI endpoint

The endpoint that Amazon KMS uses to connect to your external key store proxy.

Proxy URI path

The path from the proxy URI endpoint where Amazon KMS sends proxy API requests.

Proxy credential: Access key ID

Part of the proxy authentication credential that you establish on your external key store proxy. The access key ID identifies the secret access key in the credential.

Amazon 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 Amazon 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. 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 Amazon KMS console or by using the DescribeCustomKeyStores operation.

To view the external key stores in a given account and Region, use the following procedure.

  1. Sign in to the Amazon Web Services Management Console and open the Amazon Key Management Service (Amazon KMS) console at https://console.amazonaws.cn/kms.

  2. To change the Amazon Web Services Region, use the Region selector in the upper-right corner of the page.

  3. In the navigation pane, choose Custom key stores, External key stores.

  4. To view detailed information about an external key store, choose the key store name.

To view your external key stores, use the DescribeCustomKeyStores 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 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.

For external key stores, the output also includes the XksProxyConfiguration element. This element includes the connectivity type, proxy URI endpoint, proxy URI path, and the access key ID of the proxy authentication credential.

The examples in this section use the Amazon Command Line Interface (Amazon 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 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 Amazon KMS can connect to the external key store proxy, but the connection failed because the external key store proxy did not respond to Amazon 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.

$ 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" } } ] }