Connect an external key store - AWS Key Management Service
Connect and reconnect to your external key store

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 and use its existing KMS keys in cryptographic operations.

The process that connects an external key store to its external key store proxy differs based on the connectivity of 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 operation to view the 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.

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 operation.

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.

  2. To change the AWS 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. Choose the row of the external key store you want to connect.

    If the connection state of the external key store is FAILED, you must disconnect the external key store before you connect it.

  5. 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 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. To connect an external key store with a Failed connection state, you must first disconnect the custom key store.

To connect a disconnected external key store, use the ConnectCustomKeyStore operation.

Before connecting, the connection state of the external key store must be DISCONNECTED. If the current connection state is FAILED, disconnect the external key store, 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 response.

The examples in this section use the AWS Command Line Interface (AWS 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 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 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.

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