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 (PDF).

External key stores

External key stores allow you to protect your Amazon resources using cryptographic keys outside of Amazon. This advanced feature is designed for regulated workloads that you must protect with encryption keys stored in an external key management system that you control. External key stores support the Amazon digital sovereignty pledge to give you sovereign control over your data in Amazon, including the ability to encrypt with key material that you own and control outside of Amazon.

An external key store is a custom key store backed by an external key manager that you own and manage outside of Amazon. Your external key manager can be a physical or virtual hardware security modules (HSMs), or any hardware-based or software-based system capable of generating and using cryptographic keys. Encryption and decryption operations that use a KMS key in an external key store are performed by your external key manager using your cryptographic key material, a feature known as hold your own keys (HYOKs).

Amazon KMS never interacts directly with your external key manager, and cannot create, view, manage, or delete your keys. Instead, Amazon KMS interacts only with external key store proxy (XKS proxy) software that you provide. Your external key store proxy mediates all communication between Amazon KMS and your external key manager. It transmits all requests from Amazon KMS to your external key manager, and transmits responses from your external key manager back to Amazon KMS. The external key store proxy also translates generic requests from Amazon KMS into a vendor-specific format that your external key manager can understand, allowing you to use external key stores with key managers from a variety of vendors.

You can use KMS keys in an external key store for client-side encryption, including with the Amazon Encryption SDK. But external key stores are an important resource for server-side encryption, allowing you to protect your Amazon resources in multiple Amazon Web Services services with your cryptographic keys outside of Amazon. Amazon Web Services services that support customer managed keys for symmetric encryption also support KMS keys in an external key store. For service support details, see Amazon Service Integration.

External key stores allow you to use Amazon KMS for regulated workloads where encryption keys must be stored and used outside of Amazon. But they are a major departure from the standard shared responsibility model, and require additional operational burdens. The greater risk to availability and latency will, for most customers, exceed the perceived security benefits of external key stores.

External key stores let you control the root of trust. Data encrypted under KMS keys in your external key store can be decrypted only by using the external key manager that you control. If you temporarily revoke access to your external key manager, such as by disconnecting the external key store or disconnecting your external key manager from the external key store proxy, Amazon loses all access to your cryptographic keys until you restore it. During that interval, ciphertext encrypted under your KMS keys can't be decrypted. If you permanently revoke access to your external key manager, all ciphertext encrypted under a KMS key in your external key store becomes unrecoverable. The only exceptions are Amazon services that briefly cache the data keys protected by your KMS keys. These data keys continue to work until you deactivate the resource or the cache expires. For details, see How unusable KMS keys affect data keys.

External key stores unblock the few use cases for regulated workloads where encryption keys must remain solely under your control and inaccessible to Amazon. But this is a major change in the way you operate cloud-based infrastructure and a significant shift in the shared responsibility model. For most workloads, the additional operational burden and greater risks to availability and performance will exceed the perceived security benefits of external key stores.

Do I need an external key store?

For most users, the default Amazon KMS key store, which is protected by FIPS 140-3 Security Level 3 validated hardware security modules, fulfills their security, control, and regulatory requirements. External key store users incur substantial cost, maintenance, and troubleshooting burden, and risks to latency, availability and reliability.

When considering an external key store, take some time to understand the alternatives, including an Amazon CloudHSM key store backed by an Amazon CloudHSM cluster that you own and manage, and KMS keys with imported key material that you generate in your own HSMs and can delete from KMS keys on demand. In particular, importing key material with a very brief expiration interval might provide a similar level of control without the performance or availability risks.

An external key store might be the right solution for your organization if you have the following requirements:

If you choose an external key store, limit its use to workloads that require protection with cryptographic keys outside of Amazon.

Shared responsibility model

Standard KMS keys use key material that is generated and used in HSMs that Amazon KMS owns and manages. You establish the access control policies on your KMS keys and configure Amazon Web Services services that use KMS keys to protect your resources. Amazon KMS assumes responsibility for the security, availability, latency, and durability of the key material in your KMS keys.

