External key stores - 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.

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 sovereignity 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 with your cryptographic keys outside of Amazon. Most Amazon Web Services that support customer managed keys for symmetric encryption also support KMS keys in an external key store. For a list of Amazon Web Services that do not support KMS keys in an external key store, 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.

Learn more:

Do I need an external key store?

For most users, the default Amazon KMS key store, which is protected by FIPS 140-2 validated cryptographic 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:

  • You are required to use cryptographic keys in your on-premises key manager or a key manager outside of Amazon that you control.

  • You must demonstrate that your cryptographic keys are retained solely under your control outside of the cloud.

  • You must encrypt and decrypt using cryptographic keys with independent authorization.

  • Key material must be subject to a secondary, independent audit path.

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 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 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 Managing KMS keys in an external key store, Using KMS keys in an external key store, and Amazon Key Management Service Pricing.

However, with external key stores the following principles change:

  • You are responsible for the availability, durability, and latency of key operations.

  • You are responsible for all costs for developing, purchasing, operating, and licensing your external key manager system.

  • You can implement independent authorization of all requests from Amazon KMS to your external key store proxy.

  • You can monitor, audit, and log all operations of your external key store proxy, and all operations of your external key manager related to Amazon KMS requests.

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. To begin, see Planning an 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 Asia Pacific (Hyderabad), Asia Pacific (Melbourne), China (Beijing), China (Ningxia), Europe (Spain), Europe (Zurich), Middle East (UAE), Amazon GovCloud (US-East), and Amazon GovCloud (US-West).

Unsupported features

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

External key store concepts

This topic explains some of the 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 the requirements for your external key manager, see Planning an external key store.

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.

Warning

The external key is essential to the operation of the KMS key. If the external key is lost or deleted, ciphertext encrypted under the associated KMS key is unrecoverable.

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.


                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.

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:

  • Public endpoint connectivity — Amazon KMS sends requests for your external key store proxy over the internet to a public endpoint that you control. This option is simple to create and maintain, but it might not fulfill the security requirements for every installation.

  • VPC endpoint service connectivity — Amazon KMS sends requests to a Amazon Virtual Private Cloud (Amazon VPC) endpoint service that you create and maintain. You can host your external key store proxy inside your Amazon VPC, or host your external key store proxy outside of Amazon and use the Amazon VPC only for communication.

For details about the external key store proxy connectivity options, see Choosing a 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.

Note

The SigV4 credential that Amazon KMS uses to sign requests to the XKS proxy is unrelated to any SigV4 credentials associated with Amazon Identity and Access Management principals in your Amazon Web Services accounts. Do not reuse any IAM SigV4 credentials for your external key store proxy.

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.

  • Access key ID: Identifies the secret access key. You can provide this ID in plaintext.

  • Secret access key: The secret part of the credential. Amazon KMS encrypts the secret access key in the credential before storing it.

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 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 Monitoring an external key store.

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.

Proxy API Description Related Amazon KMS operations
Decrypt Amazon KMS sends the ciphertext to be decrypted, and the ID of the external key to use. The required encryption algorithm is AES_GCM. Decrypt, ReEncrypt
Encrypt Amazon KMS sends data to be encrypted, and the ID of the external key to use. The required encryption algorithm is AES_GCM. Encrypt, GenerateDataKey, GenerateDataKeyWithoutPlaintext, ReEncrypt
GetHealthStatus Amazon KMS requests information about the status of the proxy and your external key manager.

The status of each external key manager can be one of the following.

  • Active: Healthy; can serve traffic

  • Degraded: Unhealthy, but can serve traffic

  • Unavailable: Unhealthy; cannot serve traffic

CreateCustomKeyStore (for public endpoint connectivity), ConnectCustomKeyStore (for VPC endpoint service connectivity)

If all external key manager instances are Unavailable, attempts to create or connect the key store fail with XksProxyUriUnreachableException.

GetKeyMetadata Amazon KMS requests information about the external key associated with a KMS key in your external key store.

The response includes the key spec (AES_256), the key usage ([ENCRYPT, DECRYPT]), and the whether the external key is ENABLED or DISABLED.

CreateKey

If the key spec is not AES_256, or the key usage is not [ENCRYPT, DECRYPT], or the status is DISABLED, the CreateKey operation fails with XksKeyInvalidConfigurationException.

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.


                Double encryption of data protected by a KMS key in an external key
                    store

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

  • An Amazon KMS key material unique to the KMS key. This key material is generated and used in Amazon KMS FIPS 140-2 level-2 certified hardware security managers (HSMs).

  • An external key in your external key manager.

Double encryption has the following effects:

  • Amazon KMS cannot decrypt any ciphertext encrypted by a KMS key in an external key store without access to your external keys via your external key store proxy.

  • You cannot decrypt any ciphertext encrypted by a KMS key in an external key store outside of Amazon, even if you have its external key material.

  • You cannot recreate a KMS key that was deleted from an external key store, even if you have its external key material. Each KMS key has unique metadata that it includes in the symmetric ciphertext. A new KMS key would not be able to decrypt ciphertext encrypted by the original key, even if it used the same external key material.

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 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 Service that integrates with Amazon KMS vary. For details, see the "Data protection" topic in the Security chapter of the Amazon Web Service documentation.


            How external key stores work
  1. You add a new object to your Amazon Web Service resource. To encrypt the object, the Amazon Web Service sends a GenerateDataKey request to Amazon KMS using a KMS key in your external key store.

  2. Amazon KMS generates a 256-bit symmetric data key and prepares to send a copy of the plaintext data key to your external key manager via your external key store proxy. Amazon KMS begins the double encryption process by encrypting the plaintext data key with the Amazon KMS key material associated with the KMS key in the external key store.

  3. Amazon KMS sends an encrypt request to the external key store proxy associated with the external key store. The request includes the data key ciphertext to be encrypted and the ID of the external key that is associated with the KMS key. Amazon KMS signs the request using the proxy authentication credential for your external key store proxy.

    The plaintext copy of the data key is not sent to the external key store proxy.

  4. The external key store proxy authenticates the request, and then passes the encrypt request to your external key manager.

    Some external key store proxies also implement an optional authorization policy that allows only selected principals to perform operations under specific conditions.

  5. Your external key manager encrypts the data key ciphertext using the specified external key. The external key manager returns the double-encrypted data key to your external key store proxy, which returns it to Amazon KMS.

  6. Amazon KMS returns the plaintext data key and the double-encrypted copy of that data key to the Amazon Web Service.

  7. The Amazon Web Service uses the plaintext data key to encrypt the resource object, destroys the plaintext data key, and stores the encrypted data key with the encrypted object.

    Some Amazon Web Services might cache the plaintext data key to use for multiple objects, or to reuse while the resource is in use. For details, see How unusable KMS keys affect data keys.

To decrypt the encrypted object, the Amazon Web 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 Service cannot decrypt the encrypted object.