Configuring VPC endpoint service connectivity - 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.

Configuring VPC endpoint service connectivity

Use the guidance in this section to create and configure the Amazon resources and related components that are required for an external key store that uses VPC endpoint service connectivity. The resources listed for this connectivity option are a supplement to the resources required for all external key stores. After you create and configure the required resources, you can create your external key store.

You can locate your external key store proxy in your Amazon VPC or locate the proxy outside of Amazon and use your VPC endpoint service for communication.

Before you begin, confirm that you need an external key store. Most customer can use KMS keys backed by Amazon 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 Amazon resources in this section, consult your proxy and key manager documentation.

Requirements for VPC endpoint service connectivity

If you choose VPC endpoint service connectivity for your external key store, the following resources are required.

To minimize network latency, create your Amazon components in the supported Amazon Web Services Region that is closest to your external key manager. If possible, choose a Region with a network round-trip time (RTT) of 35 milliseconds or less.

  • An Amazon VPC that is connected to your external key manager. It must have at least two private subnets in two different Availability Zones.

    You can use an existing Amazon VPC for your external key store, provided that it fulfills the 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 Amazon PrivateLink with a network load balancer and target group.

    The endpoint service cannot require acceptance. Also, you must add Amazon KMS as an allowed principal. This allows Amazon 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 Amazon Web Services 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 of the DNS domain for private DNS name.

  • A TLS certificate issued by a supported public certificate authority 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.

For all requirements for an external key store, see the Assemble the prerequisites.

Creating 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 in the Amazon Virtual Private Cloud User Guide.

Requirements for your Amazon VPC

To work with external key stores using VPC endpoint service connectivity, the Amazon VPC must have the following properties:

  • Must be in the same Amazon Web Services account and supported Region 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.

  • 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 and Network-to-Amazon VPC connectivity options. For more details, see Amazon Direct Connect, and the Amazon Site-to-Site VPN User Guide.

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

Creating 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 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 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

Creating a network load balancer

The network load balancer distributes the network traffic, including requests from Amazon KMS to your external key store proxy, to the configured targets.

Follow the instructions in the Configure a load balancer and a listener 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 for your network load balancer.

Creating 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 Amazon 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 must must be in the same Amazon Web Services account and supported Region as your 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.

Follow the instructions in the Create an endpoint service 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 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. Amazon KMS cannot connect to the VPC endpoint service without a manual acceptance. If acceptance is required, attempts to create the external key store 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 Amazon Web Services 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.

Supported IP address types IPv4

Verifying 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. Amazon 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.

If the verification status is not verified, follow the instructions in the Domain ownership verification 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 Amazon KMS creates an interface endpoint to your VPC endpoint service, Amazon PrivateLink automatically creates a hosted zone with the required A record for the private domain name in the Amazon KMS VPC. For external key stores with VPC endpoint service connectivity, this happens when you connect your external key store to its external key store proxy.

Authorizing Amazon KMS to connect to the VPC endpoint service

You must add Amazon KMS to the Allow principals list for your VPC endpoint service. This allows Amazon KMS to create interface endpoints to your VPC endpoint service. If Amazon 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 topic in the Amazon PrivateLink Guide. Use the following required value.

Field Value
ARN cks.kms.<region>.amazonaws.com

For example, cks.kms.us-east-1.amazonaws.com

Next: Creating an external key store