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:
-
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, including the connectivity type, proxy URI endpoint and path, and the access key ID of your current proxy authentication credential.
-
If the external key store proxy uses VPC endpoint service connectivity, the console displays the name of the VPC endpoint service.
-
The current 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.
A Monitoring section with graphs of Amazon CloudWatch 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.
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.
-
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
. -
To change the Amazon Web Services Region, use the Region selector in the upper-right corner of the page.
In the navigation pane, choose Custom key stores, External key stores.
-
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)
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" } } ] }