KMS keys in external key stores rely on key material and operations in your external key manager. As such, the balance of responsibility shifts in your direction. You are responsible for the security, reliability, durability, and performance of the cryptographic keys in your external key manager. Amazon KMS is responsible for responding promptly to requests and communicating with your external key store proxy, and for maintaining our security standards. To ensure that every external key store ciphertext at least as strong than standard Amazon KMS ciphertext, Amazon KMS first encrypts all plaintext with Amazon KMS key material specific to your KMS key, and then sends it to your external key manager for encryption with your external key, a procedure known as double encryption. As a result, neither Amazon KMS nor the owner of the external key material can decrypt double-encrypted ciphertext alone.

You are responsible for maintaining an external key manager that meet your regulatory and performance standards, for supplying and maintaining an external key store proxy that conforms to the Amazon KMS External Key Store Proxy API Specification, and for ensuring the availability and durability of your key material. You must also create, configure, and maintain an external key store. When errors arise that are caused by components that you maintain, you must be prepared to identify and resolve the errors so that Amazon services can access your resources without undue disruption. Amazon KMS provides troubleshooting guidance to help you determine the cause of problems and the most likely resolutions.

Review the Amazon CloudWatch metrics and dimensions that Amazon KMS records for external key stores. Amazon KMS strongly recommends that you create CloudWatch alarms to monitor your external key store so you can detect the early signs of performance and operational problems before they occur.

What is changing?

External key stores support only symmetric encryption KMS keys. Within Amazon KMS, you use and manage KMS keys in an external key store in much the same way that you manage other customer managed keys, including setting access control policies and monitoring key use. You use the same APIs with the same parameters to request a cryptographic operation with a KMS key in an external key store that you use for any KMS key. Pricing is also the same as for standard KMS keys. For details, see KMS keys in external key stores and Amazon Key Management Service Pricing.

However, with external key stores the following principles change:

Where do I start?

To create and manage an external key store, you need to choose your external key store proxy connectivity option, assemble the prerequisites, and create and configure your external key store.

Quotas

Amazon KMS allows up to 10 custom key stores in each Amazon Web Services account and Region, including both Amazon CloudHSM key stores and external key stores, regardless of their connection state. In addition, there are Amazon KMS request quotas on the use of KMS keys in an external key store.

If you choose VPC proxy connectivity for your external key store proxy, there might also be quotas on the required components, such as VPCs, subnets, and network load balancers. For information about these quotas, use the Service Quotas console.

Regions

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

External key stores are supported in all Amazon Web Services Regions in which Amazon KMS is supported except for China (Beijing) and China (Ningxia).

Unsupported features

Amazon KMS does not support the following features in custom key stores.

Learn more:

External key store concepts

Learn the basic terms and concepts used in external key stores.

External key store

An external key store is an Amazon KMS custom key store backed by an external key manager outside of Amazon that you own and manage. Each KMS key in an external key store is associated with an external key in your external key manager. When you use a KMS key in an external key store for encryption or decryption, the operation is performed in your external key manager using your external key, an arrangement known as Hold your Own Keys (HYOK). This feature is designed for organizations that are required to maintain their cryptographic keys in their own external key manager.

External key stores ensure that the cryptographic keys and operations that protect your Amazon resources remain in your external key manager under your control. Amazon KMS sends requests to your external key manager to encrypt and decrypt data, but Amazon KMS cannot create, delete, or manage any external keys. All requests from Amazon KMS to your external key manager are mediated by an external key store proxy software component that you supply, own, and manage.

Amazon services that support Amazon KMS customer managed keys can use the KMS keys in your external key store to protect your data. As a result, your data is ultimately protected by your keys using your encryption operations in your external key manager.

The KMS keys in an external key store have fundamentally different trust models, shared responsibility arrangements, and performance expectations than standard KMS keys. With external key stores, you are responsible for the security and integrity of the key material and the cryptographic operations. The availability and latency of KMS keys in an external key store are affected by the hardware, software, networking components, and the distance between Amazon KMS and your external key manager. You are also likely to incur additional costs for your external key manager and for the networking and load balancing infrastructure you need for your external key manager to communicate with Amazon KMS

You can use your external key store as part of your broader data protection strategy. For each Amazon resource that you protect, you can decide which require a KMS key in an external key store and which can be protected by a standard KMS key. This gives you the flexibility to chose KMS keys for specific data classifications, applications, or projects.

External key manager

An external key manager is a component outside of Amazon that can generate 256-bit AES symmetric keys and perform symmetric encryption and decryption. The external key manager for an external key store can be a physical hardware security module (HSM), a virtual HSM, or a software key manager with or without an HSM component. It can be located anywhere outside of Amazon, including on your premises, in a local or remote data center, or in any cloud. Your external key store can be backed by a single external key manager or multiple related key manager instances that share cryptographic keys, such as an HSM cluster. External key stores are designed to support a variety of external managers from different vendors. For details about connecting to your external key manager, see Choose an external key store proxy connectivity option.

External key

Each KMS key in an external key store is associated with a cryptographic key in your external key manager known as an external key. When you encrypt or decrypt with a KMS key in your external key store, the cryptographic operation is performed in your external key manager using your external key.

For external key stores, an external key must be a 256-bit AES key that is enabled and can perform encryption and decryption. For detailed external key requirements, see Requirements for a KMS key in an external key store.

Amazon KMS cannot create, delete, or manage any external keys. Your cryptographic key material never leaves your external key manager.When you create a KMS key in an external key store, you provide the ID of an external key (XksKeyId). You cannot change the external key ID associated with a KMS key, although your external key manager can rotate the key material associated with the external key ID.

In addition to your external key, a KMS key in an external key store also has Amazon KMS key material. Data protected by the KMS key is encrypted first by Amazon KMS using the Amazon KMS key material, and then by your external key manager using your external key. This double encryption process ensures that ciphertext protected by your KMS key is always at least as strong as ciphertext protected only by Amazon KMS.

Many cryptographic keys have different types of identifiers. When creating a KMS key in an external key store, provide the ID of the external key that the external key store proxy uses to refer to the external key. If you use the wrong identifier, your attempt to create a KMS key in your external key store fails.

External key store proxy

The external key store proxy ("XKS proxy") is a customer-owned and customer-managed software application that mediates all communication between Amazon KMS and your external key manager. It also translates generic Amazon KMS requests into a format that your vendor-specific external key manager understand. An external key store proxy is required for an external key store. Each external key store is associated with one external key store proxy.

Amazon KMS cannot create, delete, or manage any external keys. Your cryptographic key material never leaves your external key manager. All communication between Amazon KMS and your external key manager is mediated by your external key store proxy. Amazon KMS sends requests to the external key store proxy and receives responses from the external key store proxy. The external key store proxy is responsible for transmitting requests from Amazon KMS to your external key manager and transmitting responses from your external key manager back to Amazon KMS

You own and manage the external key store proxy for your external key store, and you are responsible for its maintenance and operation. You can develop your external key store proxy based on the open-source external key store proxy API specification that Amazon KMS publishes or purchase a proxy application from a vendor. Your external key store proxy might be included in your external key manager. To support proxy development, Amazon KMS also provides a sample external key store proxy (aws-kms-xks-proxy) and a test client (xks-kms-xksproxy-test-client) that verifies that your external key store proxy conforms to the specification.

To authenticate to Amazon KMS, the proxy uses server-side TLS certificates. To authenticate to your proxy, Amazon KMS signs all requests to your external key store proxy with a SigV4 proxy authentication credential. Optionally, your proxy can enable mutual TLS (mTLS) for additional assurance that it only accepts requests from Amazon KMS.

Your external key store proxy must support HTTP/1.1 or later and TLS 1.2 or later with at least one of the following cipher suites:

To create and use the KMS keys in your external key store, you must first connect the external key store to its external key store proxy. You can also disconnect your external key store from its proxy on demand. When you do, all KMS keys in the external key store become unavailable; they cannot be used in any cryptographic operation.

External key store proxy connectivity

The external key store proxy connectivity ("XKS proxy connectivity") describes the method that Amazon KMS uses to communicate with your external key store proxy.

You specify your proxy connectivity option when you create your external key store, and it becomes a property of the external key store. You can change your proxy connectivity option by updating the custom key store property, but you must be certain that your external key store proxy can still access the same external keys.

Amazon KMS supports the following connectivity options:

For details about the external key store proxy connectivity options, see Choose an external key store proxy connectivity option.

External key store proxy authentication credential

To authenticate to your external key store proxy, Amazon KMS signs all requests to your external key store proxy with a Signature V4 (SigV4) authentication credential. You establish and maintain the authentication credential on your proxy, then provide this credential to Amazon KMS when you create your external store.

Each proxy authentication credential has two parts. You must provide both parts when creating an external key store or updating the authentication credential for your external key store.

You can edit the credential setting at any time, such as when you enter incorrect values, when you change your credential on the proxy, or when your proxy rotates the credential. For technical details about Amazon KMS authentication to the external key store proxy, see Authentication in the Amazon KMS External Key Store Proxy API Specification.

To allow you to rotate your credential without disrupting the Amazon Web Services services that use KMS keys in your external key store, we recommend that the external key store proxy support at least two valid authentication credentials for Amazon KMS. This ensures that your previous credential continues to work while you provide your new credential to Amazon KMS.

To help you track the age of your proxy authentication credential, Amazon KMS defines an Amazon CloudWatch metric, XksProxyCredentialAge. You can use this metric to create a CloudWatch alarm that notifies you when the age of your credential reaches a threshold you establish.

To provide additional assurance that your external key store proxy responds only to Amazon KMS, some external key proxies support mutual Transport Layer Security (mTLS). For details, see mTLS authentication (optional).

Proxy APIs

To support an Amazon KMS external key store, an external key store proxy must implement the required proxy APIs as described in the Amazon KMS External Key Store Proxy API Specification. These proxy API requests are the only requests that Amazon KMS sends to the proxy. Although you never send these requests directly, knowing about them might help you fix any issues that might arise with your external key store or its proxy. For example, Amazon KMS includes information about the latency and success rates of these API calls in its Amazon CloudWatch metrics for external key stores. For details, see Monitor external key stores.

The following table lists and describes each of the proxy APIs. It also includes the Amazon KMS operations that trigger a call to the proxy API and any Amazon KMS operation exceptions related to the proxy API.

Double encryption

Data encrypted by a KMS key in an external key store is encrypted twice. First, Amazon KMS encrypts the data with Amazon KMS key material specific to the KMS key. Then the Amazon KMS-encrypted ciphertext is encrypted by your external key manager using your external key. This process is known as double encryption.

Double encryption ensures that data encrypted by a KMS key in an external key store is at least as strong as ciphertext encrypted by a standard KMS key. It also protects your plaintext in transit from Amazon KMS to your external key store proxy. With double encryption, you retain full control of your ciphertexts. If you permanently revoke Amazon access to your external key through your external proxy, any ciphertext remaining in Amazon is effectively crypto-shredded.

To enable double encryption, each KMS key in an external key store has two cryptographic backing keys:

Double encryption has the following effects:

For an example of double encryption in practice, see How external key stores work.

How external key stores work

Your external key store, external key store proxy, and external key manager work together to protect your Amazon resources. The following procedure depicts the encryption workflow of a typical Amazon Web Services service that encrypts each object under a unique data key protected by a KMS key. In this case, you've chosen a KMS key in an external key store to protect the object. The example shows how Amazon KMS uses double encryption to protect the data key in transit and ensure that ciphertext generated by a KMS key in an external key store is always at least as strong as ciphertext encrypted by a standard symmetric KMS key with key material in Amazon KMS.

The encryption methods used by each actual Amazon Web Services service that integrates with Amazon KMS vary. For details, see the "Data protection" topic in the Security chapter of the Amazon Web Services service documentation.

To decrypt the encrypted object, the Amazon Web Services service must send the encrypted data key back to Amazon KMS in a Decrypt request. To decrypt the encrypted data key, Amazon KMS must send the encrypted data key back to your external key store proxy with the ID of the external key. If the decrypt request to the external key store proxy fails for any reason, Amazon KMS cannot decrypt the encrypted data key, and the Amazon Web Services service cannot decrypt the encrypted object.