本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 外部密钥存储
外部密钥存储允许您使用外部的加密密钥来保护您的 AWS 资源。 AWS此高级功能专为受监管的工作负载设计，这些工作负载必须使用存储在您控制的外部密钥管理系统中的加密密钥加以保护。外部密钥存储支持[AWS 数字主权承诺](https://aws.amazon.com/blogs/security/aws-digital-sovereignty-pledge-control-without-compromise/)，为您提供对数据的主权控制权 AWS，包括能够使用您拥有并在外部控制的密钥材料进行加密 AWS。
*外部密钥存储库*是由您拥有并在外部管理的*外部密钥管理器*支持的[自定义密钥存储](key-store-overview.md#custom-key-store-overview)库 AWS。您的外部密钥管理器可以是物理或虚拟硬件安全模块 (HSMs)，也可以是任何能够生成和使用加密密钥的基于硬件或软件的系统。使用外部密钥存储库中的 KMS 密钥的加密和解密操作由您的外部密钥管理器使用您的加密密钥材料执行，该功能被称为 “*保留自己的密钥*” ()。HYOKs
AWS KMS 切勿直接与外部密钥管理器交互，也无法创建、查看、管理或删除您的密钥。相反，仅与您提供的[外部密钥存储代理](#concept-xks-proxy)（XKS 代理）软件进行 AWS KMS 交互。您的外部密钥存储代理负责调解与您的外部密钥管理器 AWS KMS 之间的所有通信。它会将来自 AWS KMS 您的外部密钥管理器的所有请求传送回您的外部密钥管理器，并将来自外部密钥管理器的响应传回到。 AWS KMS外部密钥存储代理还将来自 AWS KMS 的通用请求转换为外部密钥管理器可以理解的供应商特定格式，允许您将外部密钥存储与来自不同供应商的密钥管理器一起使用。
您可以在外部密钥存储中使用 KMS 密钥进行客户端加密，包括使用 [AWS Encryption SDK](https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/)。但是外部密钥存储是服务器端加密的重要资源，它允许您使用外部的加密密钥对 AWS 资源 AWS 服务 进行多重保护。 AWS AWS 服务 支持用于对称加密的[客户托管密钥](concepts.md#customer-mgn-key)还支持外部密钥存储中的 KMS 密钥。有关服务支持的详细信息，请参阅 [AWS 服务集成](https://aws.amazon.com/kms/features/#AWS_service_integration)。
外部密钥存储允许您 AWS KMS 用于受监管的工作负载，在这些工作负载中，加密密钥必须在外部存储和使用 AWS。不过，这样的工作负载与标准责任共担模型相去甚远，会造成额外的运营负担。对大多数客户而言，可用性和延迟的更大风险将超过外部密钥存储的预期安全优势。
外部密钥存储允许您控制信任根密钥。在外部密钥存储中以 KMS 密钥加密的数据，只能使用您控制的外部密钥管理器进行解密。如果您暂时撤消对外部密钥管理器的访问权限，例如断开外部密钥存储库的连接或断开外部密钥管理器与外部密钥存储代理的连接，则在恢复加密密钥之前，将 AWS 失去对加密密钥的所有访问权限。在此期间，无法解密以 KMS 密钥加密的加密文字。如果您永久撤消对外部密钥管理器的访问权限，在外部密钥存储中以 KMS 密钥加密的所有加密文字都不可恢复。唯一的例外是那些会短暂缓存受您的 KMS [密钥保护的数据](data-keys.md)密钥的 AWS 服务。这些数据密钥将继续有效，直到您停用资源或缓存过期。有关更多信息，请参阅 [不可用的 KMS 密钥如何影响数据密钥](unusable-kms-keys.md)。
外部密钥存储可以解锁受监管工作负载的少数用例，在这些用例中，加密密钥必须完全由您控制且无法访问 AWS。不过，这是您运营基于云的基础设施方式的重大变化，也是责任共担模型的重大转变。对大多数工作负载而言，额外的运营负担以及可用性和性能的更大风险将超过外部密钥存储所带来的预期安全优势。
**我需要外部密钥存储吗？**
对于大多数用户来说，默认 AWS KMS 密钥存储区受到 [FIPS 140-3 安全等级 3 验证的硬件安全模块](https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/4884)的保护，可以满足他们的安全、控制和监管要求。外部密钥存储用户会承担大量成本、维护和故障排除负担，以及与延迟、可用性和可靠性有关的风险。
在考虑外部密钥存储时，请花点时间了解替代方案，包括由您拥有和管理的 AWS CloudHSM 集群支持的密[AWS CloudHSM 钥存储库](keystore-cloudhsm.md)，以及包含您自己生成 HSMs 并可以按需从 KMS 密钥中删除的[导入密钥材料](importing-keys.md)的 KMS 密钥。特别要注意的是，导入过期间隔非常短的密钥材料可以提供类似级别的控制，却不会带来性能或可用性风险。
如果您有以下要求，则外部密钥存储可能是适合您组织的解决方案：
+ 您需要在本地密钥管理器中使用加密密钥，或者在您控制范围之外的密钥管理器中使用加密密钥。 AWS
+ 您必须证明，在云端之外，您加密密钥的保留完全由自己控制。
+ 您必须使用具有独立授权的加密密钥进行加密和解密。
+ 密钥材料必须受辅助、独立的审计路径的约束。
如果您选择外部密钥存储，请将其使用限制在需要使用 AWS之外的加密密钥进行保护的工作负载。
**责任共担模式**
标准 KMS 密钥使用在中生成和使用的密钥材料 HSMs ，由其 AWS KMS 拥有和管理。您可以在 KMS 密钥上建立访问控制策略，并配置 AWS 服务 该策略使用 KMS 密钥来保护您的资源。 AWS KMS 负责您的 KMS 密钥中密钥材料的安全性、可用性、延迟和耐久性。
外部密钥存储中的 KMS 密钥依赖外部密钥管理器中的密钥材料和操作。因此，责任的天平朝着您的方向移动。您对外部密钥管理器中加密密钥的安全性、可靠性、耐用性和性能负责。 AWS KMS 负责迅速响应请求并与您的外部密钥存储代理进行通信，并负责维护我们的安全标准。[*为确保每个外部密钥存储的密文至少与标准密文一样强，请 AWS KMS 先使用您的 KMS AWS KMS 密钥特有的 AWS KMS 密钥材料对所有明文进行加密，然后将其发送到您的外部密钥管理器以使用您的外部密钥进行加密，这种过程称为双重加密。*](#concept-double-encryption)因此，无论是 AWS KMS 还是外部密钥材料的所有者，都无法单独解密双重加密的加密文字。
您要对以下事项负责：维护符合您监管和性能标准的外部密钥管理器，提供和维护符合 [AWS KMS 外部密钥存储代理 API 规范](https://github.com/aws/aws-kms-xksproxy-api-spec/)的外部密钥存储代理，以及确保密钥材料的可用性和持久性。您还必须创建、配置和维护外部密钥存储。当出现由您维护的组件引起的错误时，您必须做好识别和解决错误的准备，以便 AWS 服务能够在不造成不当干扰的情况下访问您的资源。 AWS KMS 提供[故障排除指导](xks-troubleshooting.md)，帮助您确定问题的原因和最可能的解决方案。
查看 AWS KMS 记录外部密钥存储的 [Amazon CloudWatch 指标和维度](monitoring-cloudwatch.md#kms-metrics)。 AWS KMS 强烈建议您创建 CloudWatch 警报来监控您的外部密钥存储，这样您就可以在性能和操作问题出现之前检测到这些问题的早期迹象。
**发生了什么变化？**
外部密钥存储仅支持对称加密 KMS 密钥。在内部 AWS KMS，您使用和管理外部密钥存储库中的 KMS 密钥的方式与管理其他[客户托管密钥](concepts.md#customer-mgn-key)的方式大致相同，包括[设置访问控制策略](authorize-xks-key-store.md)和[监控密钥使用](monitoring-overview.md)情况。对于用于任何 KMS 密钥的外部密钥存储库中的 KMS 密钥，您可以使用相同的参数来请求加密操作。 APIs 定价也与标准 KMS 密钥相同。有关详细信息，请参阅 [外部密钥存储中的 KMS 密钥](keystore-external-key-manage.md) 和 [AWS Key Management Service 定价](https://aws.amazon.com/kms/pricing/)。
不过，使用外部密钥存储时，以下原则会发生变化：
+ 您对密钥操作的可用性、持久性和延迟负责。
+ 您对外部密钥管理器系统的开发、购买、运营和许可的所有费用负责。
+ 您可以对来自 AWS KMS 外部密钥存储代理的所有请求实施[独立授权](authorize-xks-key-store.md#xks-proxy-authorization)。
+ 您可以监控、审核和记录外部密钥存储代理的所有操作以及外部密钥管理器中与 AWS KMS 请求相关的所有操作。
**从何处开始？**
要创建和管理外部密钥存储，您需要[选择外部密钥存储代理连接选项](choose-xks-connectivity.md)、[汇编先决条件](create-xks-keystore.md#xks-requirements)，然后[创建和配置外部密钥存储](create-xks-keystore.md)。
**配额**
AWS KMS 允许每个 AWS 账户 和区域中最多有 [10 个自定义密钥存储库](resource-limits.md)，包括[AWS CloudHSM 密钥存储库](https://docs.aws.amazon.com/kms/latest/developerguide/keystore-cloudhsm.html)和[外部密钥存储库](https://docs.aws.amazon.com/kms/latest/developerguide/keystore-external.html)，无论其连接状态如何。此外，[使用外部密钥存储中 KMS 密钥](requests-per-second.md#rps-key-stores) 存在 AWS KMS 请求限额。
如果您为外部密钥存储[代理选择 VPC 代理连接](#concept-xks-connectivity)，则所需组件（例如 VPCs子网和网络负载均衡器）也可能有配额。有关这些限额的信息，请使用[服务限额控制台](https://console.aws.amazon.com/servicequotas/home)。
**区域**
为了最大限度地减少网络延迟，请在离[外部密钥管理器](#concept-ekm)最近的 AWS 区域 中创建外部密钥存储组件。如果可行，请选择网络往返时间（RTT）不超过 35 毫秒的区域。
除中国（北京）和中国（宁夏）外， AWS KMS 所有支持外部密钥存储的 AWS 区域 地区均支持外部密钥存储。
**不支持的功能**
AWS KMS 不支持自定义密钥存储库中的以下功能。
+ [非对称 KMS 密钥](symmetric-asymmetric.md)
+ [HMAC KMS 密钥](hmac.md)
+ [具有导入密钥材料的 KMS 密钥](importing-keys.md)
+ [自动密钥轮换](rotate-keys.md)
+ [多区域密钥](multi-region-keys-overview.md)
**了解更多：**
+ *AWS 新闻博客*中的[宣布推出 AWS KMS 外部密钥存储](https://aws.amazon.com/blogs/aws/announcing-aws-kms-external-key-store-xks/)。
## 外部密钥存储概念
了解外部密钥存储中使用的基本术语和概念。
### 外部密钥存储
*外部密钥存储库*是由您拥有和管理的外部密钥管理器支持的 AWS KMS [自定义密钥存储](key-store-overview.md#custom-key-store-overview)库。 AWS 外部密钥存储中的每个 KMS 密钥都与您外部密钥管理器中的[外部密钥](#concept-external-key)相关联。在外部密钥存储中使用 KMS 密钥进行加密或解密时，该操作将在您的外部密钥管理器中使用您的外部密钥执行，这种安排称为*持有自己的密钥*（HYOK）。此功能专为需要在自己的外部密钥管理器中维护加密密钥的组织设计。
外部密钥存储可确保保护您的 AWS 资源的加密密钥和操作保留在您的外部密钥管理器中，由您控制。 AWS KMS 向您的外部密钥管理器发送请求以加密和解密数据，但 AWS KMS 无法创建、删除或管理任何外部密钥。来自 AWS KMS 外部密钥管理器的所有请求均由您提供、拥有和管理的[外部密钥存储代理](#concept-xks-proxy)软件组件进行中介。
AWS 支持 AWS KMS [客户托管密钥](concepts.md)的服务可以使用外部密钥存储区中的 KMS 密钥来保护您的数据。因此，您的数据最终由使用您外部密钥管理器中的加密操作的密钥进行保护。
与标准 KMS 密钥相比，外部密钥存储中的 KMS 密钥具有根本上不同的信任模型、[责任共担安排](#xks-shared-responsibility)和性能预期。使用外部密钥存储时，您要对密钥材料和加密操作的安全性和完整性负责。外部密钥存储中 KMS 密钥的可用性和延迟情况，受硬件、软件、网络组件以及 AWS KMS 与外部密钥管理器之间的距离的影响。您还可能会为外部密钥管理器以及外部密钥管理器与之通信所需的网络和负载平衡基础设施支付额外费用 AWS KMS
您可以将外部密钥存储作为更广泛的数据保护策略的一部分加以使用。对于您保护的每项 AWS 资源，您可以决定哪些资源需要在外部密钥存储中使用 KMS 密钥，哪些可以由标准 KMS 密钥保护。这可以让您灵活地为特定的数据分类、应用程序或项目选择 KMS 密钥。
### 外部密钥管理器
*外部密钥管理器*是 AWS 之外的组件，可以生成 256 位 AES 对称密钥并执行对称加密和解密。外部密钥存储的外部密钥管理器，可以是实体硬件安全模块（HSM）、虚拟 HSM 或带/不带 HSM 组件的软件密钥管理器。它可以位于外部的任何地方 AWS，包括您的本地、本地或远程数据中心或任何云中。您的外部密钥存储可以由单个外部密钥管理器提供支持，也可以由共享加密密钥的多个相关密钥管理器实例（例如 HSM 集群）提供支持。外部密钥存储旨在支持来自不同供应商的各种外部管理器。有关连接外部密钥管理器的详细信息，请参阅 [选择外部密钥存储代理连接选项](choose-xks-connectivity.md)。
### 外部密钥
外部密钥存储中的每个 KMS 密钥都与[外部密钥管理器](#concept-ekm)中的加密密钥（称为*外部密钥*）相关联。在使用外部密钥存储中的 KMS 密钥加密或解密时，将使用外部密钥在[外部密钥管理器](#concept-ekm)中执行加密操作。
**警告**
外部密钥对 KMS 密钥的操作至关重要。如果外部密钥丢失或遭删除，则以相关 KMS 密钥加密的加密文字将无法恢复。
使用外部密钥存储时，外部密钥必须是已启用且可以执行加密和解密的 256 位 AES 密钥。有关详细的外部密钥要求，请参阅 [外部密钥存储中 KMS 密钥的要求](create-xks-keys.md#xks-key-requirements)。
AWS KMS 无法创建、删除或管理任何外部密钥。您的加密密钥材料永远不会离开外部密钥管理器。在外部密钥存储中创建 KMS 密钥时，您需要提供外部密钥的 ID（`XksKeyId`）。您无法更改与 KMS 密钥关联的外部密钥 ID，即便外部密钥管理器可以轮换与外部密钥 ID 关联的密钥材料。
除了外部密钥，外部密钥存储中的 KMS 密钥还具有 AWS KMS 密钥材料。受 KMS 密钥保护的数据首先 AWS KMS 使用密 AWS KMS 钥材料进行加密，然后由您的外部密钥管理器使用您的外部密钥进行加密。这种[双重加密](#concept-double-encryption)过程可确保受您 KMS 密钥保护的加密文字始终至少与仅受 AWS KMS保护的加密文字一样强大。
许多加密密钥具有不同类型的标识符。在外部密钥存储中创建 KMS 密钥时，您要提供[外部密钥存储代理](#concept-xks-proxy)用来引用外部密钥的外部密钥 ID。如果使用了错误的标识符，尝试在外部密钥存储中创建 KMS 密钥会失败。
### 外部密钥存储代理
*外部密钥存储代理*（“XKS 代理”）是客户拥有和客户管理的软件应用程序，用于调解与您的外部密钥管理器 AWS KMS 之间的所有通信。它还将通用 AWS KMS 请求转换为供应商特定的外部密钥管理器可以理解的格式。外部密钥存储需要外部密钥存储代理。每个外部密钥存储会关联一个外部密钥存储代理。
![\[外部密钥存储代理\]](http://docs.aws.amazon.com/zh_cn/kms/latest/developerguide/images/xks-proxy-concept-40.png)
AWS KMS 无法创建、删除或管理任何外部密钥。您的加密密钥材料永远不会离开外部密钥管理器。 AWS KMS 与您的外部密钥管理器之间的所有通信均由您的外部密钥存储代理进行中介。 AWS KMS 向外部密钥存储代理发送请求并接收来自外部密钥存储代理的响应。外部密钥存储代理负责将请求从您的外部密钥管理器传输 AWS KMS 到您的外部密钥管理器，并将来自外部密钥管理器的响应传回到 AWS KMS
您拥有并管理外部密钥存储的外部密钥存储代理，并负责其维护和操作。您可以根据开源外部密钥存储代理 API 规范开发[外部密钥存储代理 API 规范，该规范](https://github.com/aws/aws-kms-xksproxy-api-spec/) AWS KMS 发布或从供应商那里购买代理应用程序。您的外部密钥存储代理可能包含在您的外部密钥管理器中。为了支持代理开发， AWS KMS 还提供了外部密钥存储代理示例 ([aws-kms-xks-proxy](https://github.com/aws-samples/aws-kms-xks-proxy)) 和测试客户端 ([xks-kms-xksproxy-test-client](https://github.com/aws-samples/aws-kms-xksproxy-test-client))，用于验证您的外部密钥存储代理是否符合规范。
要进行身份验证 AWS KMS，代理使用服务器端 TLS 证书。要向您的代理进行身份验证， AWS KMS 请使用 Sigv4 代理[身份验证](#concept-xks-credential)凭据对外部密钥存储代理的所有请求进行签名。
您的外部密钥存储代理必须支持 HTTP/1.1 或更高版本以及 TLS 1.2 或更高版本，并至少使用以下密码套件之一：
+ TLS\$1AES\$1256\$1GCM SHA384 \$1 (TLS 1.3)
+ TLS\$1 \$1 CHACHA20 POLY1305 \$1 SHA256 (TLS 1.3)
**注意**
AWS GovCloud (US) Region 不支持 TLS\$1 CHACHA20 \$1 POLY1305。SHA256
+ TLS\$1ECDHE\$1RSA\$1WITH SHA384 \$1AES\$1256\$1GCM\$1 (TLS 1.2)
+ TLS\$1ECDHE\$1ECDSA\$1WITH SHA384 \$1AES\$1256\$1GCM\$1 (TLS 1.2)
要在外部密钥存储中创建和使用 KMS 密钥，必须先[将外部密钥存储连接到](xks-connect-disconnect.md)其外部密钥存储代理。您也可以根据需要断开外部密钥存储与其代理的连接。在这样做时，外部密钥存储中的所有 KMS 密钥都会变得[不可用](key-state.md)，也不能用于任何加密操作。
### 外部密钥存储代理连接
外部密钥存储代理连接（“XKS 代理连接”）描述了 AWS KMS 用于与外部密钥存储代理进行通信的方法。
您在创建外部密钥存储时指定代理连接选项，该选项将成为外部密钥存储的属性。您可以通过更新自定义密钥存储属性来更改代理连接选项，但必须确定外部密钥存储代理仍然可以访问相同的外部密钥。
AWS KMS 支持以下连接选项。
+ [公共终端节点连接](choose-xks-connectivity.md#xks-connectivity-public-endpoint)-通过 Internet 将外部密钥存储代理的请求 AWS KMS 发送到您控制的公共终端节点。此选项易于创建和维护，但可能无法满足每次安装的安全要求。
+ [VPC 终端节点服务连接](choose-xks-connectivity.md#xks-vpc-connectivity) — AWS KMS 向您创建和维护的亚马逊虚拟私有云（亚马逊 VPC）终端节点服务发送请求。您可以在 Amazon VPC 内托管外部密钥存储代理，也可以将外部密钥存储代理托管在 Amazon VPC 之外 AWS 并仅用于通信。此外还可以将外部密钥存储连接到由其他 AWS 账户拥有的 Amazon VPC 端点服务。
有关外部密钥存储代理连接选项的详细信息，请参阅 [选择外部密钥存储代理连接选项](choose-xks-connectivity.md)。
### 外部密钥存储代理身份验证凭证
要向外部密钥存储代理进行身份验证， AWS KMS 请使用[签名 V4 (Sigv4) 身份验证凭据对外部密钥存储代理的所有请求进行签名](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html)。您在代理上建立并维护身份验证凭据，然后在创建外部存储 AWS KMS 时提供此凭据。
**注意**
AWS KMS 用于签署 XKS 代理请求的 Sigv4 凭据与您的中的委托人关联的任何 Sigv4 凭据无关。 AWS Identity and Access Management AWS 账户不要将任何 IAM SigV4 凭证重复用于外部密钥存储代理。
每个代理身份验证凭证有两个部分。在创建外部密钥存储或更新外部密钥存储的身份验证凭证时，必须提供这两部分。
+ 访问密钥 ID：标识秘密访问密钥。您能以明文形式提供此 ID。
+ 秘密访问密钥：凭证的秘密部分。 AWS KMS 在存储凭据之前对凭据中的私有访问密钥进行加密。
您随时可以[编辑凭证设置](update-xks-keystore.md)，例如输入了错误值时、在代理上更改凭证时或者代理轮换证书时。有关对外部密钥存储代理 AWS KMS 进行身份验证的技术细节，请参阅《 AWS KMS 外部密钥存储代理 API 规范》中的[身份验证](https://github.com/aws/aws-kms-xksproxy-api-spec/blob/main/xks_proxy_api_spec.md#authentication)。
为了允许您在不中断外部密钥存储中使用 KMS 密钥的凭证的情况下轮换凭证，我们建议外部密钥存储代理至少支持两个有效的身份验证凭据。 AWS 服务 AWS KMS这样可以确保在您向 AWS KMS提供新凭证时，以前的凭证继续有效。
为了帮助您跟踪代理身份验证凭证的使用年限， AWS KMS 定义了 Amazon CloudWatch 指标。[XksProxyCredentialAge](monitoring-cloudwatch.md#metric-xks-proxy-credential-age)您可以使用此指标创建 CloudWatch 警报，当您的凭证期限达到您设定的阈值时，该警报会通知您。
### 代理 APIs
要支持 AWS KMS 外部密钥存储，[外部密钥存储代理](#concept-xks-proxy)必须实现所需的代理， APIs 如[AWS KMS 外部密钥存储代理 API 规范](https://github.com/aws/aws-kms-xksproxy-api-spec/)中所述。这些代理 API 请求是 AWS KMS 发送到代理的唯一请求。即便您从不直接发送这些请求，了解这些请求也可能有助于您修复外部密钥存储或其代理可能出现的任何问题。例如，在其外部密钥存储的 [Amazon CloudWatch 指标](monitoring-cloudwatch.md)中 AWS KMS 包含有关这些 API 调用的延迟和成功率的信息。有关更多信息，请参阅 [监控外部密钥存储](xks-monitoring.md)。
下表列出并描述了每个代理 APIs。它还包括触发对 AWS KMS 代理 API 的调用的 AWS KMS 操作以及与代理 API 相关的任何操作异常。
| 代理 API | 说明 | 相关 AWS KMS 操作 |
| --- | --- | --- |
| Decrypt | AWS KMS 发送要解密的密文以及要使用的[外部](#concept-external-key)密钥的 ID。所需的加密算法为 AES\$1GCM。 | [解密](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html)，[ReEncrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReEncrypt.html) |
| Encrypt | AWS KMS 发送要加密的数据以及要使用的[外部密钥](#concept-external-key)的 ID。所需的加密算法为 AES\$1GCM。 | [加密](https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html)、[GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html)、[GenerateDataKeyWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html)、[ReEncrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReEncrypt.html) |
| GetHealthStatus | AWS KMS 请求有关代理和您的外部密钥管理器状态的信息。每个外部密钥管理器的状态可以是以下状态之一。[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/kms/latest/developerguide/keystore-external.html) | [CreateCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateCustomKeyStore.html)（用于[公共终端节点连接](choose-xks-connectivity.md#xks-connectivity-public-endpoint)）、[ConnectCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_ConnectCustomKeyStore.html)（用于 [VPC 终端节点服务连接](choose-xks-connectivity.md#xks-vpc-connectivity)）如果所有外部密钥管理器实例都处于 `Unavailable` 状态，则尝试创建或连接密钥存储将失败并显示 [`XksProxyUriUnreachableException`](xks-troubleshooting.md#fix-xks-latency)。 |
| GetKeyMetadata | AWS KMS 请求有关与您的[外部密钥](#concept-external-key)存储库中的 KMS 密钥关联的外部密钥的信息。响应内容包含密钥规范（`AES_256`）、密钥用法（`[ENCRYPT, DECRYPT]`），以及外部密钥处于 `ENABLED` 还是 `DISABLED` 状态。 | [CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html)如果密钥规范不是 `AES_256`，或者密钥用法不是 `[ENCRYPT, DECRYPT]`，或者状态为 `DISABLED`，则 `CreateKey` 操作将失败并显示 `XksKeyInvalidConfigurationException`。 |
### 双重加密
由外部密钥存储中的 KMS 密钥加密的数据经过两次加密。首先， AWS KMS 使用特定于 KMS AWS KMS 密钥的密钥材料对数据进行加密。然后，[外部密钥管理器](#concept-ekm)使用[外部密钥](#concept-external-key)加密经过 AWS KMS加密的加密文字。此过程称为*双重加密*。
双重加密可确保外部密钥存储中经 KMS 密钥加密的数据至少与经标准 KMS 密钥加密的加密文字一样强大。它还可以保护您从外部密钥存储代理传输 AWS KMS 的纯文本。您可以借助双重加密保留对加密文字的完全控制。如果您通过外部代理永久撤消 AWS 对外部密钥的访问权限， AWS 中剩余的任何加密文字都会受到有效的加密粉碎处理。
![\[在外部密钥存储中对受 KMS 密钥保护的数据进行双重加密\]](http://docs.aws.amazon.com/zh_cn/kms/latest/developerguide/images/xks-double-encrypt-40.png)
要启用双重加密，外部密钥存储中的每个 KMS 密钥都有*两个*加密备用密钥：
+ KMS AWS KMS 密钥独有的密钥材料。此密钥材料是生成的，仅用于 AWS KMS [FIPS 140-3 安全等级 3](https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/4884) 认证的硬件安全模块 ()。HSMs
+ 外部密钥管理器中的[外部密钥](#concept-external-key)。
双重加密具有以下效果：
+ AWS KMS 如果不通过外部密钥存储代理访问您的外部密钥，则无法解密外部密钥存储库中由 KMS 密钥加密的任何密文。
+ 即使您有外部密钥材料，也无法解密外部密钥存储库中由 KMS 密钥加密的任何密文。 AWS
+ 即使您拥有外部密钥材料，也无法重新创建已从外部密钥存储中删除的 KMS 密钥。每个 KMS 密钥都有包含在对称加密文字中的唯一元数据。新的 KMS 密钥将无法解密由原始密钥加密的加密文字，即使其使用相同的外部密钥材料也是如此。
有关实际应用中的双重加密示例，请参见 [外部密钥存储的工作原理](#xks-how-it-works)。
## 外部密钥存储的工作原理
[外部密钥存储](#concept-external-key-store)、[外部密钥存储代理](#concept-xks-proxy)和[外部密钥管理器](#concept-ekm)会协同保护您的 AWS 资源。以下过程描述了典型 AWS 服务 的加密工作流程，即使用由 KMS 密钥保护的唯一数据密钥对每个对象进行加密。在本例中，您选择了外部密钥存储中的 KMS 密钥来保护对象。该示例说明了如何 AWS KMS 使用[双重加密](#concept-double-encryption)来保护传输中的数据密钥，并确保由外部密钥存储库中的 KMS 密钥生成的密文始终至少与由标准对称 KMS 密钥加密并包含密钥材料的密文一样强大。 AWS KMS
与之集成的每个实际 AWS 服务 使用的加密方法各 AWS KMS 不相同。有关详细信息，请参阅 AWS 服务 文档“安全”章节中的“数据保护”主题。
![\[外部密钥存储的工作原理\]](http://docs.aws.amazon.com/zh_cn/kms/latest/developerguide/images/xks-how-it-works-jan26.png)
1. 您向 AWS 服务 资源中添加了一个新对象。要加密对象，请 AWS KMS 使用外部密钥存储库中的 KMS 密钥 AWS 服务 向发送[GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html)请求。
1. AWS KMS 生成 256 位对称[数据密钥](data-keys.md)，并准备通过外部密钥存储代理将纯文本数据密钥的副本发送到外部密钥管理器。 AWS KMS 使用与外部[密钥存储库中的 KMS 密钥关联的密钥[材料对纯文本数据AWS KMS 密钥](#concept-double-encryption)进行加密，从而开始双重](#concept-double-encryption)加密过程。
1. AWS KMS 向与外部密钥存储关联的外部密钥存储代理发送[加密](#concept-proxy-apis)请求。该请求包括要加密的数据密钥密文以及与 KMS [密钥关联的外部密钥](#concept-external-key)的 ID。 AWS KMS 使用外部密钥存储[代理的代理身份验证凭据](#concept-xks-credential)对请求进行签名。
数据密钥的明文副本不会发送到外部密钥存储代理。
1. 外部密钥存储代理对请求进行身份验证，然后将加密请求传递给您的外部密钥管理器。
一些外部密钥存储代理还实现了可选的[授权策略](authorize-xks-key-store.md#xks-proxy-authorization)，该策略仅允许选定的主体在特定条件下执行操作。
1. 您的外部密钥管理器使用指定的外部密钥对数据密钥加密文字进行加密。外部密钥管理器将经过双重加密的数据密钥返回给外部密钥存储代理，后者再将其返回给 AWS KMS。
1. AWS KMS 将纯文本数据密钥和该数据密钥的双重加密副本返回到。 AWS 服务
1. AWS 服务 使用纯文本数据密钥对资源对象进行加密，销毁纯文本数据密钥，并将加密的数据密钥与加密对象一起存储。
有些人 AWS 服务 可能会缓存纯文本数据密钥以用于多个对象，或者在使用资源时重复使用。有关更多信息，请参阅 [不可用的 KMS 密钥如何影响数据密钥](unusable-kms-keys.md)。
[要解密加密对象， AWS 服务 必须在 Decrypt 请求 AWS KMS 中将加密的数据密钥发回给。](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html)要解密加密的数据密钥， AWS KMS 必须使用外部密钥的 ID 将加密的数据密钥发送回您的外部密钥存储代理服务器。如果对外部密钥存储代理的解密请求因任何原因失败，则 AWS KMS 无法解密加密的数据密钥， AWS 服务 也无法解密加密对象。
# 控制对外部密钥存储的访问
与标准 KMS [密钥配合使用的所有 AWS KMS 访问控制功能（密钥策略](key-policies.md)[、IAM 策略](iam-policies.md)和[授](grants.md)权）对外部密钥存储中的 KMS 密钥的作用相同。您可以使用 IAM policy 来控制对创建和管理外部密钥存储的 API 操作的访问。您可以使用 IAM 策略和密钥策略来控制对外部密钥存储 AWS KMS keys 中的的访问权限。您还可以使用适用于您的 AWS 组织的[服务控制策略](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_scps.html)和 [VPC 终端节点策略](https://docs.aws.amazon.com/vpc/latest/privatelink/interface-endpoints.html#edit-vpc-endpoint-policy)来控制对外部密钥存储中的 KMS 密钥的访问。
我们建议您仅向用户和角色提供他们可能执行的任务所需的权限。
**Topics**
+ [
## 授权外部密钥存储管理器
](#authorize-xks-managers)
+ [
## 授权外部密钥存储中 KMS 密钥的用户
](#authorize-xks-users)
+ [
## 授权 AWS KMS 与您的外部密钥存储代理进行通信
](#allowlist-kms-xks)
+ [
## 外部密钥存储代理授权（可选）
](#xks-proxy-authorization)
+ [
## mTLS 身份验证（已弃用）
](#xks-mtls)
## 授权外部密钥存储管理器
创建和管理外部密钥存储的主体需要自定义密钥存储操作的权限。以下列表描述了外部密钥存储管理器所需的最低权限。由于自定义密钥存储不是 AWS 资源，因此您无法为其他 AWS 账户密钥库中的委托人提供对外部密钥存储的权限。
+ `kms:CreateCustomKeyStore`
+ `kms:DescribeCustomKeyStores`
+ `kms:ConnectCustomKeyStore`
+ `kms:DisconnectCustomKeyStore`
+ `kms:UpdateCustomKeyStore`
+ `kms:DeleteCustomKeyStore`
要创建具有 [Amazon VPC 终端节点服务连接](choose-xks-connectivity.md#xks-vpc-connectivity)的外部密钥存储库，并且 VPC 终端节点服务归另一方所有 AWS 账户，您还需要以下权限：
+ `ec2:DescribeVPCEndpointServices`
创建外部密钥存储的主体需要权限来创建和配置外部密钥存储组件。主体只能在自己的账户中创建外部密钥存储。要创建具有 [VPC 端点服务连接](choose-xks-connectivity.md#xks-vpc-connectivity)的外部密钥存储，主体必须具有创建以下组件的权限：
+ Amazon VPC
+ 公有子网和私有子网
+ 网络负载均衡器和目标组
+ Amazon VPC 端点服务
有关详细信息，请参阅 [Amazon VPC 的身份和访问管理](https://docs.aws.amazon.com/vpc/latest/userguide/security-iam.html)、[VPC 端点和 VPC 端点服务的身份和访问管理](https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints-iam.html)以及 [Elastic Load Balancing API 权限](https://docs.aws.amazon.com/elasticloadbalancing/latest/userguide/elb-api-permissions.html)。
## 授权外部密钥存储中 KMS 密钥的用户
AWS KMS keys 在您的外部密钥存储中创建和管理的委托人需要与在[中创建和管理任何 KMS 密钥的委托人相同的权限](create-keys.md#create-key-permissions)。 AWS KMS外部密钥存储中的 KMS 密钥的[默认密钥策略](key-policy-default.md)与 AWS KMS中 KMS 密钥的默认密钥策略相同。[基于属性的访问权限控制](abac.md)（ABAC）使用标签和别名来控制对 KMS 密钥的访问，对外部密钥存储中的 KMS 密钥也有效。
使用自定义密钥存储中的 KMS 密钥进行[加密操作](manage-cmk-keystore.md#use-cmk-keystore)的委托人需要使用 KMS 密钥执行加密操作的权限，如 [kms:Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html)。您可以在 IAM 或密钥策略中提供这些权限。但是，他们无需任何额外权限即可在自定义密钥存储中使用 KMS 密钥。
要设置仅适用于外部密钥存储中 KMS 密钥的权限，请使用值为 `EXTERNAL_KEY_STORE` 的 [`kms:KeyOrigin`](conditions-kms.md#conditions-kms-key-origin) 策略条件。您可以使用此条件限制 [kms: CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) 权限或任何特定于 KMS 密钥资源的权限。例如，以下 IAM policy 允许其所连接的身份对账户中的所有 KMS 密钥调用指定操作，只要这些 KMS 密钥位于外部密钥存储中。请注意，您可以将权限限制为外部密钥存储中的 KMS 密钥和账户中的 KMS 密钥 AWS 账户，但不能限制账户中任何特定的外部密钥存储区。
```
{
"Sid": "AllowKeysInExternalKeyStores",
"Effect": "Allow",
"Action": [
"kms:Encrypt",
"kms:Decrypt",
"kms:ReEncrypt*",
"kms:GenerateDataKey*",
"kms:DescribeKey"
],
"Resource": "arn:aws:kms:us-west-2:111122223333:key/*",
"Condition": {
"StringEquals": {
"kms:KeyOrigin": "EXTERNAL_KEY_STORE"
}
}
}
```
## 授权 AWS KMS 与您的外部密钥存储代理进行通信
AWS KMS 仅通过您提供的外部密钥[存储代理与您的外部密钥](keystore-external.md#concept-xks-proxy)管理器通信。 AWS KMS 使用签[名版本 4 (Sigv4) 进程使用您指定的外部密钥存储代理身份验证凭据对代理的请求进行签名](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html)[，从而对代理进行身份验证](keystore-external.md#concept-xks-credential)。如果您为外部密钥存储代理使用[公共端点连接](choose-xks-connectivity.md#xks-connectivity-public-endpoint)， AWS KMS 则不需要任何其他权限。
但是，如果您使用的是 [VPC 终端节点服务连接](choose-xks-connectivity.md#xks-vpc-connectivity)，则必须 AWS KMS 授予权限才能为您的 Amazon VPC 终端节点服务创建接口终端节点。无论外部密钥存储代理位于您的 VPC 中，还是外部密钥存储代理位于其他地方，但使用 VPC 终端节点服务进行通信，都需要此权限 AWS KMS。
AWS KMS 要允许创建接口终端节点，请使用 [Amazon VPC 控制台](https://docs.aws.amazon.com/vpc/latest/privatelink/configure-endpoint-service.html#add-remove-permissions)或[ModifyVpcEndpointServicePermissions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyVpcEndpointServicePermissions.html)操作。允许以下主体的权限：`cks.kms..amazonaws.com`。
如果您的 Amazon VPC 终端节点服务由拥有外部密钥存储库 (XKS) 以外 AWS 账户 的其他人所有，则还需要允许 XKS 访问该 VPC 终端节点服务。 AWS 账户 为此，请将 [XKS AWS 账户 ID 列为亚马逊 VPC 终端节点服务的委托人](https://docs.aws.amazon.com/vpc/latest/privatelink/configure-endpoint-service.html#add-remove-permissions)。
------
#### [ Same AWS 账户 ]
如果您的 VPC 终端节点服务归您的外部密钥存储库所有，则必须将其添加 AWS KMS 到 VPC 终端节点服务的**允许委托人**列表中。 AWS 账户
以下示例使用[https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-vpc-endpoint-service-permissions.html](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-vpc-endpoint-service-permissions.html) AWS CLI 命令允许 AWS KMS 连接到美国西部（俄勒冈）(us-west-2) 区域中的指定 VPC 终端节点服务。在使用此命令之前，请将 Amazon VPC 服务 ID 和 AWS 区域 替换为适用于您的配置的有效值。
```
modify-vpc-endpoint-service-permissions
--service-id vpce-svc-12abc34567def0987
--add-allowed-principals '["cks.kms.us-west-2.amazonaws.com"]'
```
要移除此权限，请使用 [Amazon VPC 控制台](https://docs.aws.amazon.com/vpc/latest/privatelink/configure-endpoint-service.html#add-remove-permissions)或[ModifyVpcEndpointServicePermissions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyVpcEndpointServicePermissions.html)带`RemoveAllowedPrincipals`参数的。
------
#### [ Cross AWS 账户 ]
如果您的 VPC 终端节点服务归另一方所有 AWS 账户，则必须将两者 AWS KMS 以及您的外部密钥存储库添加到 VPC 终端节点服务的**允许委托人**列表中。
以下示例使用[https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-vpc-endpoint-service-permissions.html](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-vpc-endpoint-service-permissions.html) AWS CLI 命令允许两者 AWS KMS 以及您的外部密钥存储 (XKS) 连接到美国西部（俄勒冈）(us-west-2) 区域中的指定 VPC 终端节点服务。请首先将 Amazon VPC 服务 ID、 AWS 区域和 IAM 主体 ARN 替换为适用于您的配置的有效值，然后再使用此命令。应将 IAM 委托人替换为 XKS 所有者 AWS 账户中的委托人。
在此示例中，`arn:aws:iam::123456789012:role/cks_role` 是 XKS 所有者账户中的一个 IAM 主体，将用于创建、更新 XKS 或将其连接到您的 VPC 端点服务。如果要允许 XKS 所有者账户中的所有主体访问您的 VPC 端点服务，则可以指定 `arn:aws:iam::123456789012:root`。
```
modify-vpc-endpoint-service-permissions
--service-id vpce-svc-12abc34567def0987
--add-allowed-principals '["cks.kms.us-west-2.amazonaws.com", "arn:aws:iam::123456789012:role/cks_role"]'
```
要移除此权限，请使用 [Amazon VPC 控制台](https://docs.aws.amazon.com/vpc/latest/privatelink/configure-endpoint-service.html#add-remove-permissions)或[ModifyVpcEndpointServicePermissions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyVpcEndpointServicePermissions.html)带`RemoveAllowedPrincipals`参数的。
------
## 外部密钥存储代理授权（可选）
一些外部密钥存储代理针对其外部密钥的使用执行授权要求。允许但不要求使用外部密钥存储代理来设计和实现授权方案，该方案允许特定用户仅在特定条件下请求特定操作。例如，可以将代理配置为允许用户 A 使用特定的外部密钥进行加密，但不允许使用该外部密钥进行解密。
代理授权独立于[基于 SIGV4 的代理身份验证](keystore-external.md#concept-xks-credential)，后者 AWS KMS 需要所有外部密钥存储代理。其还独立于授权访问影响外部密钥存储或其 KMS 密钥的操作的密钥策略、IAM policy 和授权。
要启用外部密钥存储代理的授权，请在每个代[理 API 请求](keystore-external.md#concept-proxy-apis)中 AWS KMS 包含元数据，包括调用者、KMS 密钥、 AWS KMS 操作、 AWS 服务 （如果有）。外部密钥代理 API 版本 1（v1）的请求元数据如下所示。
```
"requestMetadata": {
"awsPrincipalArn": string,
"awsSourceVpc": string, // optional
"awsSourceVpce": string, // optional
"kmsKeyArn": string,
"kmsOperation": string,
"kmsRequestId": string,
"kmsViaService": string // optional
}
```
例如，您可以将代理配置为允许来自特定委托人 (`awsPrincipalArn`) 的请求，但前提是请求由特定 AWS 服务 (`kmsViaService`) 代表委托人提出。
如果代理授权失败，则相关 AWS KMS 操作将失败，并显示一条解释错误的消息。有关详细信息，请参阅 [代理授权问题](xks-troubleshooting.md#fix-xks-authorization)。
## mTLS 身份验证（已弃用）
本指南的先前版本提到了*相互传输层安全* (mTLS) 作为一种可选的辅助身份验证机制，用于对来自 AWS KMS的请求进行身份验证。在 mTLS 中，通过 TLS 通道进行通信的双方（AWS KMS 作为客户端，XKS 代理作为服务器）使用证书进行相互身份验证。
但是，[Chrome根目录计划政策（第4.2.2节）](https://googlechrome.github.io/chromerootprogram/policy-archive/policy-version-1-7/#422-pki-hierarchies-included-in-the-chrome-root-store)的变更禁止Chrome根目录商店中 CAs 包含的公众信任的根目录在2026年6月15日之后颁发带有ClientAuth扩展密钥用法 (EKU) 扩展程序的证书。因此， AWS KMS 无法再从 [Amazon Trust Services](https://www.amazontrust.com/repository/) 获得适合 mTL 的客户证书。任何用于在 2026 年 3 月 16 日 AWS KMS 之后创建新的外部密钥存储的 XKS 代理都不得需要 mTLS。2026 年 6 月 15 日之后，任何配置为需要 mTLS 的 XKS 代理都将无法与之通信。 AWS KMS客户必须依靠 Sigv4 身份验证来验证请求是否来自于。 AWS KMS有关更多信息，请参阅[外部密钥存储代理身份验证凭据](keystore-external.md#concept-xks-credential)。
# 选择外部密钥存储代理连接选项
在创建外部密钥库之前，请选择决定与外部密钥库组件 AWS KMS 通信方式的连接选项。您选择的连接选项决定了规划过程的剩余步骤。
如果要创建外部密钥存储库，则需要确定 AWS KMS 与[外部密钥存储代理](keystore-external.md#concept-xks-proxy)的通信方式。此选项将决定您需要哪些组件以及如何配置它们。 AWS KMS 支持以下连接选项。
+ [公有端点连接](#xks-connectivity-public-endpoint)
+ [VPC 端点服务连接](#xks-vpc-connectivity)
选择能满足性能和安全目标的选项。
在开始之前，[请确认您需要外部密钥存储](keystore-external.md#do-i-need-xks)。大多数客户都可以使用由密钥材料支持的 KMS AWS KMS 密钥。
**注意事项**
+ 如果您的外部密钥存储代理构建到外部密钥管理器中，则您的连接可能是预先确定的。有关详细信息，请参阅外部密钥管理器或外部密钥存储代理的文档。
+ 即使在正在运行的外部密钥存储上，您也可以[更改外部密钥存储代理的连接选项](update-xks-keystore.md)。但是，必须仔细规划和执行该过程，以尽可能减少中断和避免错误，并确保继续访问加密数据的加密密钥。
## 公有端点连接
AWS KMS 使用公共端点通过互联网连接到外部密钥存储代理（XKS 代理）。
此连接选项更易于设置和维护，并且可以与某些密钥管理模型很好地匹配。但是，此选项可能无法满足某些组织的安全要求。
![\[公有端点连接\]](http://docs.aws.amazon.com/zh_cn/kms/latest/developerguide/images/xks-public-endpoint-60.png)
**要求**
如果您选择公有端点连接，则需要满足以下条件。
+ 您的外部密钥存储代理必须可以在可公开路由的端点上访问。
+ 您可以将同一个公有端点用于多个外部密钥存储，前提是这些外部密钥存储使用不同的[代理 URI 路径](create-xks-keystore.md#require-path)值。
+ 对于具有公共终端节点连接的外部密钥存储库，以及任何具有 VPC 终端节点服务连接的外部密钥存储库 AWS 区域，即使密钥存储库位于不同的位置，您也不能使用相同的终端节点 AWS 账户。
+ 您必须获得由外部密钥存储支持的公有证书颁发机构颁发的 TLS 证书。有关列表，请参阅 [Trusted Certificate Authorities](https://github.com/aws/aws-kms-xksproxy-api-spec/blob/main/TrustedCertificateAuthorities)（受信任的证书颁发机构）。
TLS 证书上的主题公用名（CN）必须与外部密钥存储代理的[代理 URI 端点](create-xks-keystore.md#require-endpoint)中的域名相匹配。例如，如果公有端点是 `https://myproxy.xks.example.com`，即 TLS，则 TLS 证书上的 CN 必须为 `myproxy.xks.example.com` 或 `*.xks.example.com`。
+ 确保与外部密钥存储代理 AWS KMS 之间的任何防火墙都允许进出代理上端口 443 的流量。 AWS KMS 通过端口 443 进行通信。 IPv4此值不可配置。
有关外部密钥存储的所有要求，请参阅 [Assemble the prerequisites](create-xks-keystore.md#xks-requirements)（汇编先决条件）。
## VPC 端点服务连接
AWS KMS 通过创建与您创建和配置的 Amazon VPC 终端节点服务的接口终端节点来连接到外部密钥存储代理（XKS 代理）。您负责[创建 VPC 端点服务](vpc-connectivity.md)并将您的 VPC 连接到外部密钥管理器。
您的终端节点服务可以使用任何[支持的 network-to-Amazon VPC 选项](https://docs.aws.amazon.com/whitepapers/latest/aws-vpc-connectivity-options/network-to-amazon-vpc-connectivity-options.html)进行通信，包括[AWS Direct Connect](https://docs.aws.amazon.com/directconnect/latest/UserGuide/)。
此连接选项的设置和维护更为复杂。但是它使用了 AWS PrivateLink，这样就可以在不使用公共互联网的情况下私下 AWS KMS 连接到您的 Amazon VPC 和外部密钥存储代理。
您可以在您的 Amazon VPC 中找到外部密钥存储代理。
![\[VPC 端点服务连接 – VPC 中的 XKS 代理\]](http://docs.aws.amazon.com/zh_cn/kms/latest/developerguide/images/xks-proxy-in-vpc-60.png)
或者，您可以将外部密钥存储代理放在外部， AWS 云 并仅使用您的 Amazon VPC 终端节点服务进行安全通信 AWS KMS。
![\[VPC 终端节点服务连接-外部的 XKS 代理 AWS\]](http://docs.aws.amazon.com/zh_cn/kms/latest/developerguide/images/xks-proxy-via-vpc-60.png)
您也可以将外部密钥存储连接到另一个密钥存储库拥有的 Amazon VPC 终端节点服务 AWS 账户。两者都 AWS 账户 需要[必要的权限](authorize-xks-key-store.md#authorize-xks-managers)才能允许与 VPC 终端节点服务 AWS KMS 之间的通信
**了解更多：**
+ 查看创建外部密钥存储的过程，包括[汇编先决条件](create-xks-keystore.md#xks-requirements)。这将帮助您确保在创建外部密钥存储时拥有所需的所有组件。
+ 了解如何[控制对外部密钥存储的访问](authorize-xks-key-store.md)，包括外部密钥存储管理员和用户所需的权限。
+ 了解 AWS KMS 记录外部密钥存储的 [Amazon CloudWatch 指标和维度](monitoring-cloudwatch.md#kms-metrics)。我们强烈建议您创建警报来监控外部密钥存储，以便您就可以检测出性能和操作问题的早期迹象。
# 配置 VPC 端点服务连接
使用本节中的指南创建和配置使用 [VPC 终端节点服务连接](choose-xks-connectivity.md#xks-vpc-connectivity)的外部密钥存储所需的 AWS 资源和相关组件。此连接选项列出的资源是对[所有外部密钥存储所需资源](create-xks-keystore.md#xks-requirements)的补充。创建和配置所需资源后，您可以[创建外部密钥存储](create-xks-keystore.md)。
您可以在 Amazon VPC 中找到您的外部密钥存储代理，也可以在外部找到代理 AWS 并使用您的 VPC 终端节点服务进行通信。
在开始之前，[请确认您需要外部密钥存储](keystore-external.md#do-i-need-xks)。大多数客户都可以使用由密钥材料支持的 KMS AWS KMS 密钥。
**注意**
VPC 端点服务连接所需的某些元素可能包含在您的外部密钥管理器中。此外，您的软件可能有其他配置要求。在创建和配置本节中的 AWS 资源之前，请查阅代理和密钥管理器文档。
**Topics**
+ [
## VPC 端点服务连接的要求
](#xks-vpce-service-requirements)
+ [
## 步骤 1：创建 Amazon VPC 和子网
](#xks-create-vpc)
+ [
## 步骤 2：创建目标组
](#xks-target-group)
+ [
## 步骤 3：创建网络负载均衡器
](#xks-nlb)
+ [
## 步骤 4：创建 VPC 端点服务
](#xks-vpc-svc)
+ [
## 步骤 5：验证私有 DNS 名称域
](#xks-private-dns)
+ [
## 步骤 6：授权 AWS KMS 连接 VPC 终端节点服务
](#xks-vpc-authorize-kms)
## VPC 端点服务连接的要求
如果您为外部密钥存储选择 VPC 端点服务连接，则需要以下资源。
+ 连接到外部密钥管理器的 Amazon VPC。它必须在两个不同的可用区中至少拥有两个私有[子网](https://docs.aws.amazon.com/vpc/latest/userguide/configure-subnets.html)。
您可以将现有 Amazon VPC 用于外部密钥存储，前提是此 VPC [符合与外部密钥存储一起使用的要求](#xks-vpc-requirements)。多个外部密钥存储可以共享一个 Amazon VPC，但每个外部密钥存储必须有自己的 VPC 端点服务和私有 DNS 名称。
+ [由 AWS PrivateLink提供支持的 Amazon VPC 端点服务](https://docs.aws.amazon.com/vpc/latest/privatelink/privatelink-share-your-services.html)具有[网络负载均衡器](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/introduction.html)和[目标组](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-target-groups.html)。
端点服务不能要求接受。此外，您必须将 AWS KMS 添加为允许的主体。这 AWS KMS 允许创建接口端点，以便它可以与您的外部密钥存储代理进行通信。
+ VPC 端点服务在其 AWS 区域中的唯一私有 DNS 名称。
私有 DNS 名称必须是更高级别的公有域的子域。例如，如果私有 DNS 名称为 `myproxy-private.xks.example.com`，则其必须是公有域（例如 `xks.example.com` 或 `example.com`）的子域。
您必须针对私有 DNS 名称的 DNS 域[验证所有权](#xks-private-dns)。
+ 由[受支持的公有证书颁发机构](https://github.com/aws/aws-kms-xksproxy-api-spec/blob/main/TrustedCertificateAuthorities)为您的外部密钥存储代理颁发的 TLS 证书。
TLS 证书上的主题通用名称（CN）必须与私有 DNS 名称相匹配。例如，若私有 DNS 名称为 `myproxy-private.xks.example.com`，则 TLS 证书上的 CN 必须为 `myproxy-private.xks.example.com` 或 `*.xks.example.com`。
+ 为了最大限度地减少网络延迟，请在最接近[外部密钥管理器的](keystore-external.md#concept-ekm)[支持 AWS 区域](keystore-external.md#xks-regions)环境中创建 AWS 组件。如果可行，请选择网络往返时间（RTT）不超过 35 毫秒的区域。
有关外部密钥存储的所有要求，请参阅 [Assemble the prerequisites](create-xks-keystore.md#xks-requirements)（汇编先决条件）。
## 步骤 1：创建 Amazon VPC 和子网
VPC 端点服务连接需要连接到外部密钥管理器的 Amazon VPC，该管理器至少拥有两个私有子网。您可以创建 Amazon VPC 或使用满足外部密钥存储要求的现有 Amazon VPC。有关创建新 VPC 的帮助，请参阅《Amazon Virtual Private Cloud 用户指南》**中的[创建 VPC](https://docs.aws.amazon.com/vpc/latest/userguide/working-with-vpcs.html#Create-VPC)。
### Amazon VPC 的要求
Amazon VPC 端点服务必须具有以下属性才能使用外部密钥存储。
+ 必须与您的外部密钥存储位于[受支持的区域](keystore-external.md#xks-regions)中。
+ 需要至少两个私有子网，每个子网均位于不同的可用区内。
+ Amazon VPC 的私有 IP 地址范围不得与托管[外部密钥管理器](keystore-external.md#concept-ekm)的数据中心的私有 IP 地址范围重叠。
+ 所有组件都必须使用 IPv4。
您可以通过多种方式将 Amazon VPC 连接到外部密钥存储代理。选择能满足性能和安全需求的选项。有关列表，请参阅[将您的 VPC 连接到其他网络](https://docs.aws.amazon.com/vpc/latest/userguide/extend-intro.html)和 [Network-to-Amazon VPC 连接选项](https://docs.aws.amazon.com/whitepapers/latest/aws-vpc-connectivity-options/network-to-amazon-vpc-connectivity-options.html)。有关详细信息，请参阅 [Direct Connect](https://docs.aws.amazon.com/directconnect/latest/UserGuide/Welcome.html) 和《AWS Site-to-Site VPN 用户指南》[https://docs.aws.amazon.com/vpn/latest/s2svpn/](https://docs.aws.amazon.com/vpn/latest/s2svpn/)。
### 为外部密钥存储创建 Amazon VPC
使用下面的说明为外部密钥存储创建 Amazon VPC。仅当您选择 [VPC 端点服务连接](choose-xks-connectivity.md)选项时，才需要 Amazon VPC。您可以使用满足外部密钥存储要求的现有 Amazon VPC。
按照[创建 VPC、子网和其他 VPC 资源](https://docs.aws.amazon.com/vpc/latest/userguide/working-with-vpcs.html#create-vpc-and-other-resources)主题中的说明使用以下必需值。对于其他字段，请接受默认值并按要求提供名称。
| Field | Value |
| --- | --- |
| IPv4 CIDR 块 | 输入 VPC 的 IP 地址。Amazon VPC 的私有 IP 地址范围不得与托管[外部密钥管理器](keystore-external.md#concept-ekm)的数据中心的私有 IP 地址范围重叠。 |
| 可用区数量 (AZs) | 2 或更多 |
| 公有子网的数量 | 不需要任何内容（0） |
| 私有子网的数量 | 每个 AZ 一个 |
| NAT 网关 | 不需要任何内容。 |
| VPC 端点 | 不需要任何内容。 |
| 启用 DNS 主机名 | 是 |
| 启用 DNS 解析 | 是 |
请务必测试您的 VPC 通信。例如，如果您的外部密钥存储代理不在 Amazon VPC 中，请在 Amazon VPC 中创建 Amazon EC2 实例，验证 Amazon VPC 是否可以与外部密钥存储代理通信。
### 将 VPC 连接到外部密钥管理器
使用 Amazon VPC 支持的任何[网络连接选项](https://docs.aws.amazon.com/whitepapers/latest/aws-vpc-connectivity-options/network-to-amazon-vpc-connectivity-options.html)将 VPC 连接到托管外部密钥管理器的数据中心。确保 VPC（或外部密钥存储代理，如果在 VPC 中）中的 Amazon EC2 实例可以与数据中心和外部密钥管理器通信。
## 步骤 2：创建目标组
在创建所需的 VPC 端点服务之前，创建其必需的组件、网络负载均衡器（NLB）和目标组。网络负载均衡器（NLB）在多个运行状况良好的目标之间分配请求，其中任何一个目标都可以为请求提供服务。在此步骤中，您将为外部密钥存储代理创建至少具有两台主机的目标组，并将您的 IP 地址注册到目标组。
使用以下必填值，按照[配置目标组](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/create-network-load-balancer.html#configure-target-group)主题中的说明使用以下必需值。对于其他字段，请接受默认值并按要求提供名称。
| Field | Value |
| --- | --- |
| Target type | IP 地址 |
| 协议 | TCP |
| 端口： | 443 |
| IP 地址类型 | IPv4 |
| VPC | 选择 VPC，您将在其中为外部密钥存储创建 VPC 端点服务。 |
| 运行状况检查协议和路径 | 运行状况检查协议和路径将与外部密钥存储代理配置不同。请参阅外部密钥管理器或外部密钥存储代理的文档。若要为您的目标组配置运行状况检查，请参阅《网络负载均衡器的弹性负载均衡用户指南》中的[目标组的运行状况检查](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/target-group-health-checks.html)。 |
| Network | 其他私有 IP 地址 |
| IPv4 地址 | 外部密钥存储代理的私有地址 |
| 端口 | 443 |
## 步骤 3：创建网络负载均衡器
网络负载均衡器将网络流量（包括从 AWS KMS 到外部密钥存储代理的请求）分配到配置的目标。
按照[配置负载均衡器和侦听器](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/create-network-load-balancer.html#configure-load-balancer)主题中的说明配置和添加侦听器，并使用以下必需值创建负载均衡器。对于其他字段，请接受默认值并按要求提供名称。
| Field | Value |
| --- | --- |
| Scheme | Internal |
| IP 地址类型 | IPv4 |
| 网络映射 | 选择 VPC，您将在其中为外部密钥存储创建 VPC 端点服务。 |
| Mapping | 选择您为 VPC 子网配置的两个可用区（至少两个）。验证子网名称和私有 IP 地址。 |
| 协议 | TCP |
| 端口： | 443 |
| 默认操作：转发至 | 选择网络负载均衡器的[目标组](#xks-target-group)。 |
## 步骤 4：创建 VPC 端点服务
通常，您创建到服务的端点。但是，当您创建 VPC 终端节点服务时，您就是提供者，并为您的服务 AWS KMS 创建终端节点。对于外部密钥存储，使用您在上一个步骤中创建的网络负载均衡器创建 VPC 端点服务。VPC 终端节点服务可以与您的外部密钥存储库 AWS 账户 相同，也可以位于不同的地方 AWS 账户。
多个外部密钥存储可以共享一个 Amazon VPC，但每个外部密钥存储必须有自己的 VPC 端点服务和私有 DNS 名称。
按照[创建端点服务](https://docs.aws.amazon.com/vpc/latest/privatelink/create-endpoint-service.html#create-endpoint-service-nlb)主题中的说明创建具有以下必需值的 VPC 端点服务。对于其他字段，请接受默认值并按要求提供名称。
| Field | Value |
| --- | --- |
| 负载均衡器类型 | Network |
| 可用的负载均衡器 | 选择您在之前的步骤中创建的[网络负载均衡器](#xks-nlb)。如果新的负载均衡器未出现在列表中，请验证其状态是否为活动。负载均衡器状态可能需要几分钟才能从预置中变为活动。 |
| 需要接受 | False。取消选中复选框。*不需要接受*。 AWS KMS 未经手动接受，无法连接到 VPC 终端节点服务。如果需要接受，则[创建外部密钥存储](create-xks-keystore.md)的尝试会失败，并出现 `XksProxyInvalidConfigurationException` 异常。 |
| 启用私有 DNS 名称 | 将私有 DNS 名称与服务关联 |
| 私有 DNS 名称 | 输入在其 AWS 区域中唯一的私有 DNS 名称。私有 DNS 名称必须是更高级别的公有域的子域。例如，如果私有 DNS 名称为 `myproxy-private.xks.example.com`，则其必须是公有域（例如 `xks.example.com` 或 `example.com`）的子域。此私有 DNS 名称必须与在外部密钥存储代理上配置的 TLS 证书中的主题公用名（CN）相匹配。例如，若私有 DNS 名称为 `myproxy-private.xks.example.com`，则 TLS 证书上的 CN 必须为 `myproxy-private.xks.example.com` 或 `*.xks.example.com`。如果证书和私有 DNS 名称不匹配，则将外部密钥存储连接到其外部密钥存储代理的尝试会失败，连接错误代码为 `XKS_PROXY_INVALID_TLS_CONFIGURATION`。有关更多信息，请参阅 [常规配置错误](xks-troubleshooting.md#fix-xks-gen-configuration)。 |
| 支持的 IP 地址类型 | IPv4 |
## 步骤 5：验证私有 DNS 名称域
创建 VPC 端点服务时，其域验证状态为 `pendingVerification`。使用 VPC 端点服务创建外部密钥存储之前，此状态必须为 `verified`。若要验证您是否拥有与私有 DNS 名称关联的域，您必须在公有 DNS 服务器中创建 TXT 记录。
例如，如果您的 VPC 终端节点服务的私有 DNS 名称为`myproxy-private.xks.example.com`，则必须在公共域（例如`xks.example.com`或）中创建 TXT 记录`example.com`，以公有域为准。 AWS PrivateLink 先打开 TXT 记录，`xks.example.com`然后再打开`example.com`。
**提示**
添加 TXT 记录后，**Domain verification status**（域验证状态）值可能需要几分钟才能从 `pendingVerification` 变为 `verify`。
首先，使用以下任一方法找到域的验证状态。有效值包括 `verified`、`pendingVerification` 和 `failed`。
+ 在 [Amazon VPC 控制台](https://console.aws.amazon.com/vpc)中，选择 **Endpoint services**（端点服务），然后选择您的端点服务。在详细信息窗格中，查看 **Domain verification status**（域验证状态）。
+ 使用 [DescribeVpcEndpointServiceConfigurations](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeVpcEndpointServiceConfigurations.html) 操作。`State` 值在 `ServiceConfigurations.PrivateDnsNameConfiguration.State` 字段中。
如果验证状态不是 `verified`，请按照 [Domain ownership verification](https://docs.aws.amazon.com/vpc/latest/privatelink/manage-dns-names.html#verify-domain-ownership)（域所有权验证）主题中的说明将 TXT 记录添加到域的 DNS 服务器并验证 TXT 记录是否已发布。然后再次检查您的验证状态。
您无需为私有 DNS 域名创建 A 记录。在 AWS KMS 为您的 VPC 终端节点服务创建接口终端节点时， AWS PrivateLink 会自动创建一个托管区域，其中包含所需的 AWS KMS VPC 中私有域名的 A 记录。对于具有 VPC 端点服务连接的外部密钥存储，将[外部密钥存储连接到](xks-connect-disconnect.md)其外部密钥存储代理时，就会发生这种情况。
## 步骤 6：授权 AWS KMS 连接 VPC 终端节点服务
请参阅以下过程来管理您的 Amazon VPC 端点服务权限。其中的每个步骤都取决于您的外部密钥存储、VPC 端点服务以及 AWS 账户之间的连接和配置。
------
#### [ Same AWS 账户 ]
如果您的 VPC 终端节点服务归您的外部密钥存储库所有，则必须将其添加 AWS KMS 到 VPC 终端节点服务的**允许委托人**列表中。 AWS 账户 这 AWS KMS 允许为您的 VPC 终端节点服务创建接口终端节点。如果 AWS KMS 不是允许的主体，则尝试创建外部密钥存储将失败，但会出现异`XksProxyVpcEndpointServiceNotFoundException`常。
按照《AWS PrivateLink 指南》**中[管理权限](https://docs.aws.amazon.com/vpc/latest/privatelink/configure-endpoint-service.html#add-remove-permissions)主题中的说明进行操作。使用以下必需值。
| Field | Value |
| --- | --- |
| AWS KMS ARN | cks.kms..amazonaws.com例如，`cks.kms.us-east-1.amazonaws.com` |
------
#### [ Cross AWS 账户 ]
如果您的 VPC 终端节点服务归其他人所有， AWS 账户 则必须将两者 AWS KMS 以及您的账户添加到 “**允许委托人” 列表中。**这允许 AWS KMS 您的外部密钥存储库为您的 VPC 终端节点服务创建接口终端节点。如果 AWS KMS 不是允许的主体，则创建外部密钥存储的尝试将失败，并出现 `XksProxyVpcEndpointServiceNotFoundException` 异常。您需要提供外部密钥存储库所在的 AWS 账户 ARN。
按照《AWS PrivateLink 指南》**中[管理权限](https://docs.aws.amazon.com/vpc/latest/privatelink/configure-endpoint-service.html#add-remove-permissions)主题中的说明进行操作。使用以下必需值。
| Field | Value |
| --- | --- |
| AWS KMS ARN | cks.kms..amazonaws.com例如，`cks.kms.us-east-1.amazonaws.com` |
| AWS 账户 ARN | arn:aws:iam::111122223333:role/role\$1name例如，`arn:aws:iam::123456789012:role/cks_role` |
------
**下一步**：[创建外部密钥存储](create-xks-keystore.md)
# 创建外部密钥存储
您可以在每个 AWS 账户 和区域中创建一个或多个外部密钥存储库。每个外部密钥存储都必须与外部密钥管理器相关联 AWS，以及用于调解外部密钥管理器之间 AWS KMS 通信的外部密钥存储代理（XKS 代理）。有关更多信息，请参阅 [选择外部密钥存储代理连接选项](choose-xks-connectivity.md)。在开始之前，[请确认您需要外部密钥存储](keystore-external.md#do-i-need-xks)。大多数客户都可以使用由密钥材料支持的 KMS AWS KMS 密钥。
**提示**
一些外部密钥管理器为创建外部密钥存储提供了更简单的方法。有关详细信息，请参阅外部密钥管理器的文档。
在创建外部密钥存储之前，您需要[汇编先决条件](#xks-requirements)。在创建过程中，您要指定外部密钥存储的属性。最重要的是，您需要指明您的外部密钥存储是 AWS KMS 使用[公共终端节点](choose-xks-connectivity.md#xks-connectivity-public-endpoint)还是 [VPC 终端节点服务](choose-xks-connectivity.md#xks-vpc-connectivity)来连接到其外部密钥存储代理。您还可以指定连接详细信息，包括代理的 URI 端点以及该代理端点中向代理 AWS KMS 发送 API 请求的路径。
**注意事项**
+ KMS 无法 IPv6 与外部密钥存储库进行通信。
+ 如果您使用公共终端节点连接，请确保它 AWS KMS 可以使用 HTTPS 连接通过互联网与您的代理进行通信。这包括在外部密钥存储代理上配置 TLS，并确保与代理之间的 AWS KMS 任何防火墙都允许代理上进出端口 443 的 IPv4 流量。在创建具有公共端点连接的外部密钥存储时，通过向外部密钥存储代理发送状态请求来 AWS KMS 测试连接。此测试会验证端点是否可访问，以及外部密钥存储代理是否会接受使用[外部密钥存储代理身份验证凭证](keystore-external.md#concept-xks-credential)签名的请求。如果此测试请求失败，则创建外部密钥存储的操作将失败。
+ 如果使用 VPC 端点服务连接，请确保网络负载均衡器、私有 DNS 名称和 VPC 端点服务配置正确且可运行。如果外部密钥存储代理不在 VPC 中，则需要确保 VPC 终端节点服务可以与外部密钥存储代理通信。 （在将[外部密钥存储库连接到其外部密钥存储](xks-connect-disconnect.md)代理时AWS KMS 测试 VPC 终端节点服务的连接。）
+ AWS KMS 记录 [Amazon CloudWatch 指标和维度](monitoring-cloudwatch.md#kms-metrics)，尤其是外部密钥存储的指标和维度。基于其中一些指标的监控图表显示在每个外部密钥存储的 AWS KMS 控制台中。我们强烈建议您使用这些指标创建监控外部密钥存储的警报。这些警报会在发生性能和操作问题之前提醒您注意相关问题的早期迹象。有关说明，请参阅[监控外部密钥存储](xks-monitoring.md)。
+ 外部密钥存储受[资源限额](resource-limits.md#cks-resource-quota)的限制。在外部密钥存储中使用 KMS 密钥受[请求限额](requests-per-second.md#rps-key-stores)的限制。在设计外部密钥存储实现之前，请查看这些限额。
**注意**
检查您的配置中是否存在可能使其无法运行的循环依赖关系。
例如，如果您使用 AWS 资源创建外部密钥存储代理，请确保操作代理不需要通过该代理访问的外部密钥存储中有 KMS 密钥。
所有新的外部密钥存储都在断开连接的状态下创建。在外部密钥存储中创建 KMS 密钥之前，您必须[将其连接到](about-xks-connecting.md)外部密钥存储代理。要更改外部密钥存储的属性，请[编辑外部密钥存储设置](update-xks-keystore.md)。
**Topics**
+ [
## 汇编先决条件
](#xks-requirements)
+ [
## 创建新的外部密钥存储
](#create-xks)
## 汇编先决条件
在创建外部密钥存储库之前，您需要组装所需的组件，包括用于支持[外部密钥存储的外部密钥管理器和](keystore-external.md#concept-ekm)将 AWS KMS 请求转换为[外部密钥管理器可以理解的格式的外部密钥存储代](keystore-external.md#concept-xks-proxy)理。
所有外部密钥存储都需要以下组件。除了这些组件，您还需要提供组件来支持自己选择的[外部密钥存储代理连接选项](choose-xks-connectivity.md)。
**提示**
您的外部密钥管理器可能包含其中一些组件，或者可以为您配置这些组件。有关详细信息，请参阅外部密钥管理器的文档。
如果您在 AWS KMS 控制台中创建外部密钥存储，则可以选择上传基于 JSON 的[代理配置文件，该文件](#proxy-configuration-file)指定代理 [URI 路径和代理](#require-path)[身份验证](keystore-external.md#concept-xks-credential)凭据。一些外部密钥存储代理会为您生成此文件。有关详细信息，请参阅外部密钥存储代理或外部密钥管理器的文档。
### 外部密钥管理器
每个外部密钥存储都需要至少一个[外部密钥管理器](keystore-external.md#concept-ekm)实例。这可以是实体或虚拟硬件安全模块（HSM），也可以是密钥管理软件。
您可以使用单个密钥管理器，但我们建议准备至少两个共享加密密钥的相关密钥管理器实例，以便实现冗余配置。外部密钥存储不需要独占使用外部密钥管理器。但是，外部密钥管理器必须有能力处理来自使用外部密钥存储中的 KMS 密钥来保护您的资源的 AWS 服务的预期频率的加密和解密请求。您的外部密钥管理器应配置为每秒最多处理 1800 个请求，并在 250 毫秒的超时限制内响应每个请求。我们建议您将外部密钥管理器放在附近， AWS 区域 以便网络往返时间 (RTT) 为 35 毫秒或更短。
如果外部密钥存储代理允许，则可以更改与外部密钥存储代理关联的外部密钥管理器，但新的外部密钥管理器必须是具有相同密钥材料的备份或快照。如果您与 KMS 密钥关联的外部密钥不再可供外部密钥存储代理使用，则 AWS KMS 无法解密使用 KMS 密钥加密的密文。
外部密钥存储代理必须可以访问外部密钥管理器。如果代理的[GetHealthStatus](keystore-external.md#xks-concepts)响应报告所有外部密钥管理器实例都是`Unavailable`，则所有创建外部密钥存储的尝试都将失败，并显示为[`XksProxyUriUnreachableException`](xks-troubleshooting.md#fix-xks-proxy)。
### 外部密钥存储代理
您必须指定符合 [AWS KMS 外部密钥存储代理 API 规范](https://github.com/aws/aws-kms-xksproxy-api-spec/)中设计要求的[外部密钥存储代理](keystore-external.md#concept-xks-proxy)（XKS 代理）。您可以开发或购买外部密钥存储代理，也可以使用外部密钥管理器提供或内置的外部密钥存储代理。 AWS KMS 建议将您的外部密钥存储代理配置为每秒最多处理 1800 个请求，并在每个请求的 250 毫秒超时内做出响应。我们建议您将外部密钥管理器放在附近， AWS 区域 以便网络往返时间 (RTT) 为 35 毫秒或更短。
您可以将外部密钥存储代理用于多个外部密钥存储，但每个外部密钥存储必须在其请求的外部密钥存储代理中具有唯一的 URI 端点和路径。
如果您使用的是 VPC 端点服务连接，则可以在 Amazon VPC 中找到您的外部密钥存储代理，但这不是必需的。您可以将代理定位在外部 AWS（例如私有数据中心），并且只能使用 VPC 终端节点服务与代理通信。
### 代理身份验证凭证
要创建外部密钥存储，必须指定外部密钥存储代理身份验证凭证（`XksProxyAuthenticationCredential`）。
您必须在外部密钥存储代理 AWS KMS 上为建立[身份验证凭据](keystore-external.md#concept-xks-credential) (`XksProxyAuthenticationCredential`)。 AWS KMS 使用签[名版本 4 (Sigv4) 流程使用外部密钥存储代理身份验证凭据对代理的请求进行签名](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html)，从而对代理进行身份验证。您可以在创建外部密钥存储时指定身份验证凭证，并且可以随时[对其进行更改](update-xks-keystore.md)。如果代理要轮换凭证，则务必更新外部密钥存储的凭证值。
代理身份验证凭证有两个部分。您必须为外部密钥存储提供这两部分。
+ 访问密钥 ID：标识秘密访问密钥。您能以明文形式提供此 ID。
+ 秘密访问密钥：凭证的秘密部分。 AWS KMS 在存储凭据之前对凭据中的私有访问密钥进行加密。
AWS KMS 用于签署外部密钥存储代理请求的 Sigv4 凭据与您账户中任何委托人关联的任何 Sigv4 凭据无关。 AWS Identity and Access Management AWS 不要将任何 IAM SigV4 凭证重复用于外部密钥存储代理。
### 代理连接
要创建外部密钥存储，您必须指定外部密钥存储代理连接选项（`XksProxyConnectivity`）。
AWS KMS 可以使用[公共终端节点](choose-xks-connectivity.md#xks-connectivity-public-endpoint)或 Amazon Virtu [al Private Cloud (Amazon VPC) 终端节点服务](choose-xks-connectivity.md#xks-vpc-connectivity)与您的外部密钥存储代理进行通信。公有端点虽然更易于配置和维护，但可能无法满足每次安装的安全要求。如果您选择 Amazon VPC 端点服务连接选项，则必须创建和维护所需的组件，包括在两个不同可用区内至少有两个子网的 Amazon VPC、具有网络负载均衡器和目标组的 VPC 端点服务，以及 VPC 端点服务的私有 DNS 名称。
您可以为外部密钥存储[更改代理连接选项](update-xks-keystore.md)。不过，您必须确保外部密钥存储中与 KMS 密钥相关的密钥材料持续可用。否则， AWS KMS 无法解密使用这些 KMS 密钥加密的任何密文。
有关确定哪种代理连接选项最适合外部密钥存储的帮助信息，请参阅 [选择外部密钥存储代理连接选项](choose-xks-connectivity.md)。有关创建和配置 VPC 端点服务连接的帮助信息，请参阅 [配置 VPC 端点服务连接](vpc-connectivity.md)。
### 代理 URI 端点
要创建外部密钥存储库，必须指定用于向外部密钥存储代理发送请求的端点 (`XksProxyUriEndpoint`)。 AWS KMS
协议必须是 HTTPS。 AWS KMS 通过端口 44 IPv4 3 进行通信。不要在代理 URI 端点值中指定端口。
+ [公有端点连接](choose-xks-connectivity.md#xks-connectivity-public-endpoint) – 为外部密钥存储代理指定公开可用的端点。在创建外部密钥存储之前，此端点必须可供访问。
+ [VPC 端点服务连接](choose-xks-connectivity.md#xks-vpc-connectivity) – 指定 `https://`，后接 VPC 端点服务的私有 DNS 名称。
在外部密钥存储代理上配置的 TLS 服务器证书必须与外部密钥存储代理 URI 端点中的域名相匹配，并且由支持外部密钥存储的证书颁发机构颁发。有关列表，请参阅 [Trusted Certificate Authorities](https://github.com/aws/aws-kms-xksproxy-api-spec/blob/main/TrustedCertificateAuthorities)（受信任的证书颁发机构）。在颁发 TLS 证书之前，证书颁发机构会要求您提供域所有权证明。
TLS 证书上的主题通用名称（CN）必须与私有 DNS 名称相匹配。例如，若私有 DNS 名称为 `myproxy-private.xks.example.com`，则 TLS 证书上的 CN 必须为 `myproxy-private.xks.example.com` 或 `*.xks.example.com`。
您可以[更改代理 URI 端点](update-xks-keystore.md)，但请确保外部密钥存储代理有权访问与外部密钥存储中的 KMS 密钥关联的密钥材料。否则， AWS KMS 无法解密使用这些 KMS 密钥加密的任何密文。
**唯一性要求**
+ 合并的代理 URI 端点（`XksProxyUriEndpoint`）和代理 URI 路径（`XksProxyUriPath`）值在 AWS 账户 和区域中必须具备唯一性。
+ 使用公有端点连接的外部密钥存储可以共享相同的代理 URI 端点，前提是这些外部密钥存储具有不同的代理 URI 路径值。
+ 具有公共终端节点连接的外部密钥存储不能使用与任何具有相同 VPC 终端节点服务连接的外部密钥存储相同的代理 URI 终端节点值 AWS 区域，即使密钥存储库位于不同的位置 AWS 账户。
+ 每个具有 VPC 端点连接的外部密钥存储都必须有自己的私有 DNS 名称。代理 URI 终端节点（私有 DNS 名称）在 AWS 账户 和区域中必须是唯一的。
### 代理 URI 路径
要创建外部密钥存储库，您必须在外部密钥存储代理中指定[所需代理](keystore-external.md#concept-proxy-apis)的基本路径 APIs。该值必须以开头`/`且必须以/kms/xks/v1 结尾，其中`v1`表示外部密钥存储代理的 AWS KMS API 版本。此路径可以在必要元素之间包含可选前缀，例如 `/example-prefix/kms/xks/v1`。要找到此值，请参阅外部密钥存储代理的文档。
AWS KMS 将代理请求发送到由代理 URI 端点和代理 URI 路径串联所指定的地址。例如，如果代理 URI 端点是，`https://myproxy.xks.example.com`而代理 URI 路径是`/kms/xks/v1`，则将其代理 API 请求 AWS KMS 发送到`https://myproxy.xks.example.com/kms/xks/v1`。
您可以[更改代理 URI 路径](update-xks-keystore.md)，但要确保外部密钥存储代理有权访问与外部密钥存储中的 KMS 密钥关联的密钥材料。否则， AWS KMS 无法解密使用这些 KMS 密钥加密的任何密文。
**唯一性要求**
+ 合并的代理 URI 端点（`XksProxyUriEndpoint`）和代理 URI 路径（`XksProxyUriPath`）值在 AWS 账户 和区域中必须具备唯一性。
### VPC 终端节点服务
指定用于与外部密钥存储代理通信的 Amazon VPC 端点服务的名称。只有使用 VPC 端点服务连接的外部密钥存储才需要此组件。有关为外部密钥存储设置和配置 VPC 端点服务的帮助信息，请参阅 [配置 VPC 端点服务连接](vpc-connectivity.md)。
VPC 端点服务必须具有以下属性：
+ VPC 端点服务可与外部密钥存储位于同一或不同 AWS 账户 中。
+ VPC 终端节点服务必须与外部密钥存储库位于同一 AWS 区域 位置。
+ 如果 VPC 终端节点服务位于其他 VPC 终端节点服务中，则需要提供该服务的 AWS 账户 ID AWS 账户。
+ 其必须有至少连接到两个子网的网络负载均衡器（NLB），每个子网位于不同的可用区中。
+ VPC 终端节点服务的*允许委托人列表*必须包括该区域的 AWS KMS 服务委托人：`cks.kms..amazonaws.com`，例如`cks.kms.us-east-1.amazonaws.com`。
+ 如果您的 Amazon VPC 终端节点服务归拥有外部密钥存储库 (XKS) 以外 AWS 账户 的其他人所有，则还需要允许 XKS 访问该 VPC 终端节点服务。 AWS 账户 为此，请将 [XKS AWS 账户 ID 列为亚马逊 VPC 终端节点服务的委托人](https://docs.aws.amazon.com/vpc/latest/privatelink/configure-endpoint-service.html#add-remove-permissions)。
+ 其不得要求接受连接请求。
+ 其必须在更高级别的公有域内具有私有 DNS 名称。例如，在 `xks.example.com` 公有域中，私有 DNS 名称可能为 myproxy-private.xks.example.com。
使用 VPC 端点服务连接的外部密钥存储的私有 DNS 名称，在其 AWS 区域中必须具备唯一性。
+ 私有 DNS 名称域的[域验证状态](vpc-connectivity.md#xks-private-dns)必须为 `verified`。
+ 在外部密钥存储代理上配置的 TLS 服务器证书，必须指定可访问端点的私有 DNS 主机名。
**唯一性要求**
+ 具有 VPC 端点连接的外部密钥存储可以共享 `Amazon VPC`，但每个外部密钥存储必须有自己的 VPC 端点服务和私有 DNS 名称。
### 代理配置文件
*代理配置文件*是基于 JSON 的可选文件，其中包含外部密钥存储的[代理 URI 路径](#require-path)和[代理身份验证凭证](#require-credential)属性的值。在 AWS KMS 控制台中创建或[编辑外部密钥存储](update-xks-keystore.md)时，您可以上传代理配置文件来为外部密钥存储提供配置值。使用此文件可以避免键入和粘贴错误，并确保外部密钥存储中的值与外部密钥存储代理中的值相匹配。
代理配置文件由外部密钥存储代理生成。要了解外部密钥存储代理是否提供代理配置文件，请参阅您的外部密钥存储代理文档。
下面是具有虚拟值的格式正确的代理配置文件示例。
```
{
"XksProxyUriPath": "/example-prefix/kms/xks/v1",
"XksProxyAuthenticationCredential": {
"AccessKeyId": "ABCDE12345670EXAMPLE",
"RawSecretAccessKey": "0000EXAMPLEFA5FT0mCc3DrGUe2sti527BitkQ0Zr9MO9+vE="
}
}
```
只有在 AWS KMS 控制台中创建或编辑外部密钥存储时，才能上传代理配置文件。您不能将其与[CreateCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateCustomKeyStore.html)或[UpdateCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_UpdateCustomKeyStore.html)操作一起使用，但可以使用代理配置文件中的值来确保参数值正确无误。
## 创建新的外部密钥存储
准备好必要的先决条件后，可以在 AWS KMS 控制台中或使用[CreateCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateCustomKeyStore.html)操作创建新的外部密钥存储。
### 使用控制 AWS KMS 台
在创建外部密钥存储之前，请[选择代理连接类型](choose-xks-connectivity.md)，并确保已创建和配置了所有[必需组件](#xks-requirements)。如果需要查找任何所需值的帮助信息，请查阅外部密钥存储代理或密钥管理软件的文档。
**注意**
在中创建外部密钥存储时 AWS 管理控制台，可以上传基于 JSON 的*代理配置文件*，其中包含代理 [URI 路径和代理](#require-path)[身份验证](#require-credential)凭据的值。一些代理会为您生成此文件，但其并非必要项目。
1. 登录 AWS 管理控制台 并在 [https://console.aws.amazon.com/km](https://console.aws.amazon.com/kms) s 处打开 AWS Key Management Service (AWS KMS) 控制台。
1. 要更改 AWS 区域，请使用页面右上角的区域选择器。
1. 在导航窗格中，选择 **Custom key stores**（自定义密钥存储）、**External key stores**（外部密钥存储）。
1. 选择 **Create external key store**（创建外部密钥存储）。
1. 为外部密钥存储输入易记名称。该名称在您账户的所有外部密钥存储中必须具备唯一性。
**重要**
不要在此字段中包含机密或敏感信息。此字段可能会以纯文本形式显示在 CloudTrail 日志和其他输出中。
1. 选择[代理连接](#require-connectivity)类型。
您的代理连接选择决定了外部密钥存储代理[所需的组件](#xks-requirements)。有关做出此选择的帮助信息，请参阅 [选择外部密钥存储代理连接选项](choose-xks-connectivity.md)。
1. 如果您的 VPC 端点服务位于不同的 AWS 账户中，请选择**跨账户 VPC 端点服务**。然后在 VPC 终端节点**服务所有者账户 AWS 账户 ID 字段中输入 VPC 终端节点所有者的 ID**。
1. 选择或输入此外部密钥存储的 [VPC 端点服务](#require-vpc-service-name)的名称。此步骤仅在外部密钥存储代理连接类型为 **VPC 端点服务**时出现。
VPC 终端节点服务及其 VPCs 必须满足外部密钥存储的要求。有关更多信息，请参阅 [汇编先决条件](#xks-requirements)。
1. 选择或输入此外部密钥存储的 [VPC 端点服务](#require-vpc-service-name)的名称。此步骤仅在外部密钥存储代理连接类型为 **VPC 端点服务**时出现。
VPC 终端节点服务及其 VPCs 必须满足外部密钥存储的要求。有关更多信息，请参阅 [汇编先决条件](#xks-requirements)。
1. 输入[代理 URI 端点](#require-endpoint)。协议必须是 HTTPS。 AWS KMS 通过端口 44 IPv4 3 进行通信。不要在代理 URI 端点值中指定端口。
如果 AWS KMS 识别出您在上一步中指定的 VPC 终端节点服务，它将为您填写此字段。
若使用公有端点连接，请输入公开可用的端点 URI。若使用 VPC 端点连接，输入 `https://`，后接 VPC 端点服务的私有 DNS 名称。
1. 要输入[代理 URI 路径](#require-path)前缀和[代理身份验证凭证](#require-credential)的值，请上传代理配置文件或手动输入值。
+ 如果您有包含[代理 URI 路径](#require-path.title)和[代理身份验证凭证](#require-credential)值的可选[代理配置文件](#proxy-configuration-file)，请选择 **Upload configuration file**（上传配置文件）。然后按照步骤上传该文件。
上传文件后，控制台会在可编辑字段中显示文件中的值。您可以立即更改值，也可以在创建外部密钥存储后[编辑这些值](update-xks-keystore.md)。
要显示秘密访问密钥的值，请选择 **Show secret access key**（显示私有访问密钥）。
+ 如果您没有代理配置文件，则可以手动输入代理 URI 路径和代理身份验证凭证值。
1. 如果没有代理配置文件，您可以手动输入代理 URI。控制台提供所需的**/kms/xks/v1** 值。
如果[代理 URI 路径](#require-path)包含可选前缀，例如 `/example-prefix/kms/xks/v1` 中的 `example-prefix`，请在 **Proxy URI path prefix**（代理 URI 路径前缀）字段中输入该前缀。如若没有，则将字段留空。
1. 如果没有代理配置文件，您可以手动输入[代理身份验证凭证](keystore-external.md#concept-xks-credential)。访问密钥 ID 和秘密访问密钥均为必填项。
+ 在 **Proxy credential: Access key ID**（代理凭证：访问密钥 ID）中，输入代理身份验证凭证的访问密钥 ID。访问密钥 ID 标识秘密访问密钥。
+ 在 **Proxy credential: Secret access key**（代理凭证：秘密访问密钥）中，输入代理身份验证凭证的秘密访问密钥。
要显示秘密访问密钥的值，请选择 **Show secret access key**（显示私有访问密钥）。
此过程不会设置或更改您在外部密钥存储代理上建立的身份验证凭证。其只是将这些值关联到外部密钥存储。有关设置、更改和轮换代理身份验证凭证的信息，请参阅外部密钥存储代理或密钥管理软件的文档。
如果您的代理身份验证凭证发生变化，请[编辑外部密钥存储的凭证设置](update-xks-keystore.md)。
1. 选择 **Create external key store**（创建外部密钥存储）。
当该过程成功时，新的外部密钥存储将显示在账户和区域的外部密钥存储列表中。如果该过程失败，则会显示一条错误消息，描述问题并提供有关如何解决该问题的帮助。如果您需要更多帮助，请参阅[CreateKey 外部密钥错误](xks-troubleshooting.md#fix-external-key-create)。
**下一步**：不会自动连接新的外部密钥存储。必须先将外部密钥存储库[连接到其外部密钥存储代理服务器，然后才能在外部密钥存储](xks-connect-disconnect.md)库中进行创建 AWS KMS keys 。
### 使用 AWS KMS API
您可以使用该[CreateCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateCustomKeyStore.html)操作来创建新的外部密钥存储库。如果需要查找所需参数值的帮助信息，请参阅外部密钥存储代理或密钥管理软件的文档。
**提示**
使用 `CreateCustomKeyStore` 操作时，您无法上传[代理配置文件](#proxy-configuration-file)。不过，您可以使用代理配置文件中的值来确保参数值正确无误。
要创建外部密钥存储，`CreateCustomKeyStore` 操作需要以下参数值。
+ `CustomKeyStoreName` - 外部密钥存储的易记名称，该名称在账户中具备唯一性。
**重要**
不要在此字段中包含机密或敏感信息。此字段可能会以纯文本形式显示在 CloudTrail 日志和其他输出中。
+ `CustomKeyStoreType` – 指定 `EXTERNAL_KEY_STORE`。
+ [`XksProxyConnectivity`](#require-connectivity) – 指定 `PUBLIC_ENDPOINT` 或 `VPC_ENDPOINT_SERVICE`。
+ [`XksProxyAuthenticationCredential`](keystore-external.md#concept-xks-credential) – 指定访问密钥 ID 和秘密访问密钥。
+ [`XksProxyUriEndpoint`](#require-endpoint) – AWS KMS 用于与外部密钥存储代理通信的端点。
+ [`XksProxyUriPath`](#require-path)— 代理内到代理的路径 APIs。
+ [`XksProxyVpcEndpointServiceName`](#require-vpc-service-name) – 仅当 `XksProxyConnectivity` 值为 `VPC_ENDPOINT_SERVICE` 时才需要。
**注意**
如果您使用 AWS CLI 版本 1.0，请在指定带有 HTTP 或 HTTPS 值的参数（例如`XksProxyUriEndpoint`参数）之前运行以下命令。
```
aws configure set cli_follow_urlparam false
```
否则， AWS CLI 版本 1.0 会将参数值替换为在该 URI 地址中找到的内容，从而导致以下错误：
```
Error parsing parameter '--xks-proxy-uri-endpoint': Unable to retrieve
https:// : received non 200 status code of 404
```
以下示例使用虚拟值。在运行命令之前，将虚拟值替换为外部密钥存储的有效值。
创建使用公有端点连接的外部密钥存储。
```
$ aws kms create-custom-key-store
--custom-key-store-name ExampleExternalKeyStorePublic \
--custom-key-store-type EXTERNAL_KEY_STORE \
--xks-proxy-connectivity PUBLIC_ENDPOINT \
--xks-proxy-uri-endpoint https://myproxy.xks.example.com \
--xks-proxy-uri-path /kms/xks/v1 \
--xks-proxy-authentication-credential AccessKeyId=,RawSecretAccessKey=
```
创建使用 VPC 端点服务连接的外部密钥存储。
```
$ aws kms create-custom-key-store
--custom-key-store-name ExampleExternalKeyStoreVPC \
--custom-key-store-type EXTERNAL_KEY_STORE \
--xks-proxy-connectivity VPC_ENDPOINT_SERVICE \
--xks-proxy-vpc-endpoint-service-name com.amazonaws.vpce.us-east-1.vpce-svc-example \
--xks-proxy-uri-endpoint https://myproxy-private.xks.example.com \
--xks-proxy-uri-path /kms/xks/v1 \
--xks-proxy-authentication-credential AccessKeyId=,RawSecretAccessKey=
```
当此操作成功时，`CreateCustomKeyStore` 将返回自定义密钥存储 ID，如以下示例响应中所示。
```
{
"CustomKeyStoreId": cks-1234567890abcdef0
}
```
如果操作失败，请更正异常指示的错误，然后重试。有关其他帮助，请参阅[排查外部密钥存储的问题](xks-troubleshooting.md)。
**下一步**：要使用外部密钥存储，请[将其连接到外部密钥存储代理](xks-connect-disconnect.md)。
# 编辑外部密钥存储属性
您可以编辑现有外部密钥存储的选定属性。
在连接或断开外部密钥存储后，您可以编辑某些属性。若要编辑其他属性，则必须先[断开外部密钥存储](xks-connect-disconnect.md)与其外部密钥存储代理的连接。外部密钥存储的[连接状态](xks-connect-disconnect.md#xks-connection-state)必须为 `DISCONNECTED`。在外部密钥存储断开后，您可以管理密钥存储及其 KMS 密钥，但无法在外部密钥存储中创建或使用 KMS 密钥。要查找外部密钥存储库的[连接状态](xks-connect-disconnect.md#xks-connection-state)，请使用[DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html)操作或查看外部密钥存储详细信息页面上的 “**常规配置**” 部分。
在更新外部密钥存储库的属性之前，使用新值向外部密钥存储代理 AWS KMS 发送[GetHealthStatus](keystore-external.md#concept-proxy-apis)请求。如果请求成功，则表明您可以使用更新后的属性值连接到外部密钥存储代理并进行身份验证。如果请求失败，编辑操作也将失败，并且会显示标识错误的异常。
编辑操作完成后，外部密钥存储库的更新属性值将显示在 AWS KMS 控制台和`DescribeCustomKeyStores`响应中。不过，要让更改完全生效，可能需要长达五分钟的时间。
如果您在 AWS KMS 控制台中编辑外部密钥存储，则可以选择上传基于 JSON 的[代理配置文件，该文件](create-xks-keystore.md#proxy-configuration-file)指定代理 [URI 路径和代理](create-xks-keystore.md#require-path)[身份验证](keystore-external.md#concept-xks-credential)凭据。一些外部密钥存储代理会为您生成此文件。有关详细信息，请参阅外部密钥存储代理或外部密钥管理器的文档。
**警告**
更新后的属性值必须将您的外部密钥存储连接到与先前值相同的外部密钥管理器的代理，或者使用相同的加密密钥对外部密钥管理器进行备份或快照。如果外部密钥存储永久失去对与其 KMS 密钥关联的外部密钥的访问权限，则在这些外部密钥下加密的加密文字将无法恢复。特别是，更改外部密钥存储库的代理连接可能会 AWS KMS 阻止访问您的外部密钥。
**提示**
一些外部密钥管理器为编辑外部密钥存储属性提供了更简单的方法。有关详细信息，请参阅外部密钥管理器的文档。
您可以更改外部密钥存储的以下属性。
| 可编辑的外部密钥存储属性 | 任何连接状态 | 需要“已断开连接”状态 |
| --- | --- | --- |
| 自定义密钥存储名称 自定义密钥存储必需的易记名称。 不要在此字段中包含机密或敏感信息。此字段可能会以纯文本形式显示在 CloudTrail 日志和其他输出中。 | ![\[Green checkmark icon indicating success or completion.\]](http://docs.aws.amazon.com/zh_cn/kms/latest/developerguide/images/icon-successful.png) | |
| [代理身份验证凭证](keystore-external.md#concept-xks-credential) () XksProxyAuthenticationCredential（即使只更改一个元素，您也必须同时指定访问密钥 ID 和秘密访问密钥。） | ![\[Green checkmark icon indicating success or completion.\]](http://docs.aws.amazon.com/zh_cn/kms/latest/developerguide/images/icon-successful.png) | |
| [代理 URI 路径](create-xks-keystore.md#require-path) (XksProxyUriPath) | ![\[Green checkmark icon indicating success or completion.\]](http://docs.aws.amazon.com/zh_cn/kms/latest/developerguide/images/icon-successful.png) | |
| [代理连接](keystore-external.md#concept-xks-connectivity) (XksProxyConnectivity)（您还必须更新代理 URI 端点。如果要更改为 VPC 端点服务连接，则必须指定代理 VPC 端点服务名称。） | | ![\[Green checkmark icon indicating success or completion.\]](http://docs.aws.amazon.com/zh_cn/kms/latest/developerguide/images/icon-successful.png) |
| [代理 URI 端点](create-xks-keystore.md#require-endpoint) (XksProxyUriEndpoint)如果更改代理端点 URI，您可能还需要更改关联的 TLS 证书。 | | ![\[Green checkmark icon indicating success or completion.\]](http://docs.aws.amazon.com/zh_cn/kms/latest/developerguide/images/icon-successful.png) |
| [代理 VPC 终端节点服务名称](create-xks-keystore.md#require-vpc-service-name) (XksProxyVpcEndpointServiceName)（此字段是 VPC 端点服务连接的必填字段） | | ![\[Green checkmark icon indicating success or completion.\]](http://docs.aws.amazon.com/zh_cn/kms/latest/developerguide/images/icon-successful.png) |
| [VPC 终端节点服务所有者](create-xks-keystore.md#require-vpc-service-name) (XksProxyVpcEndpointServiceOwner)（此字段是 VPC 端点服务连接的必填字段） | | ![\[Green checkmark icon indicating success or completion.\]](http://docs.aws.amazon.com/zh_cn/kms/latest/developerguide/images/icon-successful.png) |
## 编辑外部密钥存储的属性
您可以在 AWS KMS 控制台中或使用[UpdateCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_UpdateCustomKeyStore.html)操作来编辑外部密钥存储库的属性。
### 使用控制 AWS KMS 台
编辑密钥库时，可以更改任何可编辑的值。某些更改要求将外部密钥存储与其外部密钥存储代理断开连接。
如果您正在编辑代理 URI 路径或代理身份验证凭证，则可以输入新值或上传包含新值的外部密钥存储[代理配置文件](create-xks-keystore.md#proxy-configuration-file)。
1. 登录 AWS 管理控制台 并在 [https://console.aws.amazon.com/km](https://console.aws.amazon.com/kms) s 处打开 AWS Key Management Service (AWS KMS) 控制台。
1. 要更改 AWS 区域，请使用页面右上角的区域选择器。
1. 在导航窗格中，选择 **Custom key stores**（自定义密钥存储）、**External key stores**（外部密钥存储）。
1. 选择要编辑的密钥存储。
1. 如有必要，请断开外部密钥存储与其外部密钥存储代理的连接。从 **Key store actions**（密钥存储操作）菜单中选择 **Disconnect**（断开连接）。
1. 从 **Key store actions**（密钥存储操作）菜单中选择 **Edit**（编辑）。
1. 更改一个或多个可编辑的外部密钥存储属性。您还可以上传包含代理 URI 路径和代理身份验证凭证值的外部密钥存储[代理配置文件](create-xks-keystore.md#proxy-configuration-file)。即使文件中指定的某些值没有更改，也可以使用代理配置文件。
1. 选择 **Update external key store**（更新外部密钥存储）。
1. 查看警告，如果您决定继续，请确认警告，然后选择 **Update external key store**（更新外部密钥存储）。
在此过程成功后，将显示一条消息，描述您编辑的属性。如果此过程失败，则会显示一条错误消息，描述问题并提供有关如何解决问题的帮助。
1. 如有必要，重新连接外部密钥存储。从 **Key store actions**（密钥存储操作）菜单中选择 **Connect**（连接）。
您可以让外部密钥存储保持断开状态。不过，在其断开连接后，您无法在外部密钥存储中创建 KMS 密钥或在[加密操作](manage-cmk-keystore.md#use-cmk-keystore)中使用外部密钥存储中的 KMS 密钥。
### 使用 AWS KMS API
要更改外部密钥存储库的属性，请使用[UpdateCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_UpdateCustomKeyStore.html)操作。您可以在同一操作中更改外部密钥存储的多个属性。如果操作成功，则 AWS KMS 返回一个 HTTP 200 响应和一个没有属性的 JSON 对象。
使用 `CustomKeyStoreId` 参数标识外部密钥存储。使用其他参数更改属性。您不能在 `UpdateCustomKeyStore` 操作中使用[代理配置文件](create-xks-keystore.md#proxy-configuration-file)。只有 AWS KMS 控制台支持代理配置文件。不过，您可以使用代理配置文件来帮助自己确定外部密钥存储代理的正确参数值。
本部分中的示例使用 [AWS Command Line Interface (AWS CLI)](https://aws.amazon.com/cli/)，但您可以使用任何受支持的编程语言。
在开始之前，[如有必要](#update-xks-keystore)，请[断开外部密钥存储](xks-connect-disconnect.md)与其外部密钥存储代理的连接。更新后，如有必要，您可以将[外部密钥存储重新连接](xks-connect-disconnect.md)到其外部密钥存储代理。您可以让外部密钥存储保持断开状态，但之后必须先重新连接，才能在密钥存储中创建新的 KMS 密钥或在密钥存储中使用现有 KMS 密钥来进行加密操作。
**注意**
如果您使用 AWS CLI 版本 1.0，请在指定带有 HTTP 或 HTTPS 值的参数（例如`XksProxyUriEndpoint`参数）之前运行以下命令。
```
aws configure set cli_follow_urlparam false
```
否则， AWS CLI 版本 1.0 会将参数值替换为在该 URI 地址中找到的内容，从而导致以下错误：
```
Error parsing parameter '--xks-proxy-uri-endpoint': Unable to retrieve
https:// : received non 200 status code of 404
```
#### 更改外部密钥存储的名称
第一个示例使用[UpdateCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_UpdateCustomKeyStore.html)操作将外部密钥存储库的友好名称更改为`XksKeyStore`。该命令使用 `CustomKeyStoreId` 参数标识自定义密钥存储，使用 `CustomKeyStoreName` 指定自定义密钥存储的新名称。将所有示例值替换为外部密钥存储的实际值。
```
$ aws kms update-custom-key-store --custom-key-store-id cks-1234567890abcdef0 --new-custom-key-store-name XksKeyStore
```
#### 更改代理身份验证凭证
以下示例更新了 AWS KMS 用于向外部密钥存储代理进行身份验证的代理身份验证凭证。如果凭证在代理上轮换，您可以使用这样的命令来更新凭证。
首先更新外部密钥存储代理上的凭证。然后使用此功能将更改报告给 AWS KMS。（您的代理将暂时支持新旧凭证，因此您有时间在中 AWS KMS更新凭证。）
您必须始终在凭证中同时指定访问密钥 ID 和秘密访问密钥，即使只更改了一个值也是如此。
前两个命令设置变量来保存凭证值。`UpdateCustomKeyStore` 操作使用 `CustomKeyStoreId` 参数来标识外部密钥存储。该操作使用 `XksProxyAuthenticationCredential` 参数及其 `AccessKeyId` 和 `RawSecretAccessKey` 字段来指定新凭证。将所有示例值替换为外部密钥存储的实际值。
```
$ accessKeyID=access key id
$ secretAccessKey=secret access key
$ aws kms update-custom-key-store --custom-key-store-id cks-1234567890abcdef0 \
--xks-proxy-authentication-credential \
AccessKeyId=$accessKeyId,RawSecretAccessKey=$secretAccessKey
```
#### 更改代理 URI 路径
以下示例更新了代理 URI 路径（`XksProxyUriPath`）。在和区域中，代理 URI 端点和代理 URI 路径的 AWS 账户 组合必须是唯一的。将所有示例值替换为外部密钥存储的实际值。
```
$ aws kms update-custom-key-store --custom-key-store-id cks-1234567890abcdef0 \
--xks-proxy-uri-path /kms/xks/v1
```
#### 更改 VPC 端点服务连接
以下示例使用[UpdateCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_UpdateCustomKeyStore.html)操作将外部密钥存储代理连接类型更改为`VPC_ENDPOINT_SERVICE`。要进行此更改，您必须指定 VPC 端点服务连接所需的值，包括 VPC 端点服务名称（`XksProxyVpcEndpointServiceName`）和包含 VPC 端点服务的私有 DNS 名称的代理 URI 端点（`XksProxyUriEndpoint`）值。将所有示例值替换为外部密钥存储的实际值。
```
$ aws kms update-custom-key-store --custom-key-store-id cks-1234567890abcdef0 \
--xks-proxy-connectivity "VPC_ENDPOINT_SERVICE" \
--xks-proxy-uri-endpoint https://myproxy-private.xks.example.com \
--xks-proxy-vpc-endpoint-service-name com.amazonaws.vpce.us-east-1.vpce-svc-example
```
#### 更改为公有端点连接
以下示例将外部密钥存储代理连接类型更改为 `PUBLIC_ENDPOINT`。进行此更改时，必须更新代理 URI 端点（`XksProxyUriEndpoint`）值。将所有示例值替换为外部密钥存储的实际值。
**注意**
VPC 端点连接提供的安全性高于公有端点连接。在更改为公有端点连接之前，请考虑其他选项，包括在本地找到外部密钥存储代理以及仅使用 VPC 进行通信。
```
$ aws kms update-custom-key-store --custom-key-store-id cks-1234567890abcdef0 \
--xks-proxy-connectivity "PUBLIC_ENDPOINT" \
--xks-proxy-uri-endpoint https://myproxy.xks.example.com
```
# 查看外部密钥存储
您可以使用 AWS KMS 控制台或使用[DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html)操作来查看每个账户和区域中的外部密钥存储库。
查看外部密钥存储时，可以看到以下内容：
+ 有关密钥存储的基本信息，包括其易记名称、ID、密钥存储类型和创建日期。
+ [外部密钥存储代理](keystore-external.md#concept-xks-proxy)的配置信息，包括[连接类型](keystore-external.md#concept-xks-connectivity)、[代理 URI 端点](create-xks-keystore.md#require-endpoint)和[路径](create-xks-keystore.md#require-path)，以及当前[代理身份验证凭证](keystore-external.md#concept-xks-credential)的[访问密钥 ID](keystore-external.md#concept-xks-credential)。
+ 如果外部密钥存储代理使用 [VPC 端点服务连接](choose-xks-connectivity.md#xks-vpc-connectivity)，则控制台将显示 VPC 端点服务的名称。
+ 当前[连接状态](xks-connect-disconnect.md#xks-connection-state)。
**注意**
如果连接状态值为 **Disconnected**（已断开连接），则表示外部密钥存储从未连接过，或者已有意与其外部密钥存储代理断开连接。但是，如果您尝试使用已连接的外部密钥存储中的 KMS 密钥时失败，则可能表示该外部密钥存储或其代理存在问题。有关帮助信息，请参阅 [外部密钥存储连接错误](xks-troubleshooting.md#fix-xks-connection)。
+ 带有 [Amazon CloudWatch 指标](monitoring-cloudwatch.md#kms-metrics)图表的 “[监控](xks-monitoring.md)” 部分，旨在帮助您检测和解决外部密钥存储的问题。有关解释图表、在规划和故障排除中使用图表以及根据图表中的指标创建 CloudWatch 警报的帮助，请参阅[监控外部密钥存储](xks-monitoring.md)。
## 外部密钥存储属性
外部密钥库的以下属性在 AWS KMS 控制台和[DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html)响应中可见。
### 自定义密钥存储属性
以下值显示在每个自定义密钥库详情页面的 “**常规配置**” 部分。这些属性适用于所有自定义密钥存储库，包括密钥存储库和外部 AWS CloudHSM 密钥存储库。
**自定义密钥存储 ID**
AWS KMS 分配给自定义密钥库的唯一 ID。
**自定义密钥存储名称**
在创建自定义密钥存储时为其分配的易记名称。您可以随时更改此值。
**自定义密钥存储类型**
自定义密钥存储的类型。有效值为 AWS CloudHSM （`AWS_CLOUDHSM`）或外部密钥存储（`EXTERNAL_KEY_STORE`）。创建自定义密钥存储后无法更改其类型。
**创建日期**
创建自定义密钥存储的日期。此日期显示为 AWS 区域的本地时间。
**连接状态**
表示自定义密钥存储已连接到其备用密钥存储。仅当自定义密钥存储从未连接到其备用密钥存储或故意断开连接时，连接状态才会为 `DISCONNECTED`。有关更多信息，请参阅 [连接状态](xks-connect-disconnect.md#xks-connection-state)。
### 外部密钥存储配置属性
以下值显示在每个**外部密钥存储详细信息页面的外部密钥存储代理配置**部分和[DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html)响应`XksProxyConfiguration`元素中。有关每个字段的详细描述，包括唯一性要求，以及有关帮助确定每个字段的正确值的详细描述，请参阅 *Creating an external key store*（创建外部密钥存储）主题中的 [汇编先决条件](create-xks-keystore.md#xks-requirements)。
**代理连接**
指示外部密钥存储是使用[公有端点连接](choose-xks-connectivity.md#xks-connectivity-public-endpoint)还是 [VPC 端点服务连接](choose-xks-connectivity.md#xks-vpc-connectivity)。
**代理 URI 端点**
AWS KMS 用于连接到您的[外部密钥存储代理](keystore-external.md#concept-xks-proxy)的端点。
**代理 URI 路径**
从 AWS KMS 发送代理 [API 请求](keystore-external.md#concept-proxy-apis)的代理 URI 端点的路径。
**代理凭证：访问密钥 ID**
您在外部密钥存储代理上建立的[代理身份验证凭证](keystore-external.md#concept-xks-credential)的一部分。访问密钥 ID 标识出凭证中的秘密访问密钥。
AWS KMS 使用 Sigv4 签名过程和代理身份验证凭据来签署其对外部密钥存储代理的请求。签名中的凭据允许外部密钥存储代理代表您对来自 AWS KMS的请求进行身份验证。
**VPC 端点服务名称**
支持您的外部密钥存储的 Amazon VPC 端点服务的名称。此值仅在外部密钥存储使用 [VPC 端点服务连接](choose-xks-connectivity.md#xks-vpc-connectivity)时显示。您可以在 VPC 中找到您的外部密钥存储代理，也可以使用 VPC 端点服务与您的外部密钥存储代理安全地进行通信。
**VPC 端点服务所有者 ID**
支持您的外部密钥存储的 Amazon VPC 端点服务 ID。此值仅在外部密钥存储使用 [VPC 端点服务连接](choose-xks-connectivity.md#xks-vpc-connectivity)时显示。您可以在 VPC 中找到您的外部密钥存储代理，也可以使用 VPC 端点服务与您的外部密钥存储代理安全地进行通信。
## 查看您的外部密钥存储属性
您可以在 AWS KMS 控制台中或使用[DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html)操作来查看您的外部密钥存储库及其关联属性。
### 使用控制 AWS KMS 台
要查看给定账户和区域中的外部密钥存储，请按照以下流程操作。
1. 登录 AWS 管理控制台 并在 [https://console.aws.amazon.com/km](https://console.aws.amazon.com/kms) s 处打开 AWS Key Management Service (AWS KMS) 控制台。
1. 要更改 AWS 区域，请使用页面右上角的区域选择器。
1. 在导航窗格中，选择 **Custom key stores**（自定义密钥存储）、**External key stores**（外部密钥存储）。
1. 要查看有关外部密钥存储的详细信息，请选择密钥存储名称。
### 使用 AWS KMS API
要查看您的外部密钥存储库，请使用[DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html)操作。默认情况下，此操作将返回账户和区域中的所有自定义密钥存储。不过，您可以使用 `CustomKeyStoreId` 或 `CustomKeyStoreName` 参数（但不能同时使用两者）将输出限制到特定的自定义密钥存储。
对于自定义密钥存储，输出包含自定义密钥存储 ID、名称和类型以及密钥存储的[连接状态](xks-connect-disconnect.md#xks-connection-state)。如果连接状态为 `FAILED`，则输出还包含描述错误原因的 `ConnectionErrorCode`。有关解释外部密钥存储 `ConnectionErrorCode` 的帮助，请参阅 [外部密钥存储的连接错误代码](xks-troubleshooting.md#xks-connection-error-codes)。
对于外部密钥存储，输出还包括 `XksProxyConfiguration` 元素。此元素包括[连接类型](create-xks-keystore.md#require-connectivity)、[代理 URI 端点](create-xks-keystore.md#require-endpoint)、[代理 URI 路径](create-xks-keystore.md#require-path)和[代理身份验证凭证](keystore-external.md#concept-xks-credential)的访问密钥 ID。
本部分中的示例使用 [AWS Command Line Interface (AWS CLI)](https://aws.amazon.com/cli/)，但您可以使用任何受支持的编程语言。
例如，以下命令返回账户和区域中的所有自定义密钥存储。您可以使用 `Limit` 和 `Marker` 参数来浏览输出中的自定义密钥存储。
```
$ aws kms describe-custom-key-stores
```
以下示例命令使用 `CustomKeyStoreName` 参数以仅获取具有 `ExampleXksPublic` 易记名称的示例外部密钥存储。此示例密钥存储使用公有端点连接。该密钥存储连接到其外部密钥存储代理。
```
$ aws kms describe-custom-key-stores --custom-key-store-name ExampleXksPublic
{
"CustomKeyStores": [
{
"CustomKeyStoreId": "cks-1234567890abcdef0",
"CustomKeyStoreName": "ExampleXksPublic",
"ConnectionState": "CONNECTED",
"CreationDate": "2022-12-14T20:17:36.419000+00:00",
"CustomKeyStoreType": "EXTERNAL_KEY_STORE",
"XksProxyConfiguration": {
"AccessKeyId": "ABCDE12345670EXAMPLE",
"Connectivity": "PUBLIC_ENDPOINT",
"UriEndpoint": "https://xks.example.com:6443",
"UriPath": "/example/prefix/kms/xks/v1"
}
}
]
}
```
以下命令获取具有 VPC 端点服务连接的示例外部密钥存储。在此示例中，外部密钥存储连接到其外部密钥存储代理。
```
$ 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"
}
}
]
}
```
[`ConnectionState`](xks-connect-disconnect.md#xks-connection-state) 为 `Disconnected` 则表示外部密钥存储从未连接过，或者已有意与其与外部密钥存储代理断开连接。但是，如果您尝试使用已连接的外部密钥存储中的 KMS 密钥时失败，则可能表示该外部密钥存储代理或其他外部组件存在问题。
如果外部密钥存储的 `ConnectionState` 为 `FAILED`，则 `DescribeCustomKeyStores` 响应包含说明错误原因的 `ConnectionErrorCode` 元素。
例如，在以下输出中，该`XKS_PROXY_TIMED_OUT`值表示 AWS KMS 可以连接到外部密钥存储代理，但是由于外部密钥存储代理 AWS KMS 在分配的时间内没有响应，连接失败了。如果您反复看到此连接错误代码，请通知您的外部密钥存储代理供应商。有关此连接失败及其他连接错误失败的帮助，请参阅[排查外部密钥存储的问题](xks-troubleshooting.md)。
```
$ aws kms describe-custom-key-stores --custom-key-store-name ExampleXksVpc
{
"CustomKeyStores": [
{
"CustomKeyStoreId": "cks-9876543210fedcba9",
"CustomKeyStoreName": "ExampleXksVpc",
"ConnectionState": "FAILED",
"ConnectionErrorCode": "XKS_PROXY_TIMED_OUT",
"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"
}
}
]
}
```
# 监控外部密钥存储
AWS KMS 收集与外部密钥存储库的每次交互的指标，并将其发布到您的 CloudWatch 账户中。这些指标用于在每个外部密钥存储的详细信息页面的监控部分生成图表。以下主题详细介绍了如何使用图表来识别和排查影响外部密钥存储的操作和配置问题。我们建议使用这些 CloudWatch 指标来设置警报，以便在外部密钥存储未按预期运行时通知您。有关更多信息，请参阅[使用 Amazon 进行监控 CloudWatch](monitoring-cloudwatch.md)。
**Topics**
+ [
## 查看图表
](#xks-monitoring-navigate)
+ [
## 解释图表
](#interpreting-graphs)
## 查看图表
您可以在不同的详细程度下查看图表。默认情况下，每个图表使用三小时的时间范围和五分钟的汇总[期](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_concepts.html#CloudWatchPeriods)。您可以在控制台中调整图表视图，但是当关闭外部密钥存储的详细信息页面或刷新浏览器时，您的更改将恢复为默认设置。有关亚马逊 CloudWatch 术语的帮助，请参阅[亚马逊 CloudWatch 概念](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_concepts.html)。
### 查看数据点详细信息
每个图表中的数据通过 [AWS KMS 指标](https://docs.aws.amazon.com/kms/latest/developerguide/monitoring-cloudwatch.html#kms-metrics)收集。若要查看有关特定数据点的更多信息，请将鼠标悬停在折线图上的数据点上方。这将显示一个弹出窗口，其中包含有关派生该图表的指标的更多信息。每个列表项都显示记录在该数据点的[维度](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_concepts.html#Dimension)值。如果该数据点的维度值没有可用的指标数据，则弹出窗口将显示空值（**–**）。有些图表记录了单个数据点的多个维度和值。其他图表，例如[可靠性图表](#reliability-graph)，使用指标收集的数据来计算唯一值。每个列表项均与不同的折线图颜色关联。
### 修改时间范围
若要修改[时间范围](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/modify_graph_date_time.html)，请在监控部分的右上角选择一个预定义的时间范围。预定义的时间范围从 1 小时到 1 周（**1 小时**、**3 小时**、**12 小时**、**1 天**、**3 天**或者 **1 周**）。这将调整所有图表的时间范围。如果您想查看不同时间范围内的特定图表，或者想要设置自定义时间范围，请放大图表或在 Amazon CloudWatch 控制台中查看。
### 放大图表
您可以使用[缩微贴图缩放功能](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/zoom-graph.html)来重点查看折线图和图表的堆叠部分，而无需在放大和缩小视图之间进行切换。例如，您可以使用缩微贴图缩放功能来重点查看折线图中的峰值，以便将该峰值与同一时间线的监控部分中的其他图表进行比较。
1. 选择并拖动要突出的图表区域，然后释放拖动对象。
1. 要重置缩放，选择 **Reset zoom**（重置缩放）图标，该图标看起来像放大镜里面包含减号 (-) 符号。
### 放大图表
若要放大图表，请选择单个图表右上角的菜单图标，然后选择 **Enlarge**（放大）。将鼠标悬停在图表上方时，也可以选择菜单图标旁边显示的放大图标。
放大图表可让您通过指定不同的时间段、自定义时间范围或刷新间隔来进一步修改图表的视图。关闭放大视图时，这些更改将恢复为默认设置。
修改时间段
1. 选择 **Period options**（时间段选项）菜单。默认情况下，此菜单显示的值为：**5 minutes**（5 分钟）。
1. 选择一个时间段，预定义的时间段从 1 秒到 30 天不等。
例如，您可以选择一分钟视图，这在您排查问题时会非常有用。或者，选择不太详细的一小时视图。这在您查看更大的时间范围（例如 3 天）来了解一段时间内的趋势时会很有用。有关更多信息，请参阅 *Amazon CloudWatch 用户指南*中的[周期](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_concepts.html#CloudWatchPeriods)。
修改时间范围或时区
1. 选择一个预定义的时间范围，此范围的跨度从 1 小时到 1 周（**1 小时**、**3 小时**、**12 小时**、**1 天**、**3 天**或 **1 周**）。或者，您也可以选择 **Custom**（自定义）来设置自己的时间范围。
1. 选择 **Custom**（自定义）。
1. *时间范围*：选择方框左上角的 **Absolute**（绝对）选项卡。使用日历选取器或文本字段框指定时间范围。
1. *时区*：选择方框右上角的下拉菜单。您可以将时区更改为 **UTC**（协调世界时）或 **Local time zone**（本地时区）。
1. 在指定时间范围后，选择 **Apply**（应用）。
修改图表中数据的刷新频率
1. 选择右上角的 **Refresh options**（刷新选项）菜单。
1. 选择刷新间隔（**关闭**、**10 秒**、**1 分钟**、**2 分钟**、**5 分钟**或 **15 分钟**）。
### 在 Amazon CloudWatch 控制台中查看图表
监控部分中的图表来自 AWS KMS 发布到 Amazon 的预定义指标 CloudWatch。你可以在 CloudWatch 控制台中打开它们并将其保存到 CloudWatch 仪表板中。如果您有多个外部密钥存储库，则可以在中 CloudWatch 打开它们各自的图表，并将它们保存到单个仪表板中，以比较它们的运行状况和使用情况。
**添加到 CloudWatch 控制面板**
选择右上角的 “**添加到控制面板**”，将所有图表添加到 Amazon CloudWatch 控制面板。您可以选择现有的控制面板或创建一个新控制面板。有关使用此控制面板创建图表和警报的自定义视图的信息，请参阅《亚马逊* CloudWatch 用户指南》中的 “使用亚马逊 CloudWatch*[控制面板](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html)”。
**在 CloudWatch 指标中查看**
选择单个图表右上角的菜单图标，然后选择**在指标中查看，即可在** Amazon CloudWatch 控制台中查看此图表。在 CloudWatch 控制台中，您可以将此单个图表添加到仪表板并修改时间范围、周期和刷新间隔。有关更多信息，请参阅《*Amazon CloudWatch 用户指南》*中的 “[绘制指标](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/graph_metrics.html)”。
## 解释图表
AWS KMS 提供了多个图表，用于在 AWS KMS 控制台中监控外部密钥存储的运行状况。这些图表为自动配置，派生自 [AWS KMS 指标](https://docs.aws.amazon.com/kms/latest/developerguide/monitoring-cloudwatch.html#kms-metrics)。
图形数据作为您对外部密钥存储和外部密钥进行的调用的一部分收集。在您没有进行任何调用的时间范围内，您可能会看到数据填充图表，这些 AWS KMS 数据来自代表您定期`GetHealthStatus`调用以检查外部密钥存储代理和外部密钥管理器的状态。如果您的图表显示 **No data available**（无可用数据）消息，则表示在该时间范围内没有记录任何调用，或者您的外部密钥存储处于 [`DISCONNECTED`](xks-connect-disconnect.md#xks-connection-state) 状态。您可以通过[将视图调整到](#graph-time-range)更大的时间范围来确定外部密钥存储断开连接的时间。
**Topics**
+ [
### 请求总数
](#total-requests-graph)
+ [
### 可靠性
](#reliability-graph)
+ [
### 延迟
](#latency-graph)
+ [
### 前 5 个异常
](#top-5-exceptions-graph)
+ [
### 证书过期天数
](#cert-expire-graph)
### 请求总数
在给定时间范围内收到的针对特定外部密钥存储的 AWS KMS 请求总数。使用此图表来确定您是否面临节流的风险。
AWS KMS 建议您的外部密钥管理器每秒能够处理多达 1800 个加密操作请求。如果您在五分钟内接通 540000 个电话，则有节流的风险。
您可以监控外部密钥存储库中对 KMS 密钥进行加密操作的请求数量，这些请求会随该指标进行 AWS KMS 限制。[ExternalKeyStoreThrottle](monitoring-cloudwatch.md#metric-throttling)
如果您经常收到 `KMSInvalidStateException` 错误，其中包含一条说明请求“due to a very high request rate”（由于请求率很高）而被拒绝的消息，则可能表明您的外部密钥管理器或外部密钥存储代理无法跟上当前的请求速率。如可能，请降低您的请求速率。您也可以考虑请求降低自定义密钥存储请求限额值。减少此配额值可能会增加限制，但这表明 AWS KMS 在将多余的请求发送到您的外部密钥存储代理或外部密钥管理器之前，会迅速拒绝这些请求。要申请下调限额，请访问 [AWS 支持 中心](https://console.aws.amazon.com/support/home) 并创建工单。
总请求数图表派生自 [XksProxyErrors](monitoring-cloudwatch.md#metric-xks-proxy-errors) 指标，该指标收集有关 AWS KMS 从外部密钥存储代理收到的成功和失败响应的数据。当您[查看特定数据点](#graph-data-point)时，弹出窗口会显示该`CustomKeyStoreId`维度的值以及在该数据点记录的 AWS KMS 请求总数。`CustomKeyStoreId` 将始终相同。
### 可靠性
外部密钥存储代理返回成功响应或不可重试错误的 AWS KMS 请求的百分比。使用此图表评估外部密钥存储代理的运行状况。
当图表显示的值小于 100% 时，该值表示代理没有响应，或者响应了可重试错误。这可能表明网络存在问题、外部密钥存储代理或外部密钥管理器速度缓慢或实施错误。
如果请求包含错误的凭证，且代理响应了 `AuthenticationFailedException`，则该图仍将显示 100% 的可靠性，因为代理在[外部密钥存储代理 API 请求](keystore-external.md#concept-proxy-apis)中识别出了错误的值，因此预计会出现故障。如果可靠性图表的百分比为 100%，则您的外部密钥存储代理将按预期进行响应。如果图表显示的值小于 100%，则代理会响应可重试错误或超时。例如，如果代理由于请求速率过高而响应了 `ThrottlingException`，则图表将显示较低的可靠性百分比，因为代理无法识别请求中导致其失败的特定问题。这是因为可重试错误可能是临时性问题，可以通过重试请求解决。
以下错误响应将降低可靠性百分比。您可以使用 [前 5 个异常](#top-5-exceptions-graph) 图表和 [XksProxyErrors](monitoring-cloudwatch.md#metric-xks-proxy-errors) 指标进一步监控代理返回每个可重试错误的频率。
+ `InternalException`
+ `DependencyTimeoutException`
+ `ThrottlingException`
+ `XksProxyUnreachableException`
可靠性图表源自该[XksProxyErrors](monitoring-cloudwatch.md#metric-xks-proxy-errors)指标，该指标收集有关从您的外部密钥存储代理 AWS KMS 收到的成功和失败响应的数据。只有当响应的 `ErrorType` 值为 `Retryable` 时，可靠性百分比才会降低。当您[查看特定数据点](#graph-data-point)时，弹出窗口会显示该`CustomKeyStoreId`维度的值以及在该数据点记录的 AWS KMS 请求的可靠性百分比。`CustomKeyStoreId` 将始终相同。
我们建议使用该[XksProxyErrors](monitoring-cloudwatch.md#metric-xks-proxy-errors)指标创建 CloudWatch 警报，通过在一分钟内记录超过五个可重试错误时提醒您潜在的网络问题。有关更多信息，请参阅 [创建可重试错误警报](xks-alarms.md#retryable-errors-alarm)。
### 延迟
外部密钥存储代理响应请求所需的毫秒数。 AWS KMS 使用此图表来评估您的外部密钥存储代理和外部密钥管理器的性能。
AWS KMS 期望外部密钥存储代理在 250 毫秒内对每个请求做出响应。如果网络超时， AWS KMS 将重试请求一次。如果代理再次失败，则记录的延迟是两次请求尝试的合计超时限制，图表将显示大约 500 毫秒。在代理未在 250 毫秒超时限制内响应的所有其他情况下，记录的延迟为 250 毫秒。如果代理在加密和解密操作时经常超时，请咨询您的外部代理管理员。有关解决延迟问题的帮助，请参阅 [延迟和超时错误](xks-troubleshooting.md#fix-xks-latency)。
响应缓慢还可能表示您的外部密钥管理器无法处理当前的请求流量。 AWS KMS 建议您的外部密钥管理器每秒能够处理多达 1800 个加密操作请求。如果您的外部密钥管理器无法处理每秒 1800 个请求的速率，请考虑请求降低[自定义密钥存储中 KMS 密钥的请求限额](requests-per-second.md#rps-key-stores)。使用外部密钥存储中的 KMS 密钥进行加密操作的请求将采用快速失效机制，并出现[节流异常](throttling.md)，而不是由外部密钥存储代理或外部密钥管理器处理后拒绝。
延迟图表派生自 [XksProxyLatency](monitoring-cloudwatch.md#metric-xks-proxy-latency) 指标。当您[查看特定数据点](#graph-data-point)时，弹出窗口会显示相应的 `KmsOperation` 和 `XksOperation` 维度的值以及该数据点的操作记录的平均延迟。列表项按从最高延迟到最低延迟的顺序排列。
我们建议使用该[XksProxyLatency](monitoring-cloudwatch.md#metric-xks-proxy-latency)指标创建 CloudWatch 警报，以便在延迟接近超时限制时通知您。有关更多信息，请参阅 [创建响应超时警报](xks-alarms.md#latency-alarm)。
### 前 5 个异常
在给定时间范围内失败的加密和管理操作的前五个异常。使用此图表跟踪最常见的错误，因此您可以确定工程工作的优先顺序。
此计数包括从外部密钥存储代理 AWS KMS 收到的异常`XksProxyUnreachableException`，以及当外部密钥存储代理无法与外部密钥存储代理建立通信时在内部 AWS KMS 返回的异常。
可重试错误率高可能表示网络错误，而不可重试错误率高可能表示外部密钥存储的配置存在问题。例如，峰值`AuthenticationFailedExceptions`表示中配置的身份验证凭据与外部密钥存储代理之间存在差异。 AWS KMS 若要查看您的外部密钥存储配置，请参阅 [查看外部密钥存储](view-xks-keystore.md)。若要编辑您的外部密钥存储设置，请参阅 [编辑外部密钥存储属性](update-xks-keystore.md)。
从外部密钥存储代理 AWS KMS 收到的异常与操作失败时 AWS KMS 返回的异常不同。 AWS KMS `KMSInvalidStateException`对于所有与外部密钥存储库的外部配置或连接状态相关的故障，加密操作都会返回。若要确定问题，请使用随附的错误消息文本。
下表显示了可能出现在前 5 个异常图表中的异常以及 AWS KMS 返回给您的相应异常。
| 错误类型 | 图表中显示的异常 | AWS KMS 返回给你的异常 |
| --- | --- | --- |
| 不可重试 | AccessDeniedException 有关问题排查帮助，请参阅[代理授权问题](xks-troubleshooting.md#fix-xks-authorization)。 | **`CustomKeyStoreInvalidStateException`** 响应 `CreateKey` 操作。 **`KMSInvalidStateException`** 响应加密操作。 |
| 不可重试 | AuthenticationFailedException 有关问题排查帮助，请参阅[身份验证凭证错误](xks-troubleshooting.md#fix-xks-credentials)。 | **`XksProxyIncorrectAuthenticationCredentialException`** 响应 `CreateCustomKeyStore` 和 `UpdateCustomKeyStore` 操作。**`CustomKeyStoreInvalidStateException`** 响应 `CreateKey` 操作。 **`KMSInvalidStateException`** 响应加密操作。 |
| 可重试 | **`DependencyTimeoutException`** 有关问题排查帮助，请参阅[延迟和超时错误](xks-troubleshooting.md#fix-xks-latency)。 | **`XksProxyUriUnreachableException`** 响应 `CreateCustomKeyStore` 和 `UpdateCustomKeyStore` 操作。 **`CustomKeyStoreInvalidStateException`** 响应 `CreateKey` 操作。 **`KMSInvalidStateException`** 响应加密操作。 |
| 可重试 | **`InternalException`** 外部密钥库代理拒绝了该请求，因为该请求无法与外部密钥管理器通信。验证外部密钥存储代理配置是否正确以及外部密钥管理器是否可用。 | **`XksProxyInvalidResponseException`** 响应 `CreateCustomKeyStore` 和 `UpdateCustomKeyStore` 操作。 **`CustomKeyStoreInvalidStateException`** 响应 `CreateKey` 操作。 **`KMSInvalidStateException`** 响应加密操作。 |
| 不可重试 | **`InvalidCiphertextException`** 有关问题排查帮助，请参阅[解密错误](xks-troubleshooting.md#fix-xks-decrypt)。 | **`KMSInvalidStateException`** 响应加密操作。 |
| 不可重试 | **`InvalidKeyUsageException`** 有关问题排查帮助，请参阅[外部密钥的加密操作错误](xks-troubleshooting.md#fix-external-key-crypto)。 | **`XksKeyInvalidConfigurationException`** 响应 `CreateKey` 操作。 **`KMSInvalidStateException`** 响应加密操作。 |
| 不可重试 | **`InvalidStateException`** 有关问题排查帮助，请参阅[外部密钥的加密操作错误](xks-troubleshooting.md#fix-external-key-crypto)。 | **`XksKeyInvalidConfigurationException`** 响应 `CreateKey` 操作。 **`KMSInvalidStateException`** 响应加密操作。 |
| 不可重试 | **`InvalidUriPathException`** 有关问题排查帮助，请参阅[常规配置错误](xks-troubleshooting.md#fix-xks-gen-configuration)。 | **`XksProxyInvalidConfigurationException`** 响应 `CreateCustomKeyStore` 和 `UpdateCustomKeyStore` 操作。 **`CustomKeyStoreInvalidStateException`** 响应 `CreateKey` 操作。 **`KMSInvalidStateException`** 响应加密操作。 |
| 不可重试 | **`KeyNotFoundException`** 有关问题排查帮助，请参阅[外部密钥错误](xks-troubleshooting.md#fix-external-key)。 | **`XksKeyNotFoundException`** 响应 `CreateKey` 操作。 **`KMSInvalidStateException`** 响应加密操作。 |
| 可重试 | **`ThrottlingException`** 由于请求速率过高，外部密钥存储代理拒绝了该请求。使用外部密钥存储中的 KMS 密钥降低调用频率。 | **`XksProxyUriUnreachableException`** 响应 `CreateCustomKeyStore` 和 `UpdateCustomKeyStore` 操作。 **`CustomKeyStoreInvalidStateException`** 响应 `CreateKey` 操作。 **`KMSInvalidStateException`** 响应加密操作。 |
| 不可重试 | **`UnsupportedOperationException`** 有关问题排查帮助，请参阅[外部密钥的加密操作错误](xks-troubleshooting.md#fix-external-key-crypto)。 | **`XksKeyInvalidResponseException`** 响应 `CreateKey` 操作。 **`KMSInvalidStateException`** 响应加密操作。 |
| 不可重试 | **`ValidationException`** 有关问题排查帮助，请参阅[代理问题](xks-troubleshooting.md#fix-xks-proxy)。 | **`XksProxyInvalidResponseException`** 响应 `CreateCustomKeyStore` 和 `UpdateCustomKeyStore` 操作。 **`CustomKeyStoreInvalidStateException`** 响应 `CreateKey` 操作。 **`KMSInvalidStateException`** 响应加密操作。 |
| 可重试 | **`XksProxyUnreachableException`** 如果您反复看到此错误，请验证您的外部密钥存储代理是否处于活动状态并已连接到网络，以及其在外部密钥存储中的 URI 路径和端点 URI 或 VPC 服务名称是否正确。 | **`XksProxyUriUnreachableException`** 响应 `CreateCustomKeyStore` 和 `UpdateCustomKeyStore` 操作。 **`CustomKeyStoreInvalidStateException`** 响应 `CreateKey` 操作。 **`KMSInvalidStateException`** 响应加密操作。 |
前 5 个异常图表派生自 [XksProxyErrors](monitoring-cloudwatch.md#metric-xks-proxy-errors) 指标。当您[查看特定数据点](#graph-data-point)时，弹出窗口会显示 `ExceptionName` 维度的值以及在该数据点记录的异常的次数。五个列表项按最常见的异常到最少见的异常顺序排列。
我们建议使用该[XksProxyErrors](monitoring-cloudwatch.md#metric-xks-proxy-errors)指标创建 CloudWatch 警报，通过在一分钟内记录超过五个不可重试的错误时提醒您潜在的配置问题。有关更多信息，请参阅 [创建不可重试错误警报](xks-alarms.md#nonretryable-errors-alarm)。
### 证书过期天数
距离您的外部密钥存储代理端点（`XksProxyUriEndpoint`）的 TLS 证书过期的天数。使用此图表监控即将过期的 TLS 证书。
证书过期后， AWS KMS 无法与外部密钥存储代理通信。在您续订证书之前，外部密钥存储中所有受 KMS 密钥保护的数据都将不可访问。
距离证书过期的天数图表派生自 [XksProxyCertificateDaysToExpire](monitoring-cloudwatch.md#metric-xks-proxy-certificate-days-to-expire) 指标。我们强烈建议您使用此指标来创建 CloudWatch 警报，通知您即将到期。证书过期可能会影响您访问加密资源。设置警报，让您的组织有时间在证书过期之前续订证书。有关更多信息，请参阅 [创建证书到期警报](xks-alarms.md#cert-expire-alarm)。
# 连接和断开外部密钥存储
新外部密钥存储未连接。要在外部密钥存储库 AWS KMS keys 中创建和使用，您需要将外部密钥存储库连接到其[外部密钥存储代理服务器](keystore-external.md#concept-xks-proxy)。您可以随时连接和断开外部密钥存储，并[查看其连接状态](view-xks-keystore.md)。
当您的外部密钥存储断开连接时， AWS KMS 无法与您的外部密钥存储代理进行通信。因此，您可以查看和管理外部密钥存储及其现有 KMS 密钥。不过，您不能在外部密钥存储中创建 KMS 密钥，也不能在加密操作中使用其 KMS 密钥。您可能需要在某些时候断开外部密钥存储的连接，例如编辑外部密钥存储的属性时，但要进行相应计划。断开密钥存储库的连接可能会中断使用其 KMS 密钥的 AWS 服务的运行。
您无需连接外部密钥存储。您可以将外部密钥存储保持在无限期断开的状态并且仅在您需要使用它时进行连接。但是，您可能希望定期测试连接以验证设置是否正确以及自定义密钥存储是否可以连接。
当您断开自定义密钥存储时，密钥存储中的 KMS 密钥立即变得不可用（视最终一致性而定）。不过，在再次使用 KMS 密钥（例如解密数据密钥）之前，使用受 KMS 密钥保护的[数据密钥](data-keys.md)加密的资源不会受到影响。此问题会影响 AWS 服务，因为许多服务使用数据密钥来保护您的资源。有关更多信息，请参阅 [不可用的 KMS 密钥如何影响数据密钥](unusable-kms-keys.md)。
**注意**
仅当密钥存储从未连接或您明确断开密钥存储连接时，外部密钥存储才会具有 `DISCONNECTED` 状态。`CONNECTED` 状态并不表示外部密钥存储或其支持组件正在高效运行。有关外部密钥存储组件性能的信息，请参阅每个外部密钥存储详细信息页面 **Monitoring**（监控）部分中的图表。有关更多信息，请参阅 [监控外部密钥存储](xks-monitoring.md)。
您的外部密钥管理器可能会提供其他方法来停止和重新启动 AWS KMS 外部密钥存储与外部密钥存储代理之间或外部密钥存储代理与外部密钥管理器之间的通信。有关详细信息，请参阅外部密钥管理器的文档。
**Topics**
+ [
## 连接状态
](#xks-connection-state)
+ [
# 连接外部密钥存储
](about-xks-connecting.md)
+ [
# 断开外部密钥存储
](about-xks-disconnecting.md)
## 连接状态
连接和断开会改变自定义密钥存储的*连接状态*。 AWS CloudHSM 密钥存储库和外部密钥存储库的连接状态值相同。
要查看自定义密钥库的连接状态，请使用[DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/DescribeCustomKeyStores.html)操作或 AWS KMS 控制台。**连接状态**显示在每个自定义密钥存储表中、每个自定义密钥存储详细信息页面的 **General configuration**（常规配置）部分中，以及自定义密钥存储中 KMS 密钥 **Cryptographic configuration**（加密配置）选项卡上。有关详细信息，请参阅 [查看密 AWS CloudHSM 钥库](view-keystore.md) 和 [查看外部密钥存储](view-xks-keystore.md)。
自定义密钥存储可能具有以下连接状态之一：
+ `CONNECTED`：自定义密钥存储已连接到其备用密钥存储。您可以在自定义密钥存储中创建和使用 KMS 密钥。
*密钥库的备*用 AWS CloudHSM 密钥存储区是其关联的 AWS CloudHSM 集群。外部密钥存储的*备用密钥存储*是外部密钥存储代理及其支持的外部密钥管理器。
CONNECTED（已连接）状态表示连接成功且自定义密钥存储未被故意断开。但该状态并不表示连接运行正常。有关与您的 AWS CloudHSM 密钥库关联的 AWS CloudHSM 集群状态的信息，请参阅 AWS CloudHSM 用户指南 AWS CloudHSM中的[获取 CloudWatch 指标](https://docs.aws.amazon.com/cloudhsm/latest/userguide/hsm-metrics-cw.html)。有关外部密钥存储的状态和操作的信息，请参阅每个外部密钥存储详细信息页面 **Monitoring**（监控）部分的图表。有关更多信息，请参阅 [监控外部密钥存储](xks-monitoring.md)。
+ `CONNECTING`：连接自定义密钥存储的过程正在进行。这是一种暂时状态。
+ `DISCONNECTED`：自定义密钥库从未与其后端连接过，或者使用 AWS KMS 控制台或[DisconnectCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/DisconnectCustomKeyStores.html)操作故意断开了连接。
+ `DISCONNECTING`：断开自定义密钥存储的过程正在进行。这是一种暂时状态。
+ `FAILED`：尝试连接自定义密钥存储失败。[DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/DescribeCustomKeyStores.html)响应`ConnectionErrorCode`中的表示问题所在。
要连接自定义密钥存储，其连接状态必须为 `DISCONNECTED`。如果连接状态为 `FAILED`，则使用 `ConnectionErrorCode` 来识别和解决问题。接着断开自定义密钥存储，然后再尝试重新连接。如需帮助解决连接失败问题，请参阅 [外部密钥存储连接错误](xks-troubleshooting.md#fix-xks-connection)。有关响应连接错误代码的帮助信息，请参阅 [外部密钥存储的连接错误代码](xks-troubleshooting.md#xks-connection-error-codes)。
要查看连接错误代码，请执行以下操作：
+ 在[DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html)响应中，查看`ConnectionErrorCode`元素的值。只有当 `ConnectionState` 为 `FAILED` 时，此元素才会出现在 `DescribeCustomKeyStores` 响应中。
+ 要在 AWS KMS 控制台中查看连接错误代码，请在外部密钥存储的详细信息页面上将鼠标悬停在 Faile **d** 值上。
![\[自定义密钥存储详细信息页面上的连接错误代码\]](http://docs.aws.amazon.com/zh_cn/kms/latest/developerguide/images/connection-error-code.png)
# 连接外部密钥存储
外部密钥存储连接到其外部密钥存储代理后，您可以[在外部密钥存储中创建 KMS 密钥](create-cmk-keystore.md)，然后在[加密操作](manage-cmk-keystore.md#use-cmk-keystore)中使用现有 KMS 密钥。
将外部密钥存储连接到其外部密钥存储代理的过程因外部密钥存储的连接而异。
+ 当您将外部密钥存储与[公共端点连接连接](keystore-external.md#concept-xks-connectivity)时， AWS KMS 会向外部密钥存储代理发送[GetHealthStatus 请求](keystore-external.md#concept-proxy-apis)以验证代理 [URI 端点](create-xks-keystore.md#require-endpoint)、[代理 URI 路径](create-xks-keystore.md#require-path)和[代理身份验证凭据](keystore-external.md#concept-xks-credential)。来自代理的成功响应可确认[代理 URI 端点](create-xks-keystore.md#require-endpoint)和[代理 URI 路径](create-xks-keystore.md#require-path)准确且可访问，并且代理对使用外部密钥存储的[代理身份验证凭证](keystore-external.md#concept-xks-credential)签名的请求进行了身份验证。
+ 将具有 [VPC 终端节点服务连接](choose-xks-connectivity.md#xks-vpc-connectivity)的外部密钥存储与其外部密钥存储代理连接时， AWS KMS 会执行以下操作：
+ 确认[代理 URI 端点](create-xks-keystore.md#require-endpoint)中指定的私有 DNS 名称的域名已[通过验证](vpc-connectivity.md#xks-private-dns)。
+ 创建从 AWS KMS VPC 到您的 VPC 终端节点服务的接口终端节点。
+ 为代理 URI 端点中指定的私有 DNS 名称创建私有托管区
+ 向外部密钥存储代理发送[GetHealthStatus请求](keystore-external.md#concept-proxy-apis)。来自代理的成功响应可确认[代理 URI 端点](create-xks-keystore.md#require-endpoint)和[代理 URI 路径](create-xks-keystore.md#require-path)准确且可访问，并且代理对使用外部密钥存储的[代理身份验证凭证](keystore-external.md#concept-xks-credential)签名的请求进行了身份验证。
连接操作即开始连接您的自定义密钥存储的过程，但是将外部密钥存储连接到其外部代理大约需要五分钟。连接操作的成功响应并不表示外部密钥存储已连接。要确认连接是否成功，请使用 AWS KMS 控制台或[DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/DescribeCustomKeyStores.html)操作查看外部密钥存储库的[连接状态](xks-connect-disconnect.md#xks-connection-state)。
当连接状态为时`FAILED`， AWS KMS 控制台中会显示连接错误代码并将其添加到`DescribeCustomKeyStore`响应中。有关解释连接错误代码的帮助信息，请参阅 [外部密钥存储的连接错误代码](xks-troubleshooting.md#xks-connection-error-codes)。
## 连接和重新连接到您的外部密钥存储
您可以在 AWS KMS 控制台中或使用[ConnectCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_ConnectCustomKeyStore.html)操作来连接或重新连接外部密钥存储库。
### 使用控制 AWS KMS 台
您可以使用 AWS KMS 控制台将外部密钥存储与其外部密钥存储代理连接起来。
1. 登录 AWS 管理控制台 并在 [https://console.aws.amazon.com/km](https://console.aws.amazon.com/kms) s 处打开 AWS Key Management Service (AWS KMS) 控制台。
1. 要更改 AWS 区域，请使用页面右上角的区域选择器。
1. 在导航窗格中，选择 **Custom key stores**（自定义密钥存储）、**External key stores**（外部密钥存储）。
1. 选择要连接的外部密钥存储的行。
如果外部密钥存储的[连接状态](xks-connect-disconnect.md#xks-connection-state)为 **FAILED**（失败），则必须在连接之前[断开外部密钥存储](disconnect-keystore.md#disconnect-keystore-console)。
1. 从 **Key store actions**（密钥存储操作）菜单中选择 **Connect**（连接）。
该连接过程通常需要五分钟才能完成。操作完成后，[连接状态](xks-connect-disconnect.md#xks-connection-state)更改为 **CONNECTED**（已连接）。
如果连接状态为 **Failed**（失败），请将鼠标悬停在连接状态上方以查看*连接错误代码*，从中了解错误的原因。有关响应连接错误代码的帮助信息，请参阅 [外部密钥存储的连接错误代码](xks-troubleshooting.md#xks-connection-error-codes)。要连接处于 **Failed**（失败）连接状态的外部密钥存储，必须先[断开自定义密钥存储](disconnect-keystore.md#disconnect-keystore-console)。
### 使用 AWS KMS API
要连接已断开连接的外部密钥存储库，请使用[ConnectCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_ConnectCustomKeyStore.html)操作。
在连接之前，外部密钥存储的[连接状态](xks-connect-disconnect.md#xks-connection-state)必须为 `DISCONNECTED`。如果连接状态为 `FAILED`，请[断开外部密钥存储](about-xks-disconnecting.md#disconnect-xks-api)，再进行连接。
该连接过程可能需要五分钟才能完成。除非该过程迅速失败，否则 `ConnectCustomKeyStore` 将返回 HTTP 200 响应和无属性的 JSON 对象。但是，此初始响应不指示连接是否成功。要确定外部密钥存储是否已连接，请查看[DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html)响应中的连接状态。
本部分中的示例使用 [AWS Command Line Interface (AWS CLI)](https://aws.amazon.com/cli/)，但您可以使用任何受支持的编程语言。
要确定外部密钥存储，请使用自定义密钥存储 ID。您可以在控制台的**自定义密钥存储**页面上或使用[DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html)操作来找到 ID。在运行此示例之前，请将示例 ID 替换为有效的 ID。
```
$ aws kms connect-custom-key-store --custom-key-store-id cks-1234567890abcdef0
```
`ConnectCustomKeyStore` 操作不会在响应中返回 `ConnectionState`。要验证外部密钥存储是否已连接，请使用[DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html)操作。默认情况下，此操作将返回您的账户和区域中的所有自定义密钥存储。但您可以使用 `CustomKeyStoreId` 或 `CustomKeyStoreName` 参数（但不能同时使用两者）将响应限制到特定自定义密钥存储。`ConnectionState` 值为 `CONNECTED` 表示外部密钥存储已连接到其外部密钥存储代理。
```
$ 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"
}
}
]
}
```
如果 `DescribeCustomKeyStores` 响应中的 `ConnectionState` 值为 `FAILED`，则该 `ConnectionErrorCode` 元素指示失败的原因。
在以下示例中，的`XKS_VPC_ENDPOINT_SERVICE_NOT_FOUND`值`ConnectionErrorCode`表示找 AWS KMS 不到用于与外部密钥存储代理通信的 VPC 终端节点服务。验证是否正确， AWS KMS 服务委托人是否是 Amazon VPC 终端节点服务允许的委托人，以及 VPC 终端节点服务不要求接受连接请求。`XksProxyVpcEndpointServiceName`有关响应连接错误代码的帮助信息，请参阅 [外部密钥存储的连接错误代码](xks-troubleshooting.md#xks-connection-error-codes)。
```
$ 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"
}
}
]
}
```
# 断开外部密钥存储
从外部密钥存储代理断开具有 [VPC 端点服务连接](choose-xks-connectivity.md#xks-vpc-connectivity)的外部密钥存储时， AWS KMS 会删除其与 VPC 端点服务的接口端点，并移除其为支持连接而创建的网络基础设施。具有公有端点连接的外部密钥存储不需要等效流程。此操作不会影响 VPC 端点服务或其支持的任何组件，也不会影响外部密钥存储代理或任何外部组件。
当外部密钥存储断开连接时， AWS KMS 不会向外部密钥存储代理发送任何请求。外部密钥存储的连接状态为 `DISCONNECTED`。已断开连接的外部密钥存储中的 KMS 密钥处于 [`UNAVAILABLE` 密钥状态](key-state.md)（除非处于[待删除](deleting-keys.md)状态），这表示此类密钥不能用于加密操作。不过，您仍然可以查看和管理外部密钥存储及其现有 KMS 密钥。
已断开连接状态被设计为临时且可逆的状态。您可以随时重新连接外部密钥存储。通常无需重新配置。不过，如果关联的外部密钥存储代理的任何属性在断开连接时发生了变化，例如轮换了[代理身份验证凭证](keystore-external.md#concept-xks-credential)，则必须在重新连接之前[编辑外部密钥存储设置](update-xks-keystore.md)。
**注意**
虽然自定义密钥存储已断开连接，但在自定义密钥存储中创建 KMS 密钥或在加密操作中使用现有 KMS 密钥的所有尝试都将失败。此操作可以阻止用户存储和访问敏感数据。
为了更好地估计断开外部密钥存储的影响，请在外部密钥存储中标识 KMS 密钥，并[确定其过去的使用情况](deleting-keys-determining-usage.md)。
您可能出于以下原因断开外部密钥存储：
+ **编辑其属性。**在外部密钥存储处于连接状态时，您可以编辑自定义密钥存储名称、代理 URI 路径和代理身份验证凭证。不过，要编辑代理连接类型、代理 URI 端点或 VPC 端点服务名称，您必须先断开外部密钥存储的连接。有关更多信息，请参阅 [编辑外部密钥存储属性](update-xks-keystore.md)。
+ **停止与外部密钥存储代理 AWS KMS 之间的所有通信**。您也可以通过禁用终端节点或 VPC 终端节点服务来停止与代理之间的 AWS KMS 通信。此外，您的外部密钥存储代理或密钥管理软件可能会提供其他机制来 AWS KMS 防止与代理进行通信或阻止代理访问您的外部密钥管理器。
+ **禁用外部密钥存储中的所有 KMS 密钥**。您可以使用 AWS KMS 控制台或[DisableKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DisableKey.html)操作在外部[密钥存储中禁用和重新启](enabling-keys.md)用 KMS 密钥。这些操作会快速完成（视最终一致性而定），但一次只针对一个 KMS 密钥。断开外部密钥存储会将外部密钥存储中所有 KMS 密钥的密钥状态更改为 `Unavailable`，这将阻止在任何加密操作中使用这些 KMS 密钥。
+ **修复失败的连接尝试**。如果连接外部密钥存储的尝试失败（自定义密钥存储的连接状态为 `FAILED`），则必须在尝试再次连接外部密钥存储之前将其断开。
## 断开您的外部密钥存储
您可以在 AWS KMS 控制台中或使用[DisconnectCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_DisconnectCustomKeyStore.html)操作断开外部密钥存储的连接。
### 使用控制 AWS KMS 台
您可以使用 AWS KMS 控制台将外部密钥存储与其外部密钥存储代理连接起来。完成此过程大约需要 5 分钟。
1. 登录 AWS 管理控制台 并在 [https://console.aws.amazon.com/km](https://console.aws.amazon.com/kms) s 处打开 AWS Key Management Service (AWS KMS) 控制台。
1. 要更改 AWS 区域，请使用页面右上角的区域选择器。
1. 在导航窗格中，选择 **Custom key stores**（自定义密钥存储）、**External key stores**（外部密钥存储）。
1. 选择要断开连接的外部密钥存储的行。
1. 从 **Key store actions**（密钥存储操作）菜单中选择 **Disconnect**（断开连接）。
当操作完成时，连接状态将从 **DISCONNECTING** 变为 **DISCONNECTED**。如果操作失败，则会出现一条错误消息，描述问题并提供有关如何修复它的帮助。如果您需要更多帮助，请参阅[外部密钥存储连接错误](xks-troubleshooting.md#fix-xks-connection)。
### 使用 AWS KMS API
要断开连接的外部密钥存储库，请使用[DisconnectCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_DisconnectCustomKeyStore.html)操作。如果操作成功，则 AWS KMS 返回一个 HTTP 200 响应和一个没有属性的 JSON 对象。该过程可能需要五分钟才能完成。要查找外部密钥存储库的连接状态，请使用[DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html)操作。
本部分中的示例使用 [AWS Command Line Interface (AWS CLI)](https://aws.amazon.com/cli/)，但您可以使用任何受支持的编程语言。
此示例断开具有 VPC 端点服务连接的外部密钥存储。在运行此示例之前，请将示例自定义密钥存储 ID 替换为有效 ID。
```
$ aws kms disconnect-custom-key-store --custom-key-store-id cks-1234567890abcdef0
```
要验证外部密钥存储是否已断开连接，请使用[DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html)操作。默认情况下，此操作将返回您的账户和区域中的所有自定义密钥存储。但您可以使用 `CustomKeyStoreId` 和 `CustomKeyStoreName` 参数（但不能同时使用两者）将响应限制到特定自定义密钥存储。`DISCONNECTED` 的 `ConnectionState` 值表示此示例外部密钥存储不再连接到其外部密钥存储代理。
```
$ aws kms describe-custom-key-stores --custom-key-store-name ExampleXksVpc
{
"CustomKeyStores": [
{
"CustomKeyStoreId": "cks-9876543210fedcba9",
"CustomKeyStoreName": "ExampleXksVpc",
"ConnectionState": "DISCONNECTED",
"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"
}
}
]
}
```
# 删除外部密钥存储
删除外部密钥存储库时， AWS KMS 会从中删除有关该外部密钥存储的所有元数据 AWS KMS，包括有关其外部密钥存储代理的信息。此操作不会影响[外部密钥存储代](keystore-external.md#concept-xks-proxy)[理、外部密钥管理器](keystore-external.md#concept-ekm)、[外部密钥](keystore-external.md#concept-external-key)或您为支持外部密钥存储而创建的任何 AWS 资源，例如 Amazon VPC 或 VPC 终端节点服务。
在删除外部密钥存储之前，必须从密钥存储中[删除所有 KMS 密钥](deleting-keys.md)，并从其外部密钥存储代理[断开密钥存储](xks-connect-disconnect.md)。否则，尝试删除密钥存储将失败。
删除外部密钥存储是不可逆的操作，但您可以创建新的外部密钥存储并将其与同一个外部密钥存储代理和外部密钥管理器相关联。但是，即使您可以访问相同的外部密钥材料，也无法在外部密钥存储中重新创建对称加密 KMS 密钥。 AWS KMS 在每个 KMS 密钥独有的对称密文中包含元数据。此安全功能确保只有加密数据的 KMS 密钥才能解密数据。
与其删除外部密钥存储，不如考虑断开连接。当外部密钥存储断开连接时，您可以管理外部密钥存储库及其它， AWS KMS keys 但不能在外部密钥存储中创建或使用 KMS 密钥。您可以随时重新连接外部密钥存储并恢复使用其 KMS 密钥来加密和解密数据。我们不对已断开连接的外部密钥存储代理或其不可用的 KMS 密钥收取任何费用。
您可以在 AWS KMS 控制台中或使用[DeleteCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeleteCustomKeyStore.html)操作来删除您的外部密钥存储。
## 使用控制 AWS KMS 台
您可以使用 AWS KMS 控制台删除外部密钥存储库。
1. 登录 AWS 管理控制台 并在 [https://console.aws.amazon.com/km](https://console.aws.amazon.com/kms) s 处打开 AWS Key Management Service (AWS KMS) 控制台。
1. 要更改 AWS 区域，请使用页面右上角的区域选择器。
1. 在导航窗格中，选择 **Custom key stores**（自定义密钥存储）、**External key stores**（外部密钥存储）。
1. 找到表示要删除的外部密钥存储的行。如果外部密钥存储的 **Connection state**（连接状态）不是 **DISCONNECTED**（已断开连接），则必须[断开外部密钥存储](about-xks-disconnecting.md#disconnect-xks-console)，然后才能将其删除。
1. 从 **Key store actions**（密钥存储操作）菜单中选择 **Delete**（删除）。
在操作完成后，会显示一条成功消息，并且外部密钥存储不再显示在密钥存储列表中。如果操作失败，则会显示一条错误消息，描述问题并提供有关如何解决该问题的帮助。如果您需要更多帮助，请参阅[排查外部密钥存储的问题](xks-troubleshooting.md)。
## 使用 AWS KMS API
要删除外部密钥存储库，请使用[DeleteCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeleteCustomKeyStore.html)操作。如果操作成功，则 AWS KMS 返回一个 HTTP 200 响应和一个没有属性的 JSON 对象。
首先，断开外部密钥存储的连接。在运行此命令之前，请将示例自定义密钥存储 ID 替换为有效 ID。
```
$ aws kms disconnect-custom-key-store --custom-key-store-id cks-1234567890abcdef0
```
断开外部密钥存储后，您可以使用该[DeleteCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeleteCustomKeyStore.html)操作将其删除。
```
$ aws kms delete-custom-key-store --custom-key-store-id cks-1234567890abcdef0
```
要确认外部密钥存储已删除，请使用[DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html)操作。
```
$ aws kms describe-custom-key-stores
{
"CustomKeyStores": []
}
```
如果您指定的自定义密钥库名称或 ID 已不存在，则 AWS KMS 会返回`CustomKeyStoreNotFoundException`异常。
```
$ aws kms describe-custom-key-stores --custom-key-store-id cks-1234567890abcdef0
An error occurred (CustomKeyStoreNotFoundException) when calling the DescribeCustomKeyStore operation:
```
# 排查外部密钥存储的问题
大多数外部密钥存储问题的解决方法由每个异常时 AWS KMS 显示的错误消息或尝试将外部密钥存储库[连接到其外部密钥存储](xks-connect-disconnect.md)代理失败时 AWS KMS 返回的[连接错误代码](#fix-xks-connection)来指示。但是，有些问题较为复杂。
在诊断外部密钥存储的问题时，首先需要找到原因。这将缩小补救措施的范围，提高故障排除的效率。
+ AWS KMS — 问题可能出在内部 AWS KMS，例如[外部密钥存储配置](create-xks-keystore.md#xks-requirements)中的值不正确。
+ 外部 — 问题可能源于外部 AWS KMS，包括外部密钥存储代理、外部密钥管理器、外部密钥或 VPC 端点服务的配置或操作问题。
+ 联网：可能是连接或网络问题，例如代理端点、端口、IP 堆栈或私有 DNS 名称或域存在问题。
**注意**
当外部密钥存储的管理操作失败时，这些操作会生成几个不同的异常。但是，所有与外部密钥存储库的外部配置或连接状态相关的失败都会返回 AWS KMS `KMSInvalidStateException`加密操作。若要确定问题，请使用随附的错误消息文本。
在连接过程完成之前，[ConnectCustomKeyStore](xks-connect-disconnect.md)操作很快就会成功。要确定连接过程是否成功，请查看外部密钥存储的[连接状态](xks-connect-disconnect.md#xks-connection-state)。如果连接过程失败，则 AWS KMS 将返回[连接错误代码](#xks-connection-error-codes)，用于解释原因并提出补救措施建议。
**Topics**
+ [
## 外部密钥存储故障排除工具
](#xks-troubleshooting-tools)
+ [
## 配置错误
](#fix-xks-configuration)
+ [
## 外部密钥存储连接错误
](#fix-xks-connection)
+ [
## 延迟和超时错误
](#fix-xks-latency)
+ [
## 身份验证凭证错误
](#fix-xks-credentials)
+ [
## 密钥状态错误
](#fix-unavailable-xks-keys)
+ [
## 解密错误
](#fix-xks-decrypt)
+ [
## 外部密钥错误
](#fix-external-key)
+ [
## 代理问题
](#fix-xks-proxy)
+ [
## 代理授权问题
](#fix-xks-authorization)
## 外部密钥存储故障排除工具
AWS KMS 提供了多种工具来帮助您识别和解决外部密钥存储库及其密钥的问题。请将这些工具与随外部密钥存储代理和外部密钥管理器提供的工具结合使用。
**注意**
您的外部密钥存储代理和外部密钥管理器可能会提供更简单的方法来创建和维护外部密钥存储及其 KMS 密钥。有关详细信息，请参阅外部工具的相关文档。
**AWS KMS 异常和错误消息**
AWS KMS 提供了有关它遇到的任何问题的详细错误消息。您可以在《API 参考》和《[https://docs.aws.amazon.com/kms/latest/APIReference/](https://docs.aws.amazon.com/kms/latest/APIReference/)》中找到有关 AWS KMS 异常的更多信息 AWS SDKs。即使你使用的是 AWS KMS 控制台，你也可能会发现这些参考资料很有帮助。例如，您可以参阅 `CreateCustomKeyStores` 操作的[错误](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateCustomKeyStore.html#API_CreateCustomKeyStore_Errors)列表。
要优化外部密钥存储代理的性能， AWS KMS 在给定的 5 分钟聚合期内，根据代理的可靠性返回异常。如果出现 500 内部服务器错误、503 服务不可用或连接超时，可靠性高的代理会返回 `KMSInternalException` 并触发自动重试，以确保请求最终成功。但是，可靠性较低的代理会返回 `KMSInvalidStateException`。有关更多信息，请参阅[监控外部密钥存储](https://docs.aws.amazon.com/kms/latest/developerguide/xks-monitoring.html)。
如果问题出现在其他 AWS 服务中，例如当您使用外部密钥存储中的 KMS 密钥来保护其他 AWS 服务中的资源时，该 AWS 服务可能会提供其他信息来帮助您识别问题。如果 AWS 服务未提供消息，则可以在记录您的 KMS 密钥使用情况的[CloudTrail 日志](logging-using-cloudtrail.md)中查看错误消息。
**[CloudTrail logs](logging-using-cloudtrail.md)**
每 AWS KMS 个 API 操作，包括 AWS KMS 控制台中的操作，都记录在 AWS CloudTrail 日志中。 AWS KMS 记录成功和失败操作的日志条目。对于失败的操作，日志条目包括 AWS KMS 异常名称（`errorCode`）和错误消息（`errorMessage`）。您可以使用此信息来确定和解决错误。有关示例，请参阅[使用外部密钥存储中的 KMS 密钥解密失败](ct-decrypt.md#ct-decrypt-xks-fail)。
日志条目还包括请求 ID。如果请求到达您的外部密钥存储代理，则您可以使用日志条目中的请求 ID，在代理日志中查找相应的请求（前提是您的代理提供日志）。
**[CloudWatch metrics](monitoring-cloudwatch.md#kms-metrics)**
AWS KMS 记录有关您的外部密钥存储操作和性能的详细亚马逊 CloudWatch 指标，包括延迟、限制、代理错误、外部密钥管理器状态、距您的 TLS 证书到期的天数以及您的代理身份验证证书报告的使用期限。您可以使用这些指标为外部密钥存储的操作开发数据模型，并使用 CloudWatch 警报在即将发生的问题发生之前提醒您。
AWS KMS 建议您创建 CloudWatch 警报以监控外部密钥存储指标。这些警报将在问题出现之前提醒您注意问题的早期迹象。
**[监控图表](xks-monitoring.md)**
AWS KMS 在 AWS KMS 控制台中每个外部密钥存储的详细信息页面上显示外部密钥存储 CloudWatch 指标的图表。您可以使用图表中的数据来帮助定位错误来源、检测即将发生的问题、建立基线和完善 CloudWatch 警报阈值。有关监控图标解释和使用其数据的详细信息，请参阅 [监控外部密钥存储](xks-monitoring.md)。
**显示外部密钥存储和 KMS 密钥**
AWS KMS 在 AWS KMS 控制台的外部密钥存储区以及对和[DescribeKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html)操作的响应中显示有关您的外部密钥存储和 KMS 密钥的[DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html)详细信息。这些显示信息包括外部密钥存储和 KMS 密钥的特殊字段，其中包含可用于故障排除的信息，例如外部密钥存储的[连接状态](xks-connect-disconnect.md#xks-connection-state)和与 KMS 密钥关联的外部密钥的 ID。有关更多信息，请参阅 [查看外部密钥存储](view-xks-keystore.md)。
**[XKS 代理测试客户端](https://github.com/aws-samples/aws-kms-xksproxy-test-client)**
AWS KMS 提供了一个开源测试客户端，用于验证您的外部密钥存储代理是否符合[AWS KMS 外部密钥库代理 API](https://github.com/aws/aws-kms-xksproxy-api-spec/) 规范。您可以使用此测试客户端来确定和解决外部密钥存储代理的问题。
## 配置错误
创建外部密钥存储时，您需要指定构成外部密钥存储*配置*的属性值，例如[代理身份验证凭证](create-xks-keystore.md#require-credential)、[代理 URI 端点](create-xks-keystore.md#require-endpoint)、[代理 URI 路径](create-xks-keystore.md#require-path)和 [VPC 端点服务名称](create-xks-keystore.md#require-vpc-service-name)。当 AWS KMS 检测到属性值中有错误时，操作将失败并返回一个指示错误值的错误。
通过修复错误的值，可以解决许多配置问题。您可以修复无效的代理 URI 路径或代理身份验证凭证，而无需断开外部密钥存储的连接。有关这些值的定义，包括唯一性要求，请参阅 [汇编先决条件](create-xks-keystore.md#xks-requirements)。有关更新这些值的说明，请参阅 [编辑外部密钥存储属性](update-xks-keystore.md)。
为避免代理 URI 路径和代理身份验证凭证值出错，在创建或更新外部密钥存储时，请将[代理配置文件](create-xks-keystore.md#proxy-configuration-file)上传到 AWS KMS 控制台。这是一个基于 JSON 的文件，其中包含由外部密钥存储代理或外部密钥管理器提供的代理 URI 路径和代理身份验证凭证值。您不能在 AWS KMS API 操作中使用代理配置文件，但您可以使用该文件中的值来帮助您为 API 请求提供与代理中的值相匹配的参数值。
### 常规配置错误
**异常**：`CustomKeyStoreInvalidStateException`（`CreateKey`）、`KMSInvalidStateException`（加密操作）、`XksProxyInvalidConfigurationException`（管理操作，`CreateKey` 除外）
[**连接错误代码**](#xks-connection-error-codes)：`XKS_PROXY_INVALID_CONFIGURATION`、`XKS_PROXY_INVALID_TLS_CONFIGURATION`
对于具有[公共端点连接](choose-xks-connectivity.md#xks-connectivity-public-endpoint)的外部密钥存储，请在创建和更新外部密钥存储时 AWS KMS 测试属性值。对于使用 [VPC 端点服务连接](choose-xks-connectivity.md#xks-vpc-connectivity)的外部密钥存储， AWS KMS 会在您连接和更新外部密钥存储时测试属性值。
**注意**
即使尝试将外部密钥存储连接到其外部密钥存储代理失败，异步 `ConnectCustomKeyStore` 操作也可能会成功。在这种情况下，不会出现异常，但外部密钥存储的连接状态为“Failed（失败）”，并且连接错误代码将说明错误消息。有关更多信息，请参阅 [外部密钥存储连接错误](#fix-xks-connection)。
如果在属性值中 AWS KMS 检测到错误，则操作将失败`XksProxyInvalidConfigurationException`并返回以下错误消息之一。
| |
| --- |
| 由于 URI 路径无效，外部密钥存储代理拒绝了该请求。请验证外部密钥存储的 URI 路径，并在必要时进行更新。 |
+ 代[理 URI 路径](create-xks-keystore.md#require-path)是向代理 AWS KMS 发出请求的基本路径 APIs。如果此路径不正确，则对代理的所有请求都将失败。如需[查看外部密钥存储的当前代理 URI 路径](view-xks-keystore.md)，请使用 AWS KMS 控制台或 `DescribeCustomKeyStores` 操作。如需查找正确的代理 URI 路径，请参阅您的外部密钥存储代理文档。有关更正代理 URI 路径值的帮助，请参阅 [编辑外部密钥存储属性](update-xks-keystore.md)。
+ 随着外部密钥存储代理或外部密钥管理器的更新，外部密钥存储代理的代理 URI 路径可能会发生变化。有关此类变化的详细信息，请参阅外部密钥存储代理或外部密钥管理器的文档。
| |
| --- |
| `XKS_PROXY_INVALID_TLS_CONFIGURATION`AWS KMS 无法与外部密钥存储代理建立 TLS 连接。请验证 TLS 配置，包括其证书。 |
+ 所有外部密钥存储代理都需要 TLS 证书。TLS 证书必须由支持外部密钥存储的公有证书颁发机构（CA）颁发。有关支持的列表 CAs，请参阅《 AWS KMS 外部密钥存储区代理 API 规范》中的[可信证书颁发机构](https://github.com/aws/aws-kms-xksproxy-api-spec/blob/main/TrustedCertificateAuthorities)。
+ 对于公有端点连接，TLS 证书上的主题公用名（CN）必须与外部密钥存储代理的[代理 URI 端点](create-xks-keystore.md#require-endpoint)中的域名相匹配。例如，如果公有端点是 https://myproxy.xks.example.com，即 TLS，则 TLS 证书上的 CN 必须为 `myproxy.xks.example.com` 或 `*.xks.example.com`。
+ 对于 VPC 端点服务连接，TLS 证书上的主题公用名（CN）必须与您的 [VPC 端点服务](create-xks-keystore.md#require-vpc-service-name)的私有 DNS 名称相匹配。例如，如果私有 DNS 名称是 myproxy-private.xks.example.com，则 TLS 证书上的 CN 必须为 `myproxy-private.xks.example.com` 或 `*.xks.example.com`。
+ TLS 证书不得过期。要获取 TLS 证书的到期日期，请使用 SSL 工具，例如 [OpenSSL](https://www.openssl.org/)。要监控与外部密钥存储库关联的 TLS 证书的到期日期，请使用该[XksProxyCertificateDaysToExpire](monitoring-cloudwatch.md#metric-xks-proxy-certificate-days-to-expire) CloudWatch 指标。 AWS KMS 控制台的 “[**监控**” 部分](xks-monitoring.md)还会显示 TLS 认证到期日期的天数。
+ 如果您使用[公有端点连接](choose-xks-connectivity.md#xks-connectivity-public-endpoint)，请使用 SSL 测试工具来测试您的 SSL 配置。TLS 连接错误可能是由不正确的证书链导致。
### VPC 端点服务连接配置错误
**异常**：`XksProxyVpcEndpointServiceNotFoundException`、`XksProxyVpcEndpointServiceInvalidConfigurationException`
除了一般的连接问题外，在创建、连接或更新具有 VPC 终端节点服务连接的外部密钥存储库时，您可能会遇到以下问题。 AWS KMS 在[创建](create-xks-keystore.md)、连接和[更新](update-xks-keystore.md)外部密钥存储库时，测试具有 VPC 终端节点服务[连接](xks-connect-disconnect.md)的外部密钥存储的属性值。当管理操作由于配置错误而失败时，这些操作会生成以下异常：
| |
| --- |
| XksProxyVpcEndpointServiceNotFoundException |
原因可能是以下之一：
+ VPC 端点服务名称不正确。请验证外部密钥存储的 VPC 端点服务名称是否正确，以及是否与外部密钥存储的代理 URI 端点值相匹配。要查找 VPC 终端节点服务名称，请使用 [Amazon VPC 控制台](https://console.aws.amazon.com/vpc)或[DescribeVpcEndpointServices](https://docs.aws.amazon.com/AmazonVPC/latest/APIReference/DescribeVpcEndpointServices.html)操作。要查找现有外部密钥存储区的 VPC 终端节点服务名称和代理 URI 终端节点，请使用 AWS KMS 控制台或[DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html)操作。有关更多信息，请参阅 [查看外部密钥存储](view-xks-keystore.md)。
+ VPC 终端节点服务可能位于与外部密钥存储区 AWS 区域 不同的位置。请验证 VPC 端点服务和外部密钥存储是否处于同一区域。（区域名称的外部名称，例如，是 VPC 终端节点服务名称的一部分`us-east-1`，例如 com.amazonaws.vpce.us-east-1。 vpce-svc-example。） 有关对外部密钥存储的 VPC 端点服务的要求列表，请参阅 [VPC 终端节点服务](create-xks-keystore.md#require-vpc-service-name)。您无法将 VPC 端点服务或外部密钥存储移至其他区域。但是，您可以在 VPC 端点服务所在的同一区域中创建新的外部密钥存储。有关详细信息，请参阅 [配置 VPC 端点服务连接](vpc-connectivity.md) 和 [创建外部密钥存储](create-xks-keystore.md)。
+ AWS KMS 不是 VPC 终端节点服务的允许委托人。VPC 端点服务的 **Allow principals**（允许主体）列表必须包含 `cks.kms..amazonaws.com` 值，例如 `cks.kms.eu-west-3.amazonaws.com`。有关添加此值的说明，请参阅《AWS PrivateLink 指南》**中的[管理权限](https://docs.aws.amazon.com/vpc/latest/privatelink/configure-endpoint-service.html#add-remove-permissions)。
| |
| --- |
| XksProxyVpcEndpointServiceInvalidConfigurationException |
当 VPC 端点服务无法满足以下要求之一时，就会出现此错误：
+ VPC 需要至少两个私有子网，每个子网均位于不同的可用区内。有关将子网添加到 VPC 中的帮助，请参阅《Amazon VPC 用户指南》**中的[在您的 VPC 中创建子网](https://docs.aws.amazon.com/vpc/latest/userguide/working-with-subnets.html#create-subnets)。
+ 您的 [VPC 端点服务类型](https://docs.aws.amazon.com/vpc/latest/privatelink/create-endpoint-service.html)必须使用网络负载均衡器，而不是网关负载均衡器。
+ 不得要求 VPC 端点服务接受请求 [**Acceptance required**（需要接受）必须是“false”]。如果需要手动接受每个连接请求，则 AWS KMS 无法使用 VPC 终端节点服务连接到外部密钥存储代理。有关详细信息，请参阅《AWS PrivateLink 指南》**中的[接受或拒绝连接请求](https://docs.aws.amazon.com/vpc/latest/privatelink/configure-endpoint-service.html#accept-reject-connection-requests)。
+ VPC 端点服务必须具有私有 DNS 名称，该名称是公有域的子域。例如，如果私有 DNS 名称为 `https://myproxy-private.xks.example.com`，则 `xks.example.com` 或 `example.com` 域必须具有公有 DNS 服务器。要查看或更改 VPC 端点服务的私有 DNS 名称，请参阅《AWS PrivateLink 指南》**中的[管理 VPC 端点服务的 DNS 名称](https://docs.aws.amazon.com/vpc/latest/privatelink/manage-dns-names.html)。
+ 您的私有 DNS 名称域的 **Domain verification status**（域验证状态）必须为 `verified`。要查看和更新私有 DNS 名称域的验证状态，请参阅 [步骤 5：验证私有 DNS 名称域](vpc-connectivity.md#xks-private-dns)。添加所需的文本记录后，可能需要几分钟才能显示更新的验证状态。
**注意**
只有当私有 DNS 域是公有域的子域时，才能对其进行验证。否则，即使您添加了所需的 TXT 记录，私有 DNS 域的验证状态也不会更改。
+ 确保与外部密钥存储代理 AWS KMS 之间的任何防火墙都允许进出代理上端口 443 的流量。 AWS KMS 通过端口 443 进行通信。 IPv4此值不可配置。
+ VPC 端点服务的私有 DNS 名称必须与外部密钥存储的[代理 URI 端点](create-xks-keystore.md#require-endpoint)值相匹配。对于使用 VPC 端点服务连接的外部密钥存储，代理 URI 端点必须是 `https://`，后跟 VPC 端点服务的私有 DNS 名称。要查看代理 URI 端点值，请参阅 [查看外部密钥存储](view-xks-keystore.md)。要更改代理 URI 端点值，请参阅 [编辑外部密钥存储属性](update-xks-keystore.md)。
## 外部密钥存储连接错误
[将外部密钥存储连接到其外部密钥存储代理的过程](about-xks-connecting.md)大约需要五分钟才能完成。除非该过程迅速失败，否则 `ConnectCustomKeyStore` 操作将返回 HTTP 200 响应和无属性的 JSON 对象。但是，此初始响应不指示连接是否成功。要确定外部密钥存储是否已连接，请查看其[连接状态](xks-connect-disconnect.md#xks-connection-state)。如果连接失败，则外部密钥存储库的[连接状态将更改为`FAILED`并 AWS KMS 返回一个解释失败原因的连接错误代码](#xks-connection-error-codes)。
**注意**
当自定义密钥存储的连接状态为 `FAILED` 时，您必须先断开自定义密钥存储的连接，然后再尝试重新连接。您无法连接具有 `FAILED` 连接状态的自定义密钥存储。
查看外部密钥存储的连接状态：
+ 在[DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html)响应中，查看`ConnectionState`元素的值。
+ 在 AWS KMS 控制台中，**连接状态**显示在外部密钥存储表中。此外，每个外部密钥存储的详细信息页面上的 **General configuration**（常规配置）部分中也显示了 **Connection state**（连接状态）。
当连接状态为 `FAILED` 时，连接错误代码有助于解释错误。
要查看连接错误代码，请执行以下操作：
+ 在[DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html)响应中，查看`ConnectionErrorCode`元素的值。只有当 `ConnectionState` 为 `FAILED` 时，此元素才会出现在 `DescribeCustomKeyStores` 响应中。
+ 要在 AWS KMS 控制台中查看连接错误代码，请在外部密钥存储的详细信息页面上将鼠标悬停在 Faile **d** 值上。
![\[自定义密钥存储详细信息页面上的连接错误代码\]](http://docs.aws.amazon.com/zh_cn/kms/latest/developerguide/images/connection-error-code.png)
### 外部密钥存储的连接错误代码
以下连接错误代码适用于外部密钥存储
`INTERNAL_ERROR`
AWS KMS 由于内部错误，无法完成请求。重试请求。对于 `ConnectCustomKeyStore` 请求，先断开自定义密钥存储，然后再尝试重新连接它。
`INVALID_CREDENTIALS`
其中一个或两个 `XksProxyAuthenticationCredential` 值在指定的外部密钥存储代理上无效。
`NETWORK_ERRORS`
网络错误使自定义密钥存储无法 AWS KMS 连接到其备用密钥存储库。
`XKS_PROXY_ACCESS_DENIED`
AWS KMS 请求被拒绝访问外部密钥库代理。如果外部密钥存储代理有授权规则，请验证这些规则是否允许 AWS KMS 代表您与代理进行通信。
`XKS_PROXY_INVALID_CONFIGURATION`
配置错误导致外部密钥存储无法连接到其代理。验证 `XksProxyUriPath` 的值。
`XKS_PROXY_INVALID_RESPONSE`
AWS KMS 无法解释来自外部密钥存储代理的响应。如果您反复看到此连接错误代码，请通知您的外部密钥存储代理供应商。
`XKS_PROXY_INVALID_TLS_CONFIGURATION`
AWS KMS 由于 TLS 配置无效，无法连接到外部密钥库代理。请验证外部密钥存储代理是否支持 TLS 1.2 或 1.3。此外，请验证 TLS 证书是否未过期，其是否与 `XksProxyUriEndpoint` 值中的主机名匹配，以及是否由[受信任的证书颁发机构](https://github.com/aws/aws-kms-xksproxy-api-spec/blob/main/TrustedCertificateAuthorities)列表中包含的受信任的证书颁发机构签名。
`XKS_PROXY_NOT_REACHABLE`
AWS KMS 无法与您的外部密钥存储代理通信。请验证 `XksProxyUriEndpoint` 和 `XksProxyUriPath` 是否正确。使用外部密钥存储代理的工具来验证该代理是否处于活动状态并在其网络上可用。此外，请验证您的外部密钥管理器实例是否正常运行。如果代理报告所有外部密钥管理器实例都不可用，则连接尝试失败，并显示此连接错误代码。
`XKS_PROXY_TIMED_OUT`
AWS KMS 可以连接到外部密钥存储代理，但该代理 AWS KMS 在分配的时间内没有响应。如果您反复看到此连接错误代码，请通知您的外部密钥存储代理供应商。
`XKS_VPC_ENDPOINT_SERVICE_INVALID_CONFIGURATION`
Amazon VPC 终端节点服务配置不符合 AWS KMS 外部密钥存储的要求。
+ VPC 端点服务必须是调用方 AWS 账户中的接口端点的端点服务。
+ 其必须有至少连接到两个子网的网络负载均衡器（NLB），每个子网位于不同的可用区中。
+ 该`Allow principals`列表必须包括该地区的 AWS KMS 服务主体`cks.kms..amazonaws.com`，例如`cks.kms.us-east-1.amazonaws.com`。
+ 其*不得*要求[接受](https://docs.aws.amazon.com/vpc/latest/privatelink/create-endpoint-service.html)连接请求。
+ 其必须具有私有 DNS 名称。使用 `VPC_ENDPOINT_SERVICE` 连接的外部密钥存储的私有 DNS 名称在其 AWS 区域中必须是唯一的。
+ 私有 DNS 名称域的[验证状态](https://docs.aws.amazon.com/vpc/latest/privatelink/verify-domains.html)必须为 `verified`。
+ [TLS 证书](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/create-tls-listener.html)指定了端点可以访问的私有 DNS 主机名。
`XKS_VPC_ENDPOINT_SERVICE_NOT_FOUND`
AWS KMS 找不到用于与外部密钥存储代理通信的 VPC 终端节点服务。请验证 `XksProxyVpcEndpointServiceName` 是否正确，以及 AWS KMS 服务主体是否拥有 Amazon VPC 端点服务中的服务使用者权限。
## 延迟和超时错误
**异常**：`CustomKeyStoreInvalidStateException`（`CreateKey`）、`KMSInvalidStateException`（加密操作）、`XksProxyUriUnreachableException`（管理操作）
[**连接错误代码**](#xks-connection-error-codes)：`XKS_PROXY_NOT_REACHABLE`、`XKS_PROXY_TIMED_OUT`
当 AWS KMS 无法在 250 毫秒的超时间隔内联系代理时，它会返回异常。 `CreateCustomKeyStore`然后`UpdateCustomKeyStore`返回`XksProxyUriUnreachableException`。加密操作会返回标准 `KMSInvalidStateException`，其中包含描述问题的错误消息。如果`ConnectCustomKeyStore`失败，则 AWS KMS 返回描述问题的[连接错误代码](#fix-xks-connection)。
超时错误可能是暂时性问题，可以通过重试请求来解决。如果问题仍然存在，请验证您的外部密钥存储代理是否处于活动状态并已连接到网络，以及其在外部密钥存储中的代理 URI 端点、代理 URI 路径和 VPC 端点服务名称（如果有）是否正确。此外，请验证您的外部密钥管理器是否接近外部密钥存储库。 AWS 区域 如果您需要更新其中任何值，请参阅 [编辑外部密钥存储属性](update-xks-keystore.md)。
要跟踪延迟模式，请使用 AWS KMS 控制台[**监控**部分](xks-monitoring.md)中的指标**和平均延迟**图表（基于该指标）。[`XksProxyLatency`](monitoring-cloudwatch.md#metric-xks-proxy-latency) CloudWatch 您的外部密钥存储代理可能还会生成跟踪延迟和超时的日志和指标。
| |
| --- |
| `XksProxyUriUnreachableException`AWS KMS 无法与外部密钥存储代理通信。这可能是暂时的网络问题。如果您反复看到此错误，请验证您的外部密钥存储代理是否处于活动状态并已连接到网络，以及其在外部密钥存储中的端点 URI 是否正确。 |
+ 外部密钥存储代理未在 250 毫秒的超时间隔内响应 AWS KMS 代理 API 请求。这可能表示出现临时网络问题或代理存在操作或性能问题。如果重试不能解决该问题，请通知您的外部密钥存储代理管理员。
延迟和超时错误通常表现为连接失败。[ConnectCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_ConnectCustomKeyStore.html)操作失败时，外部密钥存储库的*连接状态*将更改为`FAILED`并 AWS KMS 返回解释*错误的连接错误代码*。有关连接错误代码的列表和解决错误的建议，请参阅 [外部密钥存储的连接错误代码](#xks-connection-error-codes)。**All custom key stores**（所有自定义密钥存储）和 **External key stores**（外部密钥存储）的连接代码列表适用于外部密钥存储。以下连接错误与延迟和超时有关。
| |
| --- |
| `XKS_PROXY_NOT_REACHABLE`–或者–`CustomKeyStoreInvalidStateException`, `KMSInvalidStateException`, `XksProxyUriUnreachableException`AWS KMS 无法与外部密钥存储代理通信。请验证您的外部密钥存储代理是否处于活动状态并已连接到网络，以及其在外部密钥存储中的 URI 路径和端点 URI 或 VPC 服务名称是否正确。 |
出现此错误可能的原因如下：
+ 外部密钥存储代理未处于活动状态或未连接到网络。
+ 外部密钥存储配置中的[代理 URI 端点](create-xks-keystore.md#require-endpoint)、[代理 URI 路径](create-xks-keystore.md#require-path)或 [VPC 端点服务名称](create-xks-keystore.md#require-vpc-service-name)（如果适用）值有错误。要查看外部密钥存储配置，请使用[DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html)操作或[在 AWS KMS 控制台中查看外部密钥存储的详细信息页面](view-xks-keystore.md)。
+ 与外部密钥存储代理之间的网络路径上可能存在网络配置错误 AWS KMS ，例如端口错误。 AWS KMS 通过端口 443 与外部密钥存储代理通信。 IPv4此值不可配置。
+ 当外部密钥存储代理报告（在[GetHealthStatus](keystore-external.md#concept-proxy-apis)响应中）所有外部密钥管理器实例均为时`UNAVAILABLE`，[ConnectCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_ConnectCustomKeyStore.html)操作将失败，并显示为`ConnectionErrorCode``XKS_PROXY_NOT_REACHABLE`。有关帮助信息，请参阅外部密钥管理器的文档。
+ 此错误可能是由于外部密钥管理器 AWS 区域 与外部密钥存储库之间的物理距离较远所致。 AWS 区域 和外部密钥管理器之间的 ping 延迟（网络往返时间 (RTT)）不应超过 35 毫秒。您可能需要在离外部密钥管理器更近的地方创建外部密钥存储库，或者将外部密钥管理器移到离外部密钥管理器更近的数据中心 AWS 区域。 AWS 区域
| |
| --- |
| `XKS_PROXY_TIMED_OUT`–或者–`CustomKeyStoreInvalidStateException`, `KMSInvalidStateException`, `XksProxyUriUnreachableException`AWS KMS 拒绝了该请求，因为外部密钥存储代理没有及时响应。重试请求。如果您反复看到此错误，请将其报告给您的外部密钥存储代理管理员。 |
出现此错误可能的原因如下：
+ 此错误可能是由外部密钥管理器与外部密钥存储代理之间的物理距离过远所致。如可行，请将外部密钥存储代理移到离外部密钥管理器更近的地方。
+ 如果代理不是为处理来自的请求量和频率而设计的，则可能会发生超时错误 AWS KMS。如果您的 CloudWatch 指标显示问题持续存在，请通知您的外部密钥存储代理管理员。
+ 当外部密钥管理器与外部密钥存储的 Amazon VPC 之间的连接无法正常运行时，可能会出现超时错误。如果您正在使用 AWS Direct Connect，请验证您的 VPC 和外部密钥管理器是否可以有效通信。要获得解决任何问题的帮助，请参阅《 Direct Connect 用户指南》 AWS Direct Connect中的 “[疑难解答](https://docs.aws.amazon.com/directconnect/latest/UserGuide/Troubleshooting.html)”。
| |
| --- |
| `XKS_PROXY_TIMED_OUT`–或者–`CustomKeyStoreInvalidStateException`, `KMSInvalidStateException`, `XksProxyUriUnreachableException` 外部密钥存储代理未在分配的时间内响应请求。重试请求。如果您反复看到此错误，请将其报告给您的外部密钥存储代理管理员。 |
+ 此错误可能是由外部密钥管理器与外部密钥存储代理之间的物理距离过远所致。如可行，请将外部密钥存储代理移到离外部密钥管理器更近的地方。
## 身份验证凭证错误
**异常**：`CustomKeyStoreInvalidStateException`（`CreateKey`）、`KMSInvalidStateException`（加密操作）、`XksProxyIncorrectAuthenticationCredentialException`（管理操作，`CreateKey` 除外）
您在外部密钥存储代理 AWS KMS 上建立和维护的身份验证凭据。然后， AWS KMS 在创建外部密钥存储库时告诉凭据值。要更改身份验证凭证，请在外部密钥存储代理中进行更改。然后，针对外部密钥存储[更新凭证](update-xks-keystore.md#xks-edit-name)。如果您的代理轮换凭证，则必须针对外部密钥存储[更新凭证](update-xks-keystore.md#xks-edit-name)。
如果外部密钥存储代理无法针对您的外部密钥存储，对具有[代理身份验证凭证](keystore-external.md#concept-xks-credential)签名的请求进行身份验证，则效果取决于请求：
+ `CreateCustomKeyStore` 和 `UpdateCustomKeyStore` 失败，并显示 `XksProxyIncorrectAuthenticationCredentialException`。
+ `ConnectCustomKeyStore` 成功，但连接失败。连接状态为 `FAILED`，连接错误代码为 `INVALID_CREDENTIALS`。有关更多信息，请参阅 [外部密钥存储连接错误](#fix-xks-connection)。
+ 加密操作将返回 `KMSInvalidStateException`，指出外部密钥存储中的所有外部配置错误和连接状态错误。随附的错误消息描述了问题。
| |
| --- |
| 外部密钥存储代理拒绝了该请求，因为其无法对 AWS KMS进行身份验证。请验证外部密钥存储的凭证，并在必要时进行更新。 |
出现此错误可能的原因如下：
+ 外部密钥存储的访问密钥 ID 或秘密访问密钥与在外部密钥存储代理上建立的值不匹配。
要修复此错误，请针对外部密钥存储[更新代理身份验证凭证](update-xks-keystore.md#xks-edit-name)。无需断开外部密钥存储的连接即可进行此更改。
+ AWS KMS 和外部密钥存储代理之间的反向代理可能正在操纵 HTTP 标头，从而使 SigV4 签名失效。要修复此错误，请通知您的代理管理员。
## 密钥状态错误
**异常**：`KMSInvalidStateException`
`KMSInvalidStateException` 对自定义密钥存储中的 KMS 密钥有两个不同的用途。
+ 当管理操作（例如 `CancelKeyDeletion`）失败并返回此异常时，这表明 KMS 密钥的[密钥状态](key-state.md)与该操作不兼容。
+ 当对自定义密钥存储中 KMS 密钥的[加密操作](kms-cryptography.md#cryptographic-operations)失败，并显示 `KMSInvalidStateException` 时，这可能表明 KMS 密钥的密钥状态存在问题。但是， AWS KMS 加密操作会返回`KMSInvalidStateException`外部密钥存储库中的所有外部配置错误和连接状态错误。要确定问题，请使用随异常显示的错误消息。
要查找 AWS KMS API 操作所需的密钥状态，请参阅[密 AWS KMS 钥的关键状态](key-state.md)。要查找 KMS 密钥的密钥状态，请在 **Customer managed keys**（客户托管密钥）页面上，查看 KMS 密钥的 **Status**（状态）字段。或者，使用[DescribeKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html)操作并查看响应中的`KeyState`元素。有关更多信息，请参阅 [识别和查看密钥](viewing-keys.md)。
**注意**
外部密钥存储中 KMS 密钥的密钥状态并不表明其关联的[外部密钥](keystore-external.md#concept-external-key)的状态。有关外部密钥状态的信息，请使用外部密钥管理器和外部密钥存储代理工具。
`CustomKeyStoreInvalidStateException` 指的是外部密钥存储的[连接状态](xks-connect-disconnect.md#xks-connection-state)，而不是 KMS 密钥的[密钥状态](key-state.md)。
对自定义存储中 KMS 密钥的加密操作可能会失败，因为 KMS 密钥的密钥状态为 `Unavailable` 或 `PendingDeletion`。（禁用的密钥将返回 `DisabledException`。）
+ 只有当您在 AWS KMS 控制台或使用[DisableKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DisableKey.html)操作故意禁用 KMS 密钥时，KMS 密钥才会处于密钥状态。`Disabled`当某个 KMS 密钥已禁用时，您可以查看和管理该密钥，但不能在加密操作中使用该密钥。要修复此问题，请启用密钥。有关更多信息，请参阅 [启用和禁用密钥](enabling-keys.md)。
+ 当外部密钥存储与其外部密钥存储代理断开连接时，KMS 密钥会处于 `Unavailable` 密钥状态。要修复不可用的 KMS 密钥，请[重新连接外部密钥存储](xks-connect-disconnect.md)。重新连接外部密钥存储后，外部密钥存储中的 KMS 密钥的密钥状态将自动还原到之前的状态，例如 `Enabled` 或 `Disabled`。
在计划删除 KMS 密钥，或 KMS 密钥处于等待期时，其会处于 `PendingDeletion` 密钥状态。待删除的 KMS 密钥的密钥状态错误表明不应删除该密钥，因为其正在用于加密，或者其是解密所必需的密钥。要重新启用 KMS 密钥，请取消计划的删除，然后[启用密钥](enabling-keys.md)。有关更多信息，请参阅 [计划密钥删除](deleting-keys-scheduling-key-deletion.md)。
## 解密错误
**异常**：`KMSInvalidStateException`
当使用外部[密钥存储库中的 KMS 密钥执行解](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html)密操作失败时，将 AWS KMS 返回加密操作用于处理外部密钥存储库上所有外部配置错误和连接状态错误的标准`KMSInvalidStateException`。此错误消息指示该问题。
要解密使用 [双重加密](keystore-external.md#concept-double-encryption) 进行加密的加密文字，外部密钥管理器应首先使用外部密钥解密加密文字的外层。然后 AWS KMS 使用 KMS AWS KMS 密钥中的密钥材料来解密密文的内层。无效或损坏的加密文字可能会被外部密钥管理器或 AWS KMS拒绝。
解密失败时，会随 `KMSInvalidStateException` 出现以下错误消息。它表示请求中的加密文字或可选加密上下文存在问题。
| |
| --- |
| 外部密钥存储代理拒绝了该请求，因为指定的加密文字或其他经过身份验证的数据已损坏、丢失或无效。 |
+ 当外部密钥存储代理或外部密钥管理器报告密文或其加密上下文无效时，通常表示发送到的请求中的密文或加密上下文存在问题。`Decrypt` AWS KMS对于`Decrypt`操作， AWS KMS 向代理发送它在请求中收到的相同密文和加密上下文。`Decrypt`
此错误可能由传输过程中的网络问题引起，例如位反转。重试 `Decrypt` 请求。如果问题仍然存在，请验证加密文字是否未被更改或损坏。此外，请验证`Decrypt`请求中的加密上下文是否与加密数据的请求中的加密上下文 AWS KMS 相匹配。
| |
| --- |
| 外部密钥存储代理提交解密的加密文字或加密上下文已损坏、丢失或无效。 |
+ AWS KMS 拒绝从代理收到的密文时，表示外部密钥管理器或代理向其返回了无效或损坏的密文。 AWS KMS
此错误可能由传输过程中的网络问题引起，例如位反转。重试 `Decrypt` 请求。如果问题仍然存在，请验证外部密钥管理器是否运行正常，并且外部密钥存储代理在返回外部密钥管理器之前不会更改从外部密钥管理器接收的密文。 AWS KMS
## 外部密钥错误
[外部密钥](keystore-external.md#concept-external-key)是外部密钥管理器中的加密密钥，用作 KMS 密钥的外部密钥材料。 AWS KMS 无法直接访问外部密钥。其必须要求外部密钥管理器（通过外部密钥存储代理）使用外部密钥来加密数据或解密加密文字。
在外部密钥存储中创建 KMS 密钥时，您可以在其外部密钥管理器中指定外部密钥的 ID。创建 KMS 密钥后，您无法更改外部密钥 ID。为防止 KMS 密钥出现问题，`CreateKey` 操作会要求外部密钥存储代理验证外部密钥的 ID 和配置。如果外部密钥不[符合与 KMS 密钥一起使用的要求](create-xks-keys.md#xks-key-requirements)，则 `CreateKey` 操作将失败，并显示说明问题的异常和错误消息。
但是，在创建 KMS 密钥后，可能会出现问题。如果加密操作因外部密钥问题而失败，则此操作将会失败并返回 `KMSInvalidStateException`，以及一条包含说明问题的错误消息。
### CreateKey 外部密钥错误
**异常**：`XksKeyAlreadyInUseException`、`XksKeyNotFoundException`、`XksKeyInvalidConfigurationException`
该[CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html)操作会尝试验证您在外部密钥 ID（控制台）或`XksKeyId`（API）参数中提供的**外部密钥的 ID** 和属性。这种做法是为了在您尝试结合使用 KMS 密钥和外部密钥之前及早发现错误。
**正在使用外部密钥**
外部密钥存储中的每个 KMS 密钥都必须使用不同的外部密钥。当`CreateKey`识别出 KMS 密钥的外部密钥 ID (XksKeyId) 在外部密钥存储中不是唯一的，则会失败，并显示为`XksKeyAlreadyInUseException`。
如果您 IDs 对同一个外部密钥使用多个外键，则`CreateKey`无法识别重复的外键。但是，具有相同外部密钥的 KMS 密钥不可互操作，因为它们具有不同的 AWS KMS 密钥材料和元数据。
**未找到外部密钥**
当外部密钥存储代理报告无法使用 KMS 密钥的外部密钥 ID (XksKeyId) 找到外部密钥时，`CreateKey`操作将失败`XksKeyNotFoundException`并返回以下错误消息。
| |
| --- |
| 外部密钥存储代理拒绝了该请求，因为其无法找到外部密钥。 |
出现此错误可能的原因如下：
+ KMS 密钥的外部密钥（`XksKeyId`）ID 可能无效。要查找外部密钥代理用于识别外部密钥的 ID，请参阅外部密钥存储代理或外部密钥管理器文档。
+ 外部密钥可能已从您的外部密钥管理器中删除。要进行调查，请使用外部密钥管理器工具。如果外部密钥已永久删除，请将其他外部密钥与 KMS 密钥结合使用。有关外部密钥的列表或要求，请参阅 [外部密钥存储中 KMS 密钥的要求](create-xks-keys.md#xks-key-requirements)。
**未符合外部密钥要求**
当外部密钥存储代理报告外部密钥不 [符合要求](create-xks-keys.md#xks-key-requirements)，无法与 KMS 密钥一起使用时，`CreateKey` 操作将会失败并返回 `XksKeyInvalidConfigurationException`，以及如下错误消息中的一条。
| |
| --- |
| 外部密钥的密钥规格必须为 AES\$1256。指定外部密钥的密钥规格为。 |
+ 外部密钥必须是 256 位对称加密密钥，密钥规格为 AES\$1256。如果指定的外部密钥是不同的类型，请指定符合此要求的外部密钥的 ID。
| |
| --- |
| 外部密钥的状态必须为“ENABLED”（已启用）。指定外部密钥的状态为。 |
+ 必须在外部密钥管理器中启用外部密钥。如果未启用指定的外部密钥，请使用外部密钥管理器工具将其启用，或指定已启用的外部密钥。
| |
| --- |
| 外部密钥的密钥用法必须包括“ENCRYPT”（加密）和“DECRYPT”（解密）。指定外部密钥的密钥用法为 < key-usage >。 |
+ 必须在外部密钥管理器中配置外部密钥以进行加密和解密。如果指定的外部密钥不包括这些操作，请使用外部密钥管理器工具更改操作，或指定其他外部密钥。
### 外部密钥的加密操作错误
**异常**：`KMSInvalidStateException`
当外部密钥存储代理找不到与 KMS 密钥关联的外部密钥，或者外部密钥不[符合与 KMS 密钥一起使用的要求](create-xks-keys.md#xks-key-requirements)时，加密操作将失败。
在加密操作期间检测到的外部密钥问题比在创建 KMS 密钥之前检测到的外部密钥问题更难解决。创建 KMS 密钥后，您无法更改外部密钥 ID。如果 KMS 密钥尚未加密任何数据，则可以删除 KMS 密钥并使用其他外部密钥 ID 创建一个新密钥。但是，使用 KMS 密钥生成的密文无法被任何其他 KMS 密钥解密，即使是具有相同外部密钥的密钥也是如此，因为密钥将具有不同的密钥元数据和不同的密钥材料。 AWS KMS 相反，应尽可能使用外部密钥管理器工具来解决外部密钥的问题。
当外部密钥存储代理报告外部密钥问题时，加密操作会返回 `KMSInvalidStateException`，以及一条说明该问题的错误消息题。
**未找到外部密钥**
当外部密钥存储代理报告无法使用 KMS 密钥的外部密钥 ID (XksKeyId) 找到外部密钥时，加密操作会返回`KMSInvalidStateException`带有以下错误消息的。
| |
| --- |
| 外部密钥存储代理拒绝了该请求，因为其无法找到外部密钥。 |
出现此错误可能的原因如下：
+ KMS 密钥的外部密钥（`XksKeyId`）ID 不再有效。
要查找与您的 KMS 密钥关联的外部密钥 ID，请[查看 KMS 密钥的详细信息](identify-key-types.md#view-xks-key)。要查找外部密钥代理用于识别外部密钥的 ID，请参阅外部密钥存储代理或外部密钥管理器文档。
AWS KMS 在外部密钥存储中创建 KMS 密钥时会验证外部密钥 ID。但是，ID 可能会失效，尤其是在外部密钥 ID 值是别名或可变名称的情况下。您无法更改与现有 KMS 密钥关联的外部密钥 ID。要对通过 KMS 密钥加密的任何加密文字进行解密，必须将外部密钥与现有外部密钥 ID 重新关联。
如果您尚未使用 KMS 密钥加密数据，则可以使用有效的外部密钥 ID 创建新的 KMS 密钥。但是，如果您已使用 KMS 密钥生成加密文字，则即使使用相同的外部密钥，也无法使用任何其他 KMS 密钥来对加密文字进行解密。
+ 外部密钥可能已从您的外部密钥管理器中删除。要进行调查，请使用外部密钥管理器工具。如果可能，请尝试从外部密钥管理器的副本或备份中[恢复密钥材料](fix-keystore.md#fix-keystore-recover-backing-key)。如果外部密钥已永久删除，则以关联的 KMS 密钥加密的任何加密文字都将无法恢复。
**外部密钥配置错误**
当外部密钥存储代理报告外部密钥不 [符合要求](create-xks-keys.md#xks-key-requirements)，不能与 KMS 密钥一起使用时，加密操作将返回 `KMSInvalidStateException`，以及如下错误消息中的一条。
| |
| --- |
| 外部密钥存储代理拒绝了该请求，因为外部密钥不支持所请求的操作。 |
+ 外部密钥必须同时支持加密和解密。如果密钥用法不包括加密和解密，请使用外部密钥管理器工具更改密钥用法。
| |
| --- |
| 外部密钥存储代理拒绝了该请求，因为该外部密钥未在外部密钥管理器中启用。 |
+ 外部密钥必须在外部密钥管理器中启用并处于可用状态。如果外部密钥的状态不是 `Enabled`，请使用外部密钥管理器工具将其启用。
## 代理问题
**例外：**
`CustomKeyStoreInvalidStateException`（`CreateKey`）、`KMSInvalidStateException`（加密操作）、`UnsupportedOperationException`、`XksProxyUriUnreachableException`、`XksProxyInvalidResponseException`（管理操作，`CreateKey` 除外）
外部密钥存储代理调解 AWS KMS 和外部密钥管理器之间的所有通信。它将通用 AWS KMS 请求转换为您的外部密钥管理器可以理解的格式。如果外部密钥存储代理不符合[AWS KMS 外部密钥存储代理 API 规范](https://github.com/aws/aws-kms-xksproxy-api-spec/)，或者运行不正常或无法与之通信 AWS KMS，则您将无法在外部密钥存储中创建或使用 KMS 密钥。
尽管许多错误都提到了外部密钥存储代理（因其在外部密钥存储架构中起着关键作用），但这些问题可能源于外部密钥管理器或外部密钥。
本节中的问题与外部密钥存储代理的设计或运行问题有关。要解决这些问题，可能需要更改代理软件。请咨询您的代理管理员。为帮助解决代理问题， AWS KMS 提供 [XKS 代理测试客户端](https://github.com/aws-samples/aws-kms-xksproxy-test-client)，这是一个开源测试客户端，可用于验证您的外部密钥存储代理是否符合 [AWS KMS 外部密钥存储代理 API 规范](https://github.com/aws/aws-kms-xksproxy-api-spec/)。
| |
| --- |
| `CustomKeyStoreInvalidStateException`、`KMSInvalidStateException` 或 `XksProxyUriUnreachableException`外部密钥存储代理运行状况不佳。如果您反复看到此消息，请通知您的外部密钥存储代理管理员。 |
+ 此错误可能表示外部密钥存储代理存在运行问题或软件错误。您可以找到生成每个错误的 AWS KMS API 操作的 CloudTrail 日志条目。重试该操作可能会解决此错误。但是，如果问题仍然存在，请通知您的外部密钥存储代理管理员。
+ 当外部密钥存储代理报告（在[GetHealthStatus](keystore-external.md#concept-proxy-apis)响应中）所有外部密钥管理器实例均为外部密钥管理器实例时`UNAVAILABLE`，尝试创建或更新外部密钥存储将失败，但会出现此异常。如果此错误仍然存在，请查阅您的外部密钥管理器文档。
| |
| --- |
| `CustomKeyStoreInvalidStateException`、`KMSInvalidStateException` 或 `XksProxyInvalidResponseException`AWS KMS 无法解释来自外部密钥存储代理的响应。如果您反复看到此错误，请咨询您的外部密钥存储代理管理员。 |
+ AWS KMS 当代理返回 AWS KMS 无法解析或解释的未定义响应时，操作会生成此异常。此错误可能由于暂时的外部问题或偶然的网络错误而偶尔发生。但是，如果此错误持续存在，则可能表明外部密钥存储代理不符合 [AWS KMS 外部密钥存储代理 API 规范](https://github.com/aws/aws-kms-xksproxy-api-spec/)。通知您的外部密钥存储管理员或供应商。
| |
| --- |
| `CustomKeyStoreInvalidStateException`、`KMSInvalidStateException` 或 `UnsupportedOperationException` 外部密钥存储代理拒绝了该请求，因为其不支持所请求的加密操作。 |
+ 外部密钥存储代理应支持《[AWS KMS 外部密钥存储[代](keystore-external.md#concept-proxy-apis)理 API 规范》中 APIs定义的所有代理](https://github.com/aws/aws-kms-xksproxy-api-spec/)。此错误表示代理不支持与请求相关的操作。通知您的外部密钥存储管理员或供应商。
## 代理授权问题
**异常**：`CustomKeyStoreInvalidStateException`、`KMSInvalidStateException`
一些外部密钥存储代理针对其外部密钥的使用执行授权要求。允许（但并非必需）外部密钥存储代理设计并实施授权方案，以允许特定用户在特定条件下请求特定操作。例如，代理可能允许用户使用特定的外部密钥进行加密，但不允许使用该外部密钥进行解密。有关更多信息，请参阅 [外部密钥存储代理授权（可选）](authorize-xks-key-store.md#xks-proxy-authorization)。
代理授权基于其对代理的请求中 AWS KMS 包含的元数据。仅当请求来自 VPC 端点且调用者与 KMS 密钥位于同一个账户时，`awsSourceVpc` 和 `awsSourceVpce` 字段才包含在元数据中。
```
"requestMetadata": {
"awsPrincipalArn": string,
"awsSourceVpc": string, // optional
"awsSourceVpce": string, // optional
"kmsKeyArn": string,
"kmsOperation": string,
"kmsRequestId": string,
"kmsViaService": string // optional
}
```
当代理因授权失败而拒绝请求时，相关 AWS KMS 操作将失败。 `CreateKey`返回`CustomKeyStoreInvalidStateException`。 AWS KMS 加密操作返回`KMSInvalidStateException`。两者都使用以下错误消息：
| |
| --- |
| 外部密钥存储代理拒绝对该操作的访问。请验证用户和外部密钥是否均已获得执行此操作的授权，然后重试请求。 |
+ 要解决错误，请使用外部密钥管理器或外部密钥存储代理工具来确定授权失败的原因。然后，更新导致未经授权的请求的过程，或使用外部密钥存储代理工具更新授权策略。您无法在 AWS KMS中解决此错误。