Background

External Key Stores is a new capability in AWS Key Management Service (AWS KMS) that allows customers to protect their data in AWS using cryptographic keys held inside on-premises Hardware Security Modules (HSMs) or other key managers outside of AWS. This integration mimics existing support for AWS CloudHSM within KMS except that the customer-controlled HSM resides outside of an AWS data center. This document uses the term external key manager to cover both external HSMs and external software-only key managers (aka virtual HSMs).

AWS services typically do not use a KMS key directly for encrypting customer data. Instead, they generate data keys and use envelope encryption to protect customer data. The data keys are encrypted using a KMS key and kept next to the data they encrypt. The plaintext version of the data key is held in-memory by the integrated service only for a short period. Attempts to access encrypted customer data result in a decrypt API call to KMS to get the plaintext data key. When the key material for a KMS key is hosted in external key managers, cryptographic operations to unwrap/wrap the data key are performed in a customer-chosen datacenter outside AWS.

The new capability is meant to support a variety of external key managers from different vendors. The architecture introduces a proxy, the External Key Store Proxy (aka XKS Proxy), whose primary purpose is to abstract away the API differences across various types of external key managers. The XKS Proxy presents KMS with a uniform API interface described in this document. KMS maintains a fleet of hosts, the XKS Proxy Management Fleet, that communicates with multiple instances of XKS Proxies. The rest of this document describes Version 1 of the XKS Proxy interface including message formats, authentication and authorization controls, error conditions and additional implementation guidance.

KMS keys whose key material resides in an external key manager can be distinguished from other KMS keys by their Origin which is set to EXTERNAL_KEY_STORE.

This document assumes familiarity with the AWS KMS API and standard Base64 encoding as defined in RFC 4687.

Requirements Terminology

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119

High level architecture

Figure 1: High-level KMS architecture with its main components for External Key Store (XKS) support.

Figure 1: High-level KMS architecture with its main components for External Key Store (XKS) support.

Figure 1 shows the high-level architecture for external key store support in AWS KMS. The XKS Proxy abstracts away API differences across multiple types of external key managers and provides a uniform HTTPS-based API for invoking cryptographic operations involving external keys. This standardized interface is indicated by the thick, vertical, dashed lines in Figure 1. Everything to the right of the interface is the customer’s responsibility, everything to the left and inside the AWS boundary is the responsibility of AWS.

Each type of key manager will require a corresponding XKS Proxy but a single XKS Proxy instance can serve a cluster of key managers.

We support two connectivity options for the communication between KMS and the XKS Proxy:

  1. XKS Proxy as a VPC Endpoint Service in the Customer’s Amazon VPC: With this option, customers can run the XKS Proxy on a private network (i.e. one using RFC 1918 private addresses). The proxy may be located in the customer’s data center (as shown for Customer A) or in an Amazon VPC (as shown for Customer B). In each case, customers will need to create an NLB and a VPC endpoint service in their Amazon VPC. The target group associated with the NLB will use private IP addresses associated with the XKS proxy. Customers will also need to connect their Amazon VPC to their on-premises data center using any of the available mechanisms such as a VPN or Direct Connect.
  2. XKS Proxy as a public endpoint: Customers can choose to make the proxy available as a publicly routable endpoint (as shown for Customer C) in their data center. This is the simpler connectivity option but it will experience greater variance in network performance since all traffic is going over the Internet. Request authentication restricts access to the proxy. Customers might choose this option when they are evaluating the external key store feature and switch to the VPC endpoint service connectivity option for production use.

The following is a brief description of the main entities/components referenced in Figure 1: