Disconnect an external key store
When you disconnect an external key store with VPC endpoint service connectivity from its external key store proxy, Amazon 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, Amazon 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 (unless they
are pending deletion), 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, you must edit the external key store settings 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.
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.
-
To stop all communication between Amazon KMS and the external key store proxy. You can also stop communication between Amazon 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 Amazon 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 in an external key store by using the Amazon KMS console or the DisableKey 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 Amazon KMS console or by using the DisconnectCustomKeyStore operation.
You can use the Amazon KMS console to connect an external key store to its external key store proxy. This process takes about 5 minutes to complete.
-
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.
-
Choose the row of the external key store you want to disconnect.
-
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.
To disconnect a connected external key store, use the DisconnectCustomKeyStore operation. If the operation is successful, Amazon 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 operation.
The examples in this section use the Amazon Command Line Interface
(Amazon CLI)
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
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" } } ] }