本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 密钥存储
*密钥存储*是用于存储和使用加密密钥的安全位置。中的默认密钥存储区 AWS KMS 还支持生成和管理其存储的密钥的方法。默认情况下，您在中创建的加密密钥材料在硬件安全模块 (HSMs) 中生成并受其保护，这些模块 AWS KMS 是 [FIPS 140-3 加密](https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/4884)模块验证程序。 AWS KMS keys 您的 KMS 密钥的密钥材料永远不会留下 HSMs 未加密的内容。
AWS KMS 支持多种类型的密钥存储，以便在用于创建和管理加密密钥时保护您的密钥材料。 AWS KMS 提供的所有密钥存储选项 AWS KMS 均在 FIPS 140-3 安全等级 3 下持续验证，旨在防止任何人（包括 AWS 操作员）在未经您许可的情况下访问或使用您的纯文本密钥。
## AWS KMS 标准密钥库
默认情况下，KMS 密钥是使用标准 AWS KMS HSM 创建的。从您的角度来看，这种 HSM 类型可以看作是一个多租户队伍 HSMs ，它允许最具可扩展性、最低成本和最容易管理的密钥存储。如果您要创建一个用于一个或多个密钥的 KMS 密钥， AWS 服务 以便服务可以代表您加密您的数据，则您将创建一个对称密钥。如果您在自己的应用程序设计中使用 KMS 密钥，则可以选择创建对称加密密钥、非对称密钥或 HMAC 密钥。
在标准密钥存储选项中， AWS KMS 创建您的密钥，然后使用服务内部管理的密钥对其进行加密。然后，您密钥的加密版本的多个副本将存储在系统中，系统旨在保障持久性。在标准密钥库类型中生成和保护密钥材料可让您充分利用密 AWS 钥库的可扩展性、可用性和耐久性， AWS KMS 同时将操作负担和成本降至最低。
## AWS KMS 带有导入密钥材料的标准密钥库
您可以选择将密钥材料导入并存储给定密钥的唯一副本，从而生成自己的 256 位对称加密密钥 AWS KMS、RSA 或椭圆曲线 (ECC) 密钥或基于哈希的消息身份验证码 (HMAC) 密钥，并将其应用于 KMS 密钥标识符 (KeyID)，然后将其应用于 KMS 密钥标识符 (KeyID)。 AWS KMS 这有时被称为*自带密钥*（BYOK）。必须使用颁发的公钥 AWS KMS、支持的加密封装算法和提供的基于时间的导入令牌来保护从本地密钥管理系统导入的密钥材料。 AWS KMS此过程将验证您的加密导入密钥在离开您的环境后，是否只能通过 AWS KMS HSM 解密。
如果您对生成密钥的系统有特定的要求，或者想要在外部保存密钥副本 AWS 作为备份，则导入的密钥材料可能会很有用。请注意，您需要对导入的密钥材料的整体可用性和持久性负责。虽然 AWS KMS 有您导入的密钥的副本，并且可以在您需要时保持高度可用，但导入的密钥提供了一个特殊的删除API — DeleteImportedKeyMaterial。此 API 将立即删除 AWS KMS 已导入的密钥材料的所有副本，但无法选择恢复密钥。 AWS 此外，您还可以为导入的密钥设置过期时间，过期后密钥将无法使用。要使密钥在中再次有用 AWS KMS，您必须重新导入密钥材料并将其分配给相同的 keyID。这种针对导入密钥的删除操作与代表您 AWS KMS 生成和存储的标准密钥不同。在标准情况下，密钥删除过程有一个强制性的等待期，在此期间，计划删除的密钥将首先被禁止使用。此操作允许您在可能需要该密钥才能访问数据的任何应用程序或 AWS 服务的日志中查看访问被拒绝的错误。如果您看到此类访问请求，可以选择取消计划删除并重新启用该密钥。经过可配置的等待期（7 到 30 天）后，KMS 才会真正删除密钥材料、keyID 以及与密钥关联的所有元数据。有关可用性和持久性的更多信息，请参阅《AWS KMS 开发人员指南》中的[保护导入的密钥材料](import-keys-protect.md)**。
导入的密钥材料还有一些其他限制需要注意。由于 AWS KMS 无法生成新的密钥材料，因此无法对导入密钥配置自动轮换。您需要使用新的 keyId 创建新 KMS 密钥，然后导入新的密钥材料才能实现有效的轮换。此外，在导入的对称密钥 AWS KMS 下创建的密文无法使用外部的本地密钥副本轻松解密。 AWS这是因为使用的经过身份验证的加密格式会将额外的元数据 AWS KMS 附加到密文中，以便在解密操作期间保证密文是由之前的加密操作下预期的 KMS 密钥创建的。大多数外部加密系统不了解如何通过解析这些元数据来获得原始加密文字，从而使用其对称密钥副本。在导入的非对称密钥（例如 RSA 或 ECC）下创建的密文可以在密钥的 AWS KMS 匹配（公共或私有）部分之外使用，因为没有向密文添加额外的元数据。 AWS KMS
## AWS KMS 自定义密钥库
但是，如果您需要对的更多控制 HSMs，则可以创建自定义密钥库。
*自定义密钥存储库*是内部的密钥存储库 AWS KMS ，由外部的密钥管理器提供支持 AWS KMS，您拥有并管理该密钥管理器。自定义密钥存储区将便捷而全面的密钥管理界面 AWS KMS 与拥有和控制密钥材料和加密操作的能力相结合。在自定义密钥存储中使用 KMS 密钥时，加密操作实际上是通过您的密钥管理器使用您的加密密钥来执行。因此，您对加密密钥的可用性和持久性以及其操作承担更多责任。 HSMs
拥有您的密钥 HSMs 可能有助于满足某些监管要求，这些要求尚不允许多租户 Web 服务（例如标准 KMS 密钥存储）保存您的加密密钥。自定义密钥存储并不比使用 AWS-managed 的 KMS 密钥存储更安全 HSMs，但它们具有不同（且更高）的管理和成本影响。因此，您对加密密钥的可用性和持久性以及其操作承担更多责任。 HSMs无论您是使用标准密钥存储库 AWS KMS HSMs 还是自定义密钥存储库，该服务的设计都确保任何人（包括 AWS 员工）都无法在未经您许可的情况下检索或使用您的纯文本密钥。 AWS KMS 支持两种类型的自定义密钥存储库，即 AWS CloudHSM 密钥存储库和外部密钥存储库。
**不支持的功能**
AWS KMS 不支持自定义密钥存储库中的以下功能。
+ [非对称 KMS 密钥](symmetric-asymmetric.md)
+ [HMAC KMS 密钥](hmac.md)
+ [具有导入密钥材料的 KMS 密钥](importing-keys.md)
+ [自动密钥轮换](rotate-keys.md)
+ [多区域密钥](multi-region-keys-overview.md)
### AWS CloudHSM 钥匙库
您可以在密钥库中创建 KM [AWS CloudHSM](https://aws.amazon.com/kms/pricing/)S 密钥，在您拥有和管理的 AWS CloudHSM 集群中生成、存储和使用根用户密钥。使用密钥进行某些加密操作的请求会被转发到您的 AWS CloudHSM 集群以执行该操作。 AWS KMS 虽然集 AWS CloudHSM 群由托管 AWS，但它是由您直接管理和操作的单租户解决方案。 AWS CloudHSM 集群中 KMS 密钥的大部分可用性和性能由您拥有。要查看 AWS CloudHSM 自定义密钥库是否适合您的要求，请阅读[AWS KMS 自定义密钥存储是否适合您？](https://aws.amazon.com/blogs/security/are-kms-custom-key-stores-right-for-you/) 在 AWS 安全博客上。
### 外部密钥存储
您可以配置 AWS KMS 为使用外部密钥存储 (XKS)，在外部的密钥管理系统中生成、存储和使用根用户密钥。 AWS 云向 AWS KMS 提出的使用密钥进行某些加密操作的请求将转到您的外部托管系统以执行操作。具体而言，请求会被转发到您网络中的 XKS 代理，然后该代理会将请求转发到您使用的任何加密系统。XKS 代理是开源规范，任何人都可以集成。许多商业密钥管理供应商都支持 XKS 代理规范。由于外部密钥存储由您或第三方托管，因此您负责系统中密钥的所有可用性、持久性和性能。要查看外部密钥存储是否符合您的要求，请阅读 AWS 新闻博客上的[宣布 AWS KMS 外部密钥存储 (XKS)](https://aws.amazon.com/blogs/aws/announcing-aws-kms-external-key-store-xks/)。
# AWS CloudHSM 钥匙库
密 AWS CloudHSM 钥库是由集[AWS CloudHSM 群](https://docs.aws.amazon.com/cloudhsm/latest/userguide/)支持的[自定义密钥存储库](key-store-overview.md#custom-key-store-overview)。在自定义密钥存储 AWS KMS key 中创建时， AWS KMS 会在您拥有和管理的 AWS CloudHSM 集群中为 KMS 密钥生成和存储不可提取的密钥材料。当您在自定义密钥存储中使用 KMS 密钥时，[加密操作](manage-cmk-keystore.md#use-cmk-keystore)将在集群 HSMs 中执行。此功能结合了的便利性和广泛集 AWS KMS 成，并增加了对 AWS CloudHSM 集群的控制 AWS 账户。
AWS KMS 为创建、使用和管理自定义密钥存储库提供全面的控制台和 API 支持。在自定义密钥存储中使用 KMS 密钥的方式，与使用任何 KMS 密钥相同。例如，您可以使用 KMS 密钥生成数据密钥和加密数据。您还可以将自定义密钥存储库中的 KMS 密钥与支持客户托管密钥的 AWS 服务一起使用。
**我是否需要自定义密钥存储？**
对于大多数用户来说，由 [FIPS 140-3 验证的加密模块](https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/4884)保护的默认 AWS KMS 密钥库可以满足他们的安全要求。无需添加额外的维护责任层或额外服务的依赖项。
但是，如果您的组织具有以下任何要求，则可能要考虑创建自定义密钥存储：
+ 在单租户 HSM 或您可以直接控制的 HSM 中，您有明确要求保护的密钥。
+ 您需要能够立即从中移除密钥材料 AWS KMS。
+ 您需要能够独立于 AWS KMS 或审核密钥的所有使用情况 AWS CloudTrail。
**自定义密钥存储如何工作？**
每个自定义密钥存储库都与您的集 AWS CloudHSM 群相关联 AWS 账户。当您将自定义密钥库连接到其集群时， AWS KMS 会创建支持该连接的网络基础架构。然后，它使用集群中[专用加密用户的](#concept-kmsuser)凭据登录到集群中的密钥 AWS CloudHSM 客户端。
您可以在中创建和管理您的自定义密钥存储， AWS KMS 并在中创建和管理您的 HSM 集群。 AWS CloudHSM在 AWS KMS 自定义密钥存储 AWS KMS keys 中创建时，可以在中查看和管理 KMS 密钥 AWS KMS。但是，您还可以在 AWS CloudHSM中查看和管理其密钥材料，就像您对集群中的其他密钥执行该操作一样。
![\[在自定义密钥存储中管理 KMS 密钥\]](http://docs.aws.amazon.com/zh_cn/kms/latest/developerguide/images/kms-hsm-view.png)
您可以使用自定义密钥存储库 AWS KMS 中生成的[密钥材料创建对称加密 KMS](create-cmk-keystore.md) 密钥。然后，使用与在密钥库中用于密钥库中的 KMS 密钥相同的方法来查看和管理自定义密钥存储区中的 AWS KMS KMS 密钥。您可以使用 IAM 和密钥策略控制访问，创建标签和别名，启用和禁用 KMS 密钥，以及计划密钥删除。您可以使用 KMS 密钥进行[加密操作](manage-cmk-keystore.md#use-cmk-keystore)，并将其与集成的 AWS 服务一起 AWS KMS使用。
此外，您可以完全控制 AWS CloudHSM 集群，包括创建、删除 HSMs 和管理备份。您可以使用 AWS CloudHSM 客户端和支持的软件库来查看、审计和管理 KMS 密钥的密钥材料。当自定义密钥存储断开连接时， AWS KMS 无法对其进行访问，用户也无法使用自定义密钥存储区中的 KMS 密钥进行加密操作。增加的控制层使自定义密钥存储成为需要它的组织的强大解决方案。
**从何处开始？**
要创建和管理 AWS CloudHSM 密钥库，您可以使用 AWS KMS 和的功能 AWS CloudHSM。
1. 从... 开始 AWS CloudHSM。[创建活动 AWS CloudHSM 集群](https://docs.aws.amazon.com/cloudhsm/latest/userguide/getting-started.html)或选择现有集群。集群在不同的可用区中必须至少有两个 HSMs 处于活动状态。然后，在该集群中为 AWS KMS创建一个[专用加密用户 (CU) 账户](#concept-kmsuser)。
1. 在中 AWS KMS，[创建与所选 AWS CloudHSM 集群关联的自定义密钥库](create-keystore.md)。 AWS KMS 提供了一个完整的管理界面，允许您创建、查看、编辑和删除自定义密钥库。
1. 准备好使用自定义密钥库时，请[将其连接到其关联的 AWS CloudHSM 集群](connect-keystore.md)。 AWS KMS 创建支持连接所需的网络基础架构。之后，它将使用专用加密用户账户凭证登录集群，以便它可以在集群中生成和管理密钥材料。
1. 现在，您可以[在自定义密钥存储中创建对称加密 KMS 密钥](create-cmk-keystore.md)。在创建 KMS 密钥时指定自定义密钥存储。
如果您在任何时候遇到困难，都可以在[对自定义密钥存储进行故障排除](fix-keystore.md)主题中查找帮助。如果您的问题未得到解答，请使用本指南的每页底部的反馈链接或在 [AWS Key Management Service 开发论坛](https://repost.aws/tags/TAMC3vcPOPTF-rPAHZVRj1PQ/aws-key-management-service)上发布问题。
**配额**
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 请求配额。 AWS CloudHSM
**定价**
有关 AWS KMS 自定义密钥存储库和客户托管密钥在自定义密钥存储库中的成本的信息，请参阅[AWS Key Management Service 定价](https://aws.amazon.com/kms/pricing/)。有关 AWS CloudHSM 集群和成本的信息 HSMs，请参阅[AWS CloudHSM 定价](https://aws.amazon.com/cloudhsm/pricing/)。
**区域**
AWS KMS 支持除亚太地区（墨尔本）、中国（北京）、中国（宁夏）和欧洲（西班牙）以外的所有 AWS 区域 地区的 AWS CloudHSM 密钥存储。 AWS KMS
**不支持的功能**
AWS KMS 不支持自定义密钥存储库中的以下功能。
+ [非对称 KMS 密钥](symmetric-asymmetric.md)
+ [HMAC KMS 密钥](hmac.md)
+ [具有导入密钥材料的 KMS 密钥](importing-keys.md)
+ [自动密钥轮换](rotate-keys.md)
+ [多区域密钥](multi-region-keys-overview.md)
## AWS CloudHSM 关键商店概念
本主题解释了 AWS CloudHSM 密钥库中使用的一些术语和概念。
### AWS CloudHSM 钥匙库
*AWS CloudHSM 密钥库*是与您拥有和管理的 AWS CloudHSM 集群关联的[自定义密钥存储库](key-store-overview.md#custom-key-store-overview)。 AWS CloudHSM 集群由 [FIPS 140-2 或 FIPS 140-3](https://docs.aws.amazon.com/cloudhsm/latest/userguide/compliance.html) Level 3 认证的硬件安全模块 (HSMs) 提供支持。
在密钥库中创建 KMS AWS CloudHSM 密钥时， AWS KMS 会在关联的集群中生成 256 位永久性、不可导出的高级加密标准 (AES) 对称密钥。 AWS CloudHSM 这些密钥材料永远不会让你处于 HSMs 未加密状态。当您在密钥存储中使用 KMS AWS CloudHSM 密钥时，加密操作将在集群 HSMs 中执行。
AWS CloudHSM 密钥存储区将便捷而全面的密钥管理界面 AWS KMS 与您的 AWS CloudHSM 集群提供的其他控件相结合 AWS 账户。此集成功能允许您在中创建、管理和使用 KMS 密钥， AWS KMS 同时保持对存储密钥材料的完全控制，包括管理集群和备份。 HSMs HSMs您可以使用 AWS KMS 控制台和 APIs 来管理 AWS CloudHSM 密钥库及其 KMS 密钥。您还可以使用 AWS CloudHSM 控制台、 APIs、客户端软件和关联的软件库来管理关联的群集。
您可以[查看和管理](view-keystore.md)您的 AWS CloudHSM 密钥库，[编辑其属性](update-keystore.md)，以及将其与其关联的 AWS CloudHSM 集群[连接](connect-keystore.md)和[断开连接](disconnect-keystore.md)。如果您需要[删除 AWS CloudHSM 密钥存储库，则](delete-keystore.md#delete-keystore-console)必须首先通过安排删除密钥库中的 KMS 密 AWS CloudHSM 钥并等到宽限期到期来将其删除。删除 AWS CloudHSM 密钥库会从中移除资源 AWS KMS，但不会影响您的 AWS CloudHSM 集群。
### AWS CloudHSM 集群
每个 AWS CloudHSM 密钥库都与一个*AWS CloudHSM 集群*相关联。当您在 AWS CloudHSM 密钥库 AWS KMS key 中创建时， AWS KMS 会在关联的集群中创建其密钥材料。当您在 AWS CloudHSM 密钥存储中使用 KMS 密钥时，将在关联的集群中执行加密操作。
每个 AWS CloudHSM 集群只能与一个 AWS CloudHSM 密钥库相关联。您选择的集群不能与其他 AWS CloudHSM 密钥库相关联，也不能与与其他密 AWS CloudHSM 钥库关联的集群共享备份历史记录。集群必须处于初始化状态且处于活动状态，并且必须与 AWS CloudHSM 密钥库位于同一 AWS 账户 区域中。您可以创建新集群或使用现有集群。 AWS KMS 不需要集群的独占使用。要在密钥库中创建 KMS 密钥，其关联的集群必须至少包含两个处于活动状态的集群 HSMs。 AWS CloudHSM 所有其他操作都只需要一个 HSM。
您在创建 AWS CloudHSM 密钥库时指定 AWS CloudHSM 集群，并且无法对其进行更改。但是，您可以替换与原始集群共享备份历史记录的任何集群。这样，您就可以删除该集群（如有必要），然后将它替换为从其备份之一创建的集群。您可以完全控制关联的 AWS CloudHSM 集群，因此您可以管理用户和密钥、创建和删除 HSMs以及使用和管理备份。
当您准备好使用 AWS CloudHSM 密钥库时，可以将其连接到其关联的 AWS CloudHSM 集群。您可以随时连接和断开自定义密钥存储。连接自定义密钥存储后，您可以创建和使用其 KMS 密钥。断开连接后，您可以查看和管理 AWS CloudHSM 密钥库及其 KMS 密钥。但是您不能创建新的 KMS 密钥或使用密钥存储区中的 KMS 密 AWS CloudHSM 钥进行加密操作。
### `kmsuser` 加密用户
要代表您创建和管理关联 AWS CloudHSM 集群中的密钥材料，请在名为的集群中 AWS KMS 使用专用*AWS CloudHSM [加密用户](https://docs.aws.amazon.com/cloudhsm/latest/userguide/hsm-users.html#crypto-user) (CU)* `kmsuser`。`kmsuser`CU 是一个标准 CU 帐户，可自动与集群 HSMs 中的所有用户同步，并保存在集群备份中。
在创建 AWS CloudHSM 密钥库之前，请使用 CloudHSM CLI 中的[https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-user-cloudhsm-cli.html](https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-user-cloudhsm-cli.html)命令在 AWS CloudHSM 集群中创建 C [`kmsuser`U 账户](create-keystore.md#before-keystore)。然后，[在创建 AWS CloudHSM 密钥库](create-keystore.md)时，将`kmsuser`帐户密码提供给 AWS KMS。[连接自定义密钥存储](connect-keystore.md)库时，以 `kmsuser` CU 的身份 AWS KMS 登录集群并轮换其密码。 AWS KMS 在安全存储`kmsuser`密码之前对其进行加密。轮换密码时，新密码也会以相同的方式加密和存储。
AWS KMS `kmsuser`只要 AWS CloudHSM 密钥库已连接，就会保持登录状态。您不应将此 CU 账户用于其他目的。但是，您保留对 `kmsuser` CU 账户的最终控制权。您可以随时[查找 `kmsuser` 拥有的密钥](find-key-material.md)。必要时，您可以[将自定义密钥存储断开连接](disconnect-keystore.md)，更改 `kmsuser` 密码，[以 `kmsuser` 身份登录到集群](fix-keystore.md#fix-login-as-kmsuser)，以及查看和管理 `kmsuser` 拥有的密钥。
有关创建 `kmsuser` CU 账户的说明，请参阅[创建 `kmsuser` 加密用户](create-keystore.md#before-keystore)。
### 密钥库中的 KMS AWS CloudHSM 密钥
您可以使用 AWS KMS 或 AWS KMS API 在 AWS CloudHSM 密钥库 AWS KMS keys 中创建。您将使用对任何 KMS 密钥使用的同一方法。唯一的区别是，您必须识别 AWS CloudHSM 密钥库并指定密钥材料的来源是 AWS CloudHSM 集群。
在[密钥存储中创建 KMS AWS CloudHSM 密钥时，在中](create-cmk-keystore.md) AWS KMS 创建 KMS 密钥，它会在关联的集群中 AWS KMS 生成 256 位、永久性、不可导出的高级加密标准 (AES) 对称密钥材料。当您在加密操作中使用 AWS KMS 密钥时，该操作将使用基于集群的 AES 密钥在 AWS CloudHSM 集群中执行。尽管 AWS CloudHSM 支持不同类型的对称和非对称密钥，但密钥库仅支持 AES 对称加密 AWS CloudHSM 密钥。
您可以在 AWS KMS 控制台的密钥库中查看 KMS 密钥，并使用控制台选项显示自定义密钥存储 ID。 AWS CloudHSM 您还可以使用该[DescribeKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html)操作来查找 AWS CloudHSM 密钥库 ID 和 AWS CloudHSM 集群 ID。
密钥存储中的 KMS 密 AWS CloudHSM 钥的工作方式与中的任何 KMS 密钥相同 AWS KMS。授权用户需要相同的权限来使用和管理 KMS 密钥。您可以使用相同的控制台过程和 API 操作来查看和管理密钥库中的 KMS 密钥。 AWS CloudHSM 这包括启用和禁用 KMS 密钥、创建和使用标签和别名以及设置和更改 IAM 和密钥策略。您可以将密钥存储区中的 KMS 密 AWS CloudHSM 钥用于加密操作，并将其与支持使用客户托管密钥的[集成 AWS 服务](service-integration.md)一起使用。但是，您无法启用[自动密钥轮换或将密钥](rotate-keys.md)[材料导入密钥](importing-keys.md)存储区的 KMS AWS CloudHSM 密钥中。
您还可以使用相同的过程来[计划删除](deleting-keys.md#delete-cmk-keystore)密钥库中的 KMS AWS CloudHSM 密钥。等待期到期后，从 KMS 中 AWS KMS 删除 KMS 密钥。然后，它会尽最大努力从关联的 AWS CloudHSM 集群中删除 KMS 密钥的密钥材料。但是，您可能需要从集群及其备份中手动[删除孤立密钥材料](fix-keystore.md#fix-keystore-orphaned-key)。
# 控制对 AWS CloudHSM 密钥库的访问权限
您可以使用 IAM 策略来控制对 AWS CloudHSM 密钥库和 AWS CloudHSM 集群的访问权限。您可以使用密钥策略、IAM 策略和授权来控制对 AWS CloudHSM 密钥库 AWS KMS keys 中的的访问权限。我们建议您仅向用户、组和角色提供他们可能执行的任务所需的权限。
要支持您的 AWS CloudHSM 密钥存储， AWS KMS 需要获得有关您的 AWS CloudHSM 集群信息的权限。它还需要权限才能创建将您的 AWS CloudHSM 密钥库连接到其 AWS CloudHSM 集群的网络基础架构。要获得这些权限， AWS KMS 请在 AWS 账户中创建**AWSServiceRoleForKeyManagementServiceCustomKeyStores**服务相关角色。有关更多信息，请参阅 [授权 AWS KMS 管理 AWS CloudHSM 和 Amazon EC2 资源](authorize-kms.md)。
在设计 AWS CloudHSM 密钥库时，请确保使用和管理密钥库的委托人仅拥有他们所需的权限。以下列表描述了 AWS CloudHSM 密钥库管理员和用户所需的最低权限。
+ 创建和管理您的 AWS CloudHSM 密钥库的委托人需要以下权限才能使用 AWS CloudHSM 密钥存储库 API 操作。
+ `cloudhsm:DescribeClusters`
+ `kms:CreateCustomKeyStore`
+ `kms:ConnectCustomKeyStore`
+ `kms:DeleteCustomKeyStore`
+ `kms:DescribeCustomKeyStores`
+ `kms:DisconnectCustomKeyStore`
+ `kms:UpdateCustomKeyStore`
+ `iam:CreateServiceLinkedRole`
+ 创建和管理与您的 AWS CloudHSM 密钥库关联的 AWS CloudHSM 集群的委托人需要获得创建和初始化 AWS CloudHSM 集群的权限。这包括创建或使用亚马逊虚拟私有云 (VPC)、创建子网和创建亚马逊实例的权限。 EC2他们可能还需要创建 HSMs、删除和管理备份。有关所需权限的列表，请参阅《AWS CloudHSM User Guide》**中的 [Identity and access management for AWS CloudHSM](https://docs.aws.amazon.com/cloudhsm/latest/userguide/identity-access-management.html)。
+ AWS KMS keys 在您的 AWS CloudHSM 密钥存储中创建和管理的委托人需要与[在中创建和管理任何 KMS 密钥的 AWS KMS用户相同的权限](create-keys.md#create-key-permissions)。[密钥存储中 KMS 密钥的默认 AWS CloudHSM 密钥策略](key-policy-default.md)与中 KMS 密钥的默认密钥策略相同 AWS KMS。[基于属性的访问控制](abac.md) (ABAC) 使用标签和别名来控制对 KMS 密钥的访问，也对密钥存储中的 KMS 密钥有效。 AWS CloudHSM
+ [使用密钥存储区中的 KMS 密钥进行[加密操作](manage-cmk-keystore.md#use-cmk-keystore)的委托人需要获得权限才能使用 KMS 密钥执行加密操作，例如 KMS: decrypt。 AWS CloudHSM](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html)您可以在密钥策略或 IAM policy 中提供这些权限。但是，他们不需要任何其他权限即可在密钥库中使用 KMS AWS CloudHSM 密钥。
# 创建密 AWS CloudHSM 钥库
您可以在自己的账户中创建一个或多个 AWS CloudHSM 密钥库。每个 AWS CloudHSM 密钥库都与同一个 AWS 账户 和区域中的一个 AWS CloudHSM 集群相关联。在创建 AWS CloudHSM 密钥存储之前，您需要[汇编先决条件](#before-keystore)。然后，在使用 AWS CloudHSM 密钥库之前，必须[将其连接到](connect-keystore.md)其 AWS CloudHSM 集群。
**注意**
KMS 无法 IPv6 与 AWS CloudHSM 密钥存储库进行通信。
如果您尝试创建与现有*已断开连接*的 AWS CloudHSM 密钥存储具有相同属性值的 AWS CloudHSM 密钥存储库，则 AWS KMS 不会创建新的 AWS CloudHSM 密钥存储，也不会引发异常或显示错误。相反，它会将重复 AWS KMS 识别为重试可能产生的结果，并返回现有 AWS CloudHSM 密钥库的 ID。
您不必立即连接 AWS CloudHSM 密钥库。您可以将它保持断开状态，直到您准备好使用它为止。但是，要验证它是否已正确配置，您可能需要[连接它](connect-keystore.md)，[查看其连接状态](view-keystore.md)，然后[断开它](disconnect-keystore.md)。
**Topics**
+ [汇编先决条件](#before-keystore)
+ [创建新的 AWS CloudHSM 密钥库](#create-hsm-keystore)
## 汇编先决条件
每个 AWS CloudHSM 密钥库都由一个 AWS CloudHSM 集群提供支持。要创建 AWS CloudHSM 密钥存储库，必须指定尚未与其他密钥库关联的活动 AWS CloudHSM 集群。您还需要在集群中创建一个专用的加密用户 (CU) HSMs ，该用户 AWS KMS 可用于代表您创建和管理密钥。
在创建 AWS CloudHSM 密钥库之前，请执行以下操作：
**选择一个 AWS CloudHSM 集群**
每个 AWS CloudHSM 密钥库[恰好与一个 AWS CloudHSM 集群相关联](keystore-cloudhsm.md#concept-cluster)。当您在 AWS CloudHSM 密钥存储 AWS KMS keys 中创建时， AWS KMS 会在中创建 KMS 密钥元数据，例如 ID 和 Amazon 资源名称 (ARN)。 AWS KMS然后，它会在关联集群 HSMs 中创建密钥材料。您可以[创建新 AWS CloudHSM](https://docs.aws.amazon.com/cloudhsm/latest/userguide/getting-started.html)集群或使用现有集群。 AWS KMS 不需要对集群的独占访问权限。
您选择的 AWS CloudHSM 集群与 AWS CloudHSM 密钥库永久关联。创建 AWS CloudHSM 密钥库后，您可以[更改关联集群的集群 ID](update-keystore.md)，但您指定的集群必须与原始集群共享备份历史记录。要使用不相关的集群，您需要创建一个新的 AWS CloudHSM 密钥库。
您选择的 AWS CloudHSM 集群必须具有以下特征：
+ **集群必须处于活动状态**。
您必须创建集群，对其进行初始化，安装适用于您的平台的 AWS CloudHSM 客户端软件，然后激活集群。有关详细说明，请参阅《AWS CloudHSM User Guide》**中的 [Getting started with AWS CloudHSM](https://docs.aws.amazon.com/cloudhsm/latest/userguide/getting-started.html)。
+ **未启用双向 TLS（mTLS）。**
KMS 不支持将 mTLS 用于集群。务必不要启用此设置。
+ **集群必须与 AWS CloudHSM 密钥库位于同一个账户和区域**中。您不能将一个区域中的 AWS CloudHSM 密钥存储库与另一个区域的集群相关联。要在多个区域创建密钥基础设施，您必须在每个区域中创建 AWS CloudHSM 密钥存储和集群。
+ **集群不能与同一账户和区域中的其他自定义密钥存储关联**。账户和区域中的每个 AWS CloudHSM 密钥存储区都必须与不同的集 AWS CloudHSM 群相关联。您无法指定已与自定义密钥存储关联的集群，也无法指定与关联集群共享备份历史记录的集群。共享备份历史记录的集群具有相同的集群证书。要查看集群的集群证书，请使用 AWS CloudHSM 控制台或[DescribeClusters](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DescribeClusters.html)操作。
如果您[将 AWS CloudHSM 集群备份到不同的区域](https://docs.aws.amazon.com/cloudhsm/latest/userguide/copy-backup-to-region.html)，则它将被视为一个不同的集群，并且您可以将备份关联到其区域中的自定义密钥存储。但是，两个自定义密钥存储库中的 KMS 密钥不可互操作，即使它们具有相同的支持密钥。 AWS KMS 将元数据绑定到密文，因此只能通过加密密文的 KMS 密钥对其进行解密。
+ 必须在区域中的**至少两个可用区**中为集群配置[私有子网](https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-subnets.html)。由于 AWS CloudHSM 并非所有可用区都支持私有子网，因此我们建议您在该区域的所有可用区中创建私有子网。您无法为现有集群重新配置子网，但可以[从备份创建集群](https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-cluster-from-backup.html)（在集群配置中具有不同的子网）。
**重要**
创建 AWS CloudHSM 密钥库后，请勿删除为其 AWS CloudHSM 集群配置的任何私有子网。如果在群集配置中找 AWS KMS 不到所有子网，则尝试[连接到自定义密钥库会](connect-keystore.md)失败，并显示`SUBNET_NOT_FOUND`连接错误状态。有关更多信息，请参阅 [如何修复连接故障](fix-keystore.md#fix-keystore-failed)。
+ [集群的安全组](https://docs.aws.amazon.com/cloudhsm/latest/userguide/configure-sg.html) (`cloudhsm-cluster--sg`) 必须包含允许端口 2223-2225 上的 TCP 流量的入站规则和出站规则。 IPv4入站规则中的 **Source (源)** 和出站规则中的 **Destination (目标)** 必须匹配安全组 ID。在创建集群时，默认情况下会设置这些规则。请勿删除或更改它们。
+ **集群必须至少包含两个 HSMs处于**不同可用区域的活动集群。要验证数量 HSMs，请使用 AWS CloudHSM 控制台或[DescribeClusters](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DescribeClusters.html)操作。如有必要，您可以[添加 HSM](https://docs.aws.amazon.com/cloudhsm/latest/userguide/add-remove-hsm.html#add-hsm)。
**查找信任锚点证书**
创建自定义密钥存储库时，必须将 AWS CloudHSM 集群的信任锚证书上传到 AWS KMS。 AWS KMS 需要信任锚证书才能将 AWS CloudHSM 密钥库连接到其关联的 AWS CloudHSM 集群。
每个活动 AWS CloudHSM 集群都有一个*信任锚证书*。在[初始化集群](https://docs.aws.amazon.com/cloudhsm/latest/userguide/initialize-cluster.html#sign-csr)时，您将生成此证书，将它保存在 `customerCA.crt` 文件中，并将它复制到已连接到集群的主机。
**为创建`kmsuser`加密用户 AWS KMS**
要管理您的 AWS CloudHSM 密钥存储，请 AWS KMS 登录选定集群中的[`kmsuser`加密用户](keystore-cloudhsm.md#concept-kmsuser) (CU) 账户。在创建 AWS CloudHSM 密钥库之前，必须创建 C `kmsuser` U。然后，在创建 AWS CloudHSM 密钥库时，您需要为提供密码 AWS KMS。`kmsuser`每当您将 AWS CloudHSM 密钥库连接到其关联 AWS CloudHSM 集群时，都要以身份 AWS KMS 登录`kmsuser`并轮换密码 `kmsuser`
在创建 `kmsuser` CU 时，请勿指定 `2FA` 选项。如果这样做，则 AWS KMS 无法登录，您的 AWS CloudHSM 密钥库也无法连接到此 AWS CloudHSM 集群。一旦指定 2FA，便无法撤消它。相反，您必须删除 CU 并重新创建它。
**注意**
以下过程使用 AWS CloudHSM 客户端 SDK 5 命令行工具 [CloudHSM C](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli.html) LI。CloudHSM CLI 将 `key-handle` 替换为 `key-reference`。
2025 年 1 月 1 日， AWS CloudHSM 将终止对客户端 SDK 3 命令行工具、CloudHSM 管理实用程序 (CMU) 和密钥管理实用程序 (KMU) 的支持。有关客户端 SDK 3 命令行工具和客户端 SDK 5 命令行工具之间区别的更多信息，请参阅《AWS CloudHSM 用户指南》**中的[从客户端 SDK 3 CMU 和 KMU 迁移到客户端 SDK 5 CloudHSM CLI](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-migrate-from-kmu-cmu.html)。
1. 按照《AWS CloudHSM 用户指南》**的[开始使用 CloudHSM 命令行界面（CLI）](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-getting-started.html)主题中所述的入门步骤进行操作。
1. 使用 [https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-user-cloudhsm-cli.html](https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-user-cloudhsm-cli.html) 命令创建名为 `kmsuser` 的 CU。
密码必须由 7 到 32 个字母数字字符组成。它区分大小写，并且不能包含任何特殊字符。
以下示例命令创建了一个 `kmsuser` CU。
```
aws-cloudhsm > user create --username kmsuser --role crypto-user
Enter password:
Confirm password:
{
"error_code": 0,
"data": {
"username": "kmsuser",
"role": "crypto-user"
}
}
```
## 创建新的 AWS CloudHSM 密钥库
[组装完先决条件](#before-keystore)后，可以在 AWS KMS 控制台中或使用[CreateCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateCustomKeyStore.html)操作创建新的 AWS CloudHSM 密钥存储库。
### 使用控制 AWS KMS 台
在中创建 AWS CloudHSM 密钥库时 AWS 管理控制台，可以在工作流程中添加和创建[先决条件](#before-keystore)。但是，如果您事先已汇编这些先决条件，则此过程会更快。
1. 登录 AWS 管理控制台 并在 [https://console.aws.amazon.com/km](https://console.aws.amazon.com/kms) s 处打开 AWS Key Management Service (AWS KMS) 控制台。
1. 要更改 AWS 区域，请使用页面右上角的区域选择器。
1. 在导航窗格中，选择**自定义密钥存储**、**AWS CloudHSM 密钥存储**。
1. 选择**创建密钥存储**。
1. 为自定义密钥存储输入友好名称。该名称在您账户的所有自定义密钥存储中必须具备唯一性。
**重要**
不要在此字段中包含机密或敏感信息。此字段可能会以纯文本形式显示在 CloudTrail 日志和其他输出中。
1. 为 AWS CloudHSM 密钥库选择[一个 AWS CloudHSM 集群](keystore-cloudhsm.md#concept-cluster)。或者，要创建新 AWS CloudHSM 集群，请选择**创建 AWS CloudHSM 集群**链接。
该菜单显示您的账户和地区中尚未与 AWS CloudHSM 密钥库关联的 AWS CloudHSM 集群。该集群必须[满足要求](#before-keystore)（与关联自定义密钥存储相关）。
1. 选择 **“选择文件”**，然后上传所选 AWS CloudHSM 集群的信任锚证书。这是您在[初始化集群](https://docs.aws.amazon.com/cloudhsm/latest/userguide/initialize-cluster.html#sign-csr)时创建的 `customerCA.crt` 文件。
1. 输入您在选定集群中创建的 [`kmsuser` 加密用户](keystore-cloudhsm.md#concept-kmsuser) (CU) 的密码。
1. 选择**创建**。
该过程成功后，新的 AWS CloudHSM 密钥库将出现在账户和地区的 AWS CloudHSM 密钥存储列表中。如果该过程失败，则会显示一条错误消息，描述问题并提供有关如何解决该问题的帮助。如果您需要更多帮助，请参阅[对自定义密钥存储进行故障排除](fix-keystore.md)。
如果您尝试创建与现有*已断开连接*的 AWS CloudHSM 密钥存储具有相同属性值的 AWS CloudHSM 密钥存储库，则 AWS KMS 不会创建新的 AWS CloudHSM 密钥存储，也不会引发异常或显示错误。相反，它会将重复 AWS KMS 识别为重试可能产生的结果，并返回现有 AWS CloudHSM 密钥库的 ID。
**下一步**：新的 AWS CloudHSM 密钥库不会自动连接。在 AWS CloudHSM 密钥库 AWS KMS keys 中创建之前，必须先将[自定义密钥库连接到](connect-keystore.md)其关联的 AWS CloudHSM 集群。
### 使用 AWS KMS API
您可以使用该[CreateCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateCustomKeyStore.html)操作来创建与账户和区域中的 AWS CloudHSM 集群关联的新 AWS CloudHSM 密钥库。这些示例使用 AWS Command Line Interface (AWS CLI)，但您可以使用任何受支持的编程语言。
`CreateCustomKeyStore` 操作需要以下参数值。
+ CustomKeyStoreName — 自定义密钥库的友好名称，在账户中是唯一的。
**重要**
不要在此字段中包含机密或敏感信息。此字段可能会以纯文本形式显示在 CloudTrail 日志和其他输出中。
+ CloudHsmClusterId — [满足 AWS CloudHSM 密钥存储要求的 AWS CloudHSM 集群的](#before-keystore)集群 ID。
+ KeyStorePassword — 指定集群中 `kmsuser` CU 账户的密码。
+ TrustAnchorCertificate — 您在[初始化集群时创建的`customerCA.crt`](https://docs.aws.amazon.com/cloudhsm/latest/userguide/initialize-cluster.html)文件的内容。
以下示例使用虚构的集群 ID。在运行命令之前，请将其替换为有效的集群 ID。
```
$ aws kms create-custom-key-store
--custom-key-store-name ExampleCloudHSMKeyStore \
--cloud-hsm-cluster-id cluster-1a23b4cdefg \
--key-store-password kmsPswd \
--trust-anchor-certificate
```
如果您使用的是 AWS CLI，则可以指定信任锚证书文件而不是其内容。在下面的示例中，`customerCA.crt` 文件位于根目录中。
```
$ aws kms create-custom-key-store
--custom-key-store-name ExampleCloudHSMKeyStore \
--cloud-hsm-cluster-id cluster-1a23b4cdefg \
--key-store-password kmsPswd \
--trust-anchor-certificate file://customerCA.crt
```
当此操作成功时，`CreateCustomKeyStore` 将返回自定义密钥存储 ID，如以下示例响应中所示。
```
{
"CustomKeyStoreId": cks-1234567890abcdef0
}
```
如果操作失败，请更正异常指示的错误，然后重试。有关其他帮助，请参阅[对自定义密钥存储进行故障排除](fix-keystore.md)。
如果您尝试创建与现有*已断开连接*的 AWS CloudHSM 密钥存储具有相同属性值的 AWS CloudHSM 密钥存储库，则 AWS KMS 不会创建新的 AWS CloudHSM 密钥存储，也不会引发异常或显示错误。相反，它会将重复 AWS KMS 识别为重试可能产生的结果，并返回现有 AWS CloudHSM 密钥库的 ID。
**下一步**：要使用 AWS CloudHSM 密钥库，请[将其连接到其 AWS CloudHSM 集群](connect-keystore.md)。
# 查看密 AWS CloudHSM 钥库
您可以使用 AWS KMS 控制台或[DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html)操作查看每个账户和区域中的 AWS CloudHSM 密钥存储区。
## 使用控制 AWS KMS 台
在中查看 AWS CloudHSM 密钥存储库时 AWS 管理控制台，可以看到以下内容：
+ 自定义密钥存储名称和 ID
+ 关联 AWS CloudHSM 集群的 ID
+ 集群 HSMs 中的数量
+ 当前连接状态
连接**状态（状态**）值为 “**已断开连接**” 表示自定义密钥库是新的，从未连接过，或者是故意与[其 AWS CloudHSM 集群断开连接](disconnect-keystore.md)。但是，如果您尝试在连接的自定义密钥存储中使用 KMS 密钥失败，则可能表明自定义密钥存储或其 AWS CloudHSM 集群存在问题。有关帮助信息，请参阅 [如何修复失败的 KMS 密钥](fix-keystore.md#fix-cmk-failed)。
要查看给定账户和区域中的 AWS CloudHSM 密钥存储，请按以下步骤操作。
1. 登录 AWS 管理控制台 并在 [https://console.aws.amazon.com/km](https://console.aws.amazon.com/kms) s 处打开 AWS Key Management Service (AWS KMS) 控制台。
1. 要更改 AWS 区域，请使用页面右上角的区域选择器。
1. 在导航窗格中，选择**自定义密钥存储**、**AWS CloudHSM 密钥存储**。
要自定义显示，请单击显示在 **Create key store (创建密钥存储)** 按钮下方的齿轮图标。
## 使用 AWS KMS API
要查看您的 AWS CloudHSM 密钥存储库，请使用[DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html)操作。默认情况下，此操作将返回账户和区域中的所有自定义密钥存储。不过，您可以使用 `CustomKeyStoreId` 或 `CustomKeyStoreName` 参数（但不能同时使用两者）将输出限制到特定的自定义密钥存储。对于 AWS CloudHSM 密钥存储，输出包括自定义密钥库 ID 和名称、自定义密钥库类型、关联 AWS CloudHSM 集群的 ID 以及连接状态。如果连接状态指示错误，则输出还包含描述错误原因的错误代码。
本部分中的示例使用 [AWS Command Line Interface (AWS CLI)](https://aws.amazon.com/cli/)，但您可以使用任何受支持的编程语言。
例如，以下命令返回账户和区域中的所有自定义密钥存储。您可以使用 `Limit` 和 `Marker` 参数来浏览输出中的自定义密钥存储。
```
$ aws kms describe-custom-key-stores
```
以下示例命令使用 `CustomKeyStoreName` 参数以仅获取具有 `ExampleCloudHSMKeyStore` 友好名称的自定义密钥存储。您可以在每个命令中使用 `CustomKeyStoreName` 或 `CustomKeyStoreId` 参数（但不能同时使用二者）。
以下示例输出表示已连接到其 AWS CloudHSM 集群的 AWS CloudHSM 密钥库。
**注意**
该`CustomKeyStoreType`字段已添加到`DescribeCustomKeyStores`响应中，以区分 AWS CloudHSM 密钥存储库和外部密钥存储。
```
$ aws kms describe-custom-key-stores --custom-key-store-name ExampleCloudHSMKeyStore
{
"CustomKeyStores": [
{
"CloudHsmClusterId": "cluster-1a23b4cdefg",
"ConnectionState": "CONNECTED",
"CreationDate": "1.499288695918E9",
"CustomKeyStoreId": "cks-1234567890abcdef0",
"CustomKeyStoreName": "ExampleCloudHSMKeyStore",
"CustomKeyStoreType": "AWS_CLOUDHSM",
"TrustAnchorCertificate": ""
}
]
}
```
如果为`ConnectionState`，`Disconnected`则表示自定义密钥库从未连接过，或者它被故意与[其 AWS CloudHSM 集群断开连接](disconnect-keystore.md)。但是，如果尝试在连接的密钥存储中使用 KMS AWS CloudHSM 密钥失败，则可能表示 AWS CloudHSM 密钥存储或其 AWS CloudHSM 集群存在问题。有关帮助信息，请参阅 [如何修复失败的 KMS 密钥](fix-keystore.md#fix-cmk-failed)。
如果自定义密钥存储的 `ConnectionState` 为 `FAILED`，则 `DescribeCustomKeyStores` 响应包含一个说明错误原因的 `ConnectionErrorCode` 元素。
例如，在以下输出中，`INVALID_CREDENTIALS` 值指示自定义密钥存储连接因 [`kmsuser` 密码无效](fix-keystore.md#fix-keystore-password)而导致失败。有关此连接失败及其他连接错误失败的帮助，请参阅[对自定义密钥存储进行故障排除](fix-keystore.md)。
```
$ aws kms describe-custom-key-stores --custom-key-store-id cks-1234567890abcdef0
{
"CustomKeyStores": [
{
"CloudHsmClusterId": "cluster-1a23b4cdefg",
"ConnectionErrorCode": "INVALID_CREDENTIALS",
"ConnectionState": "FAILED",
"CustomKeyStoreId": "cks-1234567890abcdef0",
"CustomKeyStoreName": "ExampleCloudHSMKeyStore",
"CustomKeyStoreType": "AWS_CLOUDHSM",
"CreationDate": "1.499288695918E9",
"TrustAnchorCertificate": ""
}
]
}
```
**了解更多：**
+ [查看外部密钥存储](view-xks-keystore.md)
+ [识别密钥库中的 KMS AWS CloudHSM 密钥](identify-key-types.md#identify-key-hsm-keystore)
+ [使用记录 AWS KMS API 调用 AWS CloudTrail](logging-using-cloudtrail.md)
# 编辑 AWS CloudHSM 密钥库设置
您可以更改现有 AWS CloudHSM 密钥库的设置。自定义密钥库必须断开其 AWS CloudHSM 集群的连接。
要编辑 AWS CloudHSM 密钥库设置，请执行以下操作：
1. [断开自定义密钥存储](disconnect-keystore.md)与其 AWS CloudHSM 集群的连接。
当自定义密钥存储断开连接时，您无法在自定义密钥存储库中创建 AWS KMS keys （KMS 密钥），也无法将其包含的 KMS 密钥用于[加密操作](manage-cmk-keystore.md#use-cmk-keystore)。
1. 编辑一个或多个 AWS CloudHSM 密钥库设置。
您可以在自定义密钥存储中编辑以下设置：
自定义密钥存储的友好名称。
输入新的友好名称。在您的所有自定义密钥存储库中，新名称必须是唯一的 AWS 账户。
不要在此字段中包含机密或敏感信息。此字段可能会以纯文本形式显示在 CloudTrail 日志和其他输出中。
关联集群的 AWS CloudHSM 集群 ID。
编辑此值可将相关 AWS CloudHSM 群集替换为原始群集。如果自定义密钥存储的集群损坏或被删除，则可以使用此功能修复其 AWS CloudHSM 集群。
指定一个与原始 AWS CloudHSM 集群共享备份历史记录并[满足与自定义密钥存储关联要求](create-keystore.md#before-keystore)的集群，包括两个 HSMs 在不同可用区域中处于活动状态的集群。共享备份历史记录的集群具有相同的集群证书。要查看集群的集群证书，请使用[DescribeClusters](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DescribeClusters.html)操作。您无法使用编辑功能来将自定义密钥存储与不相关的 AWS CloudHSM 集群相关联。
[`kmsuser` 加密用户](keystore-cloudhsm.md#concept-kmsuser) (CU) 的当前密码。
告诉 AWS KMS 集 AWS CloudHSM 群中 `kmsuser` CU 的当前密码。此操作不会更改 AWS CloudHSM 集群中 `kmsuser` CU 的密码。
如果您更改 AWS CloudHSM 集群中 `kmsuser` CU 的密码，请使用此功能告知 AWS KMS 新`kmsuser`密码。否则， AWS KMS 将无法登录集群并且所有将自定义密钥存储连接到集群的尝试都将失败。
1. [重新连接自定义密钥存储](connect-keystore.md)至其 AWS CloudHSM 集群。
## 编辑您的密钥存储设置
您可以在 AWS KMS 控制台中或使用[UpdateCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_UpdateCustomKeyStore.html)操作来编辑 AWS CloudHSM 密钥库设置。
### 使用控制 AWS KMS 台
编辑 AWS CloudHSM 密钥库时，可以更改任何或任意可配置值。
1. 登录 AWS 管理控制台 并在 [https://console.aws.amazon.com/km](https://console.aws.amazon.com/kms) s 处打开 AWS Key Management Service (AWS KMS) 控制台。
1. 要更改 AWS 区域，请使用页面右上角的区域选择器。
1. 在导航窗格中，选择**自定义密钥存储**、**AWS CloudHSM 密钥存储**。
1. 选择要编辑的 AWS CloudHSM 密钥库所在的行。
如果**连接状态**列中的值不是**已断开连接**，则必须先断开自定义密钥存储，然后才能对其进行编辑。[从 **Key store actions**（密钥存储操作）菜单中选择 **Disconnect**（断开连接）。]
当 AWS CloudHSM 密钥存储断开连接时，您可以管理密 AWS CloudHSM 钥存储及其 KMS 密钥，但不能在密钥存储中创建或使用 KMS 密钥。 AWS CloudHSM
1. 从 **Key store actions**（密钥存储操作）菜单中选择 **Edit**（编辑）。
1. 执行以下一项或多项操作。
+ 为自定义密钥存储键入新的友好名称。
+ 键入相关集群的 AWS CloudHSM 集群 ID。
+ 键入关联 AWS CloudHSM 集群中`kmsuser`加密用户的当前密码。
1. 选择**保存**。
在此过程成功后，将显示一条消息，描述您编辑的设置。如果此过程失败，则会显示一条错误消息，描述问题并提供有关如何解决问题的帮助。如果您需要更多帮助，请参阅[对自定义密钥存储进行故障排除](fix-keystore.md)。
1. [重新连接自定义密钥存储。](connect-keystore.md)
要使用 AWS CloudHSM 密钥库，必须在编辑后将其重新连接。您可以让 AWS CloudHSM 密钥存储保留断开状态。但是，当它断开连接时，您无法在密钥存储中创建 KMS 密钥，也无法在[加密操作](manage-cmk-keystore.md#use-cmk-keystore)中使用密 AWS CloudHSM 钥存储中的 KMS 密钥。 AWS CloudHSM
### 使用 AWS KMS API
要更改 AWS CloudHSM 密钥库的属性，请使用[UpdateCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_UpdateCustomKeyStore.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/)，但您可以使用任何受支持的编程语言。
首先使用[DisconnectCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_DisconnectCustomKeyStore.html)[断开自定义密钥存储库](disconnect-keystore.md)与其 AWS CloudHSM 集群的连接。将示例自定义密钥存储 ID cks-1234567890abcdef0 替换为实际 ID。
```
$ aws kms disconnect-custom-key-store --custom-key-store-id cks-1234567890abcdef0
```
第一个示例用于[UpdateCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_UpdateCustomKeyStore.html)将 AWS CloudHSM 密钥库的友好名称更改为`DevelopmentKeys`。该命令使用`CustomKeyStoreId`参数来标识 AWS CloudHSM 密钥库，`CustomKeyStoreName`使用参数指定自定义密钥库的新名称。
```
$ aws kms update-custom-key-store --custom-key-store-id cks-1234567890abcdef0 --new-custom-key-store-name DevelopmentKeys
```
以下示例将与 AWS CloudHSM 密钥库关联的集群更改为同一集群的另一个备份。该命令使用`CustomKeyStoreId`参数来标识 AWS CloudHSM 密钥库，使用`CloudHsmClusterId`参数来指定新的集群 ID。
```
$ aws kms update-custom-key-store --custom-key-store-id cks-1234567890abcdef0 --cloud-hsm-cluster-id cluster-1a23b4cdefg
```
以下示例 AWS KMS 说明当前`kmsuser`密码为`ExamplePassword`。该命令使用`CustomKeyStoreId`参数来标识 AWS CloudHSM 密钥库，使用`KeyStorePassword`参数来指定当前密码。
```
$ aws kms update-custom-key-store --custom-key-store-id cks-1234567890abcdef0 --key-store-password ExamplePassword
```
最后一个命令将 AWS CloudHSM 密钥库重新连接到其 AWS CloudHSM 集群。您可以将自定义密钥存储保留断开状态，但必须先连接它，然后才能创建新的 KMS 密钥或使用现有 KMS 密钥来进行[加密操作](manage-cmk-keystore.md#use-cmk-keystore)。将示例自定义密钥存储 ID 替换为实际 ID。
```
$ aws kms connect-custom-key-store --custom-key-store-id cks-1234567890abcdef0
```
# Connect AWS CloudHSM 密钥库
新的 AWS CloudHSM 密钥库未连接。您需要先将其连接到其关联的 AWS CloudHSM 集群，然后才能 AWS KMS keys 在 AWS CloudHSM 密钥库中创建和使用。您可以随时连接和断开 AWS CloudHSM 密钥库的连接，并[查看其连接状态](view-keystore.md#view-keystore-console)。
您无需连接 AWS CloudHSM 密钥库。您可以将 AWS CloudHSM 密钥库无限期地置于断开连接状态，并且仅在需要使用时才连接密钥库。但是，您可能希望定期测试连接以验证设置是否正确以及自定义密钥存储是否可以连接。
**注意**
AWS CloudHSM 只有当密钥库从未`DISCONNECTED`连接过或您明确断开连接时，密钥库才会处于连接状态。如果您的 AWS CloudHSM 密钥库连接状态为，`CONNECTED`但您在使用它时遇到问题，请确保其关联的 AWS CloudHSM 集群处于活动状态并且至少包含一个处于活动状态的集群 HSMs。如需帮助解决连接失败问题，请参阅 [对自定义密钥存储进行故障排除](fix-keystore.md)。
当您连接 AWS CloudHSM 密钥库时，会 AWS KMS 找到关联的 AWS CloudHSM 集群，连接到该集群，以[`kmsuser`加密用户](keystore-cloudhsm.md#concept-kmsuser) (CU) 的身份登录 AWS CloudHSM 客户端，然后轮换`kmsuser`密码。 AWS KMS 只要 AWS CloudHSM 密钥库已连接，就会一直登录到 AWS CloudHSM 客户端。
要建立连接，请在集[群的虚拟私有云 (VPC) `kms-` 中 AWS KMS 创建一个名为的安全组](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html)。该安全组只有一条规则，允许来自集群安全组的入站流量。 AWS KMS 还会在集群的私有子[网的每个可用区中创建一个 elastic network inter](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_ElasticNetworkInterfaces.html) face (ENI)。 AWS KMS 将 ENIs 添加到集群`kms-`的安全组和安全组。每个 ENI 的描述都是 `KMS managed ENI for cluster `。
连接过程可能需要较长时间才能完成；最多 20 分钟。
在连接 AWS CloudHSM 密钥库之前，请验证其是否符合要求。
+ 其关联的 AWS CloudHSM 群集必须包含至少一个活动的 HSM。要查找集群 HSMs 中的数量，请在 AWS CloudHSM 控制台中查看集群或使用[DescribeClusters](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DescribeClusters.html)操作。如有必要，您可以[添加 HSM](https://docs.aws.amazon.com/cloudhsm/latest/userguide/add-remove-hsm.html)。
+ 集群必须有一个[`kmsuser`加密用户](create-keystore.md#kmsuser-concept) (CU) 帐户，但是当您连接 AWS CloudHSM 密钥库时，该 CU 无法登录到集群。要获取有关注销的帮助，请参阅 [如何注销并重新连接](fix-keystore.md#login-kmsuser-2)。
+ AWS CloudHSM 密钥库的连接状态不能为`DISCONNECTING`或`FAILED`。要查看连接状态，请使用 AWS KMS 控制台或[DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html)响应。如果连接状态为 `FAILED`，请断开自定义密钥存储，修复问题，然后连接它。
如需帮助解决连接失败问题，请参阅 [如何修复连接故障](fix-keystore.md#fix-keystore-failed)。
连接 AWS CloudHSM 密钥库后，您可以在其中[创建 KMS 密钥并在[加密操作](manage-cmk-keystore.md#use-cmk-keystore)中](create-cmk-keystore.md)使用现有的 KMS 密钥。
## 连接并重新连接到您的 AWS CloudHSM 密钥库
您可以在 AWS KMS 控制台中或使用[ConnectCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_ConnectCustomKeyStore.html)操作来连接或重新连接您的 AWS CloudHSM 密钥存储库。
### 使用控制 AWS KMS 台
要连接中的 AWS CloudHSM 密钥存储库 AWS 管理控制台，请先从**自定义 AWS CloudHSM 密钥存储库页面中选择密钥存储库**。连接过程可能最多需要 20 分钟才能完成。
1. 登录 AWS 管理控制台 并在 [https://console.aws.amazon.com/km](https://console.aws.amazon.com/kms) s 处打开 AWS Key Management Service (AWS KMS) 控制台。
1. 要更改 AWS 区域，请使用页面右上角的区域选择器。
1. 在导航窗格中，选择**自定义密钥存储**、**AWS CloudHSM 密钥存储**。
1. 选择要连接的 AWS CloudHSM 密钥库所在行。
如果 AWS CloudHSM 密钥库的连接状态为 “**失败**”，则必须先[断开自定义密钥库](disconnect-keystore.md#disconnect-keystore-console)的连接，然后再进行连接。
1. 从 **Key store actions**（密钥存储操作）菜单中选择 **Connect**（连接）。
AWS KMS 开始连接您的自定义密钥存储库的过程。它将查找关联的 AWS CloudHSM 集群，构建所需的网络基础设施，连接到网络基础设施，以 `kmsuser` CU 身份登录到 AWS CloudHSM 集群，然后轮换 `kmsuser` 密码。当操作完成时，连接状态将变为**已连接**。
如果操作失败，则会出现一条描述失败原因的错误消息。在尝试再次连接之前，请[查看 AWS CloudHSM 密钥库的连接状态](view-keystore.md)。如果状态为**失败**，则必须先[断开自定义密钥存储](disconnect-keystore.md#disconnect-keystore-console)，然后再次连接。如果您需要帮助，请参阅[对自定义密钥存储进行故障排除](fix-keystore.md)。
**下一步：**[在密钥库中创建 KMS AWS CloudHSM 密钥](create-cmk-keystore.md)。
### 使用 AWS KMS API
要连接已断开连接的 AWS CloudHSM 密钥库，请使用[ConnectCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_ConnectCustomKeyStore.html)操作。关联的 AWS CloudHSM 集群必须至少包含一个活动的 HSM，并且连接状态不能为。`FAILED`
连接过程需要较长时间才能完成；最多 20 分钟。除非该过程迅速失败，否则 操作将返回 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/)，但您可以使用任何受支持的编程语言。
要识别 AWS CloudHSM 密钥库，请使用其自定义密钥库 ID。您可以在控制台的**自定义密钥存储**页面上找到 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
```
要验证 AWS CloudHSM 密钥库是否已连接，请使用[DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html)操作。默认情况下，此操作将返回您的账户和区域中的所有自定义密钥存储。但您可以使用 `CustomKeyStoreId` 或 `CustomKeyStoreName` 参数（但不能同时使用两者）将响应限制到特定自定义密钥存储。`ConnectionState` 值 `CONNECTED` 表示自定义密钥存储已连接到其 AWS CloudHSM 集群。
**注意**
该`CustomKeyStoreType`字段已添加到`DescribeCustomKeyStores`响应中，以区分 AWS CloudHSM 密钥存储库和外部密钥存储。
```
$ aws kms describe-custom-key-stores --custom-key-store-id cks-1234567890abcdef0
{
"CustomKeyStores": [
"CustomKeyStoreId": "cks-1234567890abcdef0",
"CustomKeyStoreName": "ExampleCloudHSMKeyStore",
"CloudHsmClusterId": "cluster-1a23b4cdefg",
"CustomKeyStoreType": "AWS_CLOUDHSM",
"TrustAnchorCertificate": "",
"CreationDate": "1.499288695918E9",
"ConnectionState": "CONNECTED"
],
}
```
如果 `ConnectionState` 值为 FAILED，`ConnectionErrorCode` 元素将指示失败的原因。在这种情况下，在您的账户中找 AWS KMS 不到具有 AWS CloudHSM 集群 ID 的集群`cluster-1a23b4cdefg`。如果您删除了该集群，则可以[从原始集群的备份还原它](https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-cluster-from-backup.html)，然后[编辑自定义密钥存储的集群 ID](update-keystore.md)。有关响应连接错误代码的帮助信息，请参阅 [如何修复连接故障](fix-keystore.md#fix-keystore-failed)。
```
$ aws kms describe-custom-key-stores --custom-key-store-id cks-1234567890abcdef0
{
"CustomKeyStores": [
"CustomKeyStoreId": "cks-1234567890abcdef0",
"CustomKeyStoreName": "ExampleKeyStore",
"CloudHsmClusterId": "cluster-1a23b4cdefg",
"CustomKeyStoreType": "AWS_CLOUDHSM",
"TrustAnchorCertificate": "",
"CreationDate": "1.499288695918E9",
"ConnectionState": "FAILED"
"ConnectionErrorCode": "CLUSTER_NOT_FOUND"
],
}
```
# 断开密 AWS CloudHSM 钥库的连接
当您断开 AWS CloudHSM 密钥存储库的连接时，会 AWS KMS 注销 AWS CloudHSM 客户端，断开与关联 AWS CloudHSM 群集的连接，并移除它为支持该连接而创建的网络基础架构。
当 AWS CloudHSM 密钥存储断开连接时，您可以管理密 AWS CloudHSM 钥存储及其 KMS 密钥，但不能在密钥存储中创建或使用 KMS 密钥。 AWS CloudHSM 密钥存储的连接状态为 `DISCONNECTED`，自定义密钥存储中的 KMS 密钥的[密钥状态](key-state.md)为 `Unavailable`，除非它们是 `PendingDeletion`。您可以随时重新连接 AWS CloudHSM 密钥库。
**注意**
AWS CloudHSM 只有当密钥库从未`DISCONNECTED`连接过或您明确断开连接时，密钥库才会处于连接状态。如果您的 AWS CloudHSM 密钥库连接状态为，`CONNECTED`但您在使用它时遇到问题，请确保其关联的 AWS CloudHSM 集群处于活动状态并且至少包含一个处于活动状态的集群 HSMs。如需帮助解决连接失败问题，请参阅 [对自定义密钥存储进行故障排除](fix-keystore.md)。
当您断开自定义密钥存储时，密钥存储中的 KMS 密钥立即变得不可用（视最终一致性而定）。不过，在再次使用 KMS 密钥（例如解密数据密钥）之前，使用受 KMS 密钥保护的[数据密钥](data-keys.md)加密的资源不会受到影响。此问题会影响 AWS 服务，因为许多服务使用数据密钥来保护您的资源。有关更多信息，请参阅 [不可用的 KMS 密钥如何影响数据密钥](unusable-kms-keys.md)。
**注意**
虽然自定义密钥存储已断开连接，但在自定义密钥存储中创建 KMS 密钥或在加密操作中使用现有 KMS 密钥的所有尝试都将失败。此操作可以阻止用户存储和访问敏感数据。
为了更好地估计断开自定义密钥存储的影响，请在自定义密钥存储中[标识 KMS 密钥](find-cmk-in-keystore.md)，并[确定其过去的使用情况](deleting-keys-determining-usage.md)。
您可能会出于以下原因断开 AWS CloudHSM 密钥存储的连接：
+ **轮换 `kmsuser` 密码。**每当 AWS KMS 连接到 AWS CloudHSM 集群时，它就会更改 `kmsuser` 密码。要强制轮换密码，只需断开并重新连接。
+ **审计集 AWS CloudHSM 群中 KMS 密钥的密钥材料**。当您断开自定义密钥存储库的 AWS KMS 连接时，请注销 AWS CloudHSM 客户端中的[`kmsuser`加密用户](keystore-cloudhsm.md#concept-kmsuser)帐户。这样，您便能以 `kmsuser` CU 身份登录到集群并审核和管理 KMS 密钥的密钥材料。
+ 在 AWS CloudHSM 密钥存储中**立即禁用所有 KMS 密钥**。您可以使用 AWS 管理控制台 或[DisableKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DisableKey.html)操作[禁用和重新启用密 AWS CloudHSM 钥](enabling-keys.md)存储中的 KMS 密钥。这些操作会快速完成，但它们一次只针对一个 KMS 密钥。断开 AWS CloudHSM 密钥存储库的连接会立即将密钥存储区中所有 KMS 密钥的密钥状态更改为`Unavailable`，从而阻止它们用于任何加密操作。 AWS CloudHSM
+ **修复失败的连接尝试**。如果尝试连接 AWS CloudHSM 密钥库失败（自定义密钥库的连接状态为`FAILED`），则必须先断开 AWS CloudHSM 密钥库的连接，然后再尝试重新连接。
## 断开 AWS CloudHSM 密钥库的连接
您可以在 AWS KMS 控制台中断开 AWS CloudHSM 密钥存储的连接，也可以使用该[DisconnectCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_DisconnectCustomKeyStore.html)操作断开密钥存储的连接。
### 使用 AWS KMS 控制台断开连接
要断开 AWS KMS 控制台中已连接的 AWS CloudHSM 密钥存储区的连接，请先从 “**自定义 AWS CloudHSM 密钥存储” 页面中选择密钥存储库**。
1. 登录 AWS 管理控制台 并在 [https://console.aws.amazon.com/km](https://console.aws.amazon.com/kms) s 处打开 AWS Key Management Service (AWS KMS) 控制台。
1. 要更改 AWS 区域，请使用页面右上角的区域选择器。
1. 在导航窗格中，选择**自定义密钥存储**、**AWS CloudHSM 密钥存储**。
1. 选择要断开连接的外部密钥存储的行。
1. 从 **Key store actions**（密钥存储操作）菜单中选择 **Disconnect**（断开连接）。
当操作完成时，连接状态将从**正在断开**变为**已断开连接**。如果操作失败，则会出现一条错误消息，描述问题并提供有关如何修复它的帮助。如果您需要更多帮助，请参阅[对自定义密钥存储进行故障排除](fix-keystore.md)。
### 使用 AWS KMS API 断开连接
要断开连接的 AWS CloudHSM 密钥存储库，请使用[DisconnectCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_DisconnectCustomKeyStore.html)操作。如果操作成功，则 AWS KMS 返回一个 HTTP 200 响应和一个没有属性的 JSON 对象。
本部分中的示例使用 [AWS Command Line Interface (AWS CLI)](https://aws.amazon.com/cli/)，但您可以使用任何受支持的编程语言。
此示例断开 AWS CloudHSM 密钥库的连接。在运行此示例之前，请将示例 ID 替换为有效的 ID。
```
$ aws kms disconnect-custom-key-store --custom-key-store-id cks-1234567890abcdef0
```
要验证 AWS CloudHSM 密钥存储是否已断开连接，请使用[DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html)操作。默认情况下，此操作将返回您的账户和区域中的所有自定义密钥存储。但您可以使用 `CustomKeyStoreId` 和 `CustomKeyStoreName` 参数（但不能同时使用两者）将响应限制到特定自定义密钥存储。的`ConnectionState`值`DISCONNECTED`表示此示例 AWS CloudHSM 密钥存储未连接到其 AWS CloudHSM 集群。
```
$ aws kms describe-custom-key-stores --custom-key-store-id cks-1234567890abcdef0
{
"CustomKeyStores": [
"CloudHsmClusterId": "cluster-1a23b4cdefg",
"ConnectionState": "DISCONNECTED",
"CreationDate": "1.499288695918E9",
"CustomKeyStoreId": "cks-1234567890abcdef0",
"CustomKeyStoreName": "ExampleKeyStore",
"CustomKeyStoreType": "AWS_CLOUDHSM",
"TrustAnchorCertificate": ""
],
}
```
# 删除密 AWS CloudHSM 钥库
删除 AWS CloudHSM 密钥库时， AWS KMS 会从 KMS 中删除有关该 AWS CloudHSM 密钥存储的所有元数据，包括有关其与 AWS CloudHSM 集群关联的信息。此操作不会影响集 AWS CloudHSM 群 HSMs、其或其用户。您可以创建与同一 AWS CloudHSM 集群关联的新 AWS CloudHSM 密钥库，但无法撤消删除操作。
您只能删除与其 AWS CloudHSM 集群断开连接且不包含任何 AWS CloudHSM 密钥存储的密钥库 AWS KMS keys。在删除自定义密钥存储之前，请执行以下操作。
+ 验证您是否永远不需要将密钥存储中的任何 KMS 密钥用于任何[加密操作](manage-cmk-keystore.md#use-cmk-keystore)。然后从密钥存储中执行所有 KMS 密钥的[计划删除](deleting-keys.md#delete-cmk-keystore)。有关在密钥库中查找 KMS 密 AWS CloudHSM 钥的帮助，请参阅[在密钥库中查找 KMS AWS CloudHSM 密钥](find-cmk-in-keystore.md)。
+ 确认已删除所有 KMS 密钥。要查看密钥库中的 KMS AWS CloudHSM 密钥，请参阅[识别密钥库中的 KMS AWS CloudHSM 密钥](identify-key-types.md#identify-key-hsm-keystore)。
+ [断开 AWS CloudHSM 密钥库](disconnect-keystore.md)与其集 AWS CloudHSM 群的连接。
与其删除 AWS CloudHSM 密钥库，不如考虑[将其与关联 AWS CloudHSM 集群断开连接](disconnect-keystore.md)。当 AWS CloudHSM 密钥库断开连接时，您可以管理 AWS CloudHSM 密钥库及其密钥库 AWS KMS keys。但是您不能在密钥库中创建或使用 KMS AWS CloudHSM 密钥。您可以随时重新连接 AWS CloudHSM 密钥库。
## 删除您的 AWS CloudHSM 密钥库
您可以在 AWS KMS 控制台中或使用[DeleteCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeleteCustomKeyStore.html)操作来删除您的 AWS CloudHSM 密钥库。
### 使用控制 AWS KMS 台
要删除中的 AWS CloudHSM 密钥存储库 AWS 管理控制台，请先从**自定义 AWS CloudHSM 密钥存储库页面中选择密钥存储库**。
1. 登录 AWS 管理控制台 并在 [https://console.aws.amazon.com/km](https://console.aws.amazon.com/kms) s 处打开 AWS Key Management Service (AWS KMS) 控制台。
1. 要更改 AWS 区域，请使用页面右上角的区域选择器。
1. 在导航窗格中，选择**自定义密钥存储**、**AWS CloudHSM 密钥存储**。
1. 找到代表您要删除的 AWS CloudHSM 密钥库的行。如果 AWS CloudHSM 密钥库的 “**连接” 状态**不是 “**已断开连接**”，则必须先[断开 AWS CloudHSM 密钥库的](disconnect-keystore.md)连接，然后才能将其删除。
1. 从 **Key store actions**（密钥存储操作）菜单中选择 **Delete**（删除）。
操作完成后，将显示一条成功消息，并且 AWS CloudHSM 密钥库不再出现在密钥库列表中。如果操作失败，则会显示一条错误消息，描述问题并提供有关如何解决该问题的帮助。如果您需要更多帮助，请参阅[对自定义密钥存储进行故障排除](fix-keystore.md)。
### 使用 AWS KMS API
要删除密 AWS CloudHSM 钥库，请使用[DeleteCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeleteCustomKeyStore.html)操作。如果操作成功，则 AWS KMS 返回一个 HTTP 200 响应和一个没有属性的 JSON 对象。
首先，请验证 AWS CloudHSM 密钥库中是否不包含任何密钥 AWS KMS keys。您无法删除包含 KMS 密钥的自定义密钥存储。第一个示例命令使用[ListKeys](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListKeys.html)和[DescribeKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html)在 AWS CloudHSM 密钥库 AWS KMS keys 中使用示例*cks-1234567890abcdef0*自定义密钥库 ID 进行搜索。在此情况下，该命令不会返回任何 KMS 密钥。如果是，请使用该[ScheduleKeyDeletion](https://docs.aws.amazon.com/kms/latest/APIReference/API_ScheduleKeyDeletion.html)操作安排每个 KMS 密钥的删除。
------
#### [ Bash ]
```
for key in $(aws kms list-keys --query 'Keys[*].KeyId' --output text) ;
do aws kms describe-key --key-id $key |
grep '"CustomKeyStoreId": "cks-1234567890abcdef0"' --context 100; done
```
------
#### [ PowerShell ]
```
PS C:\> Get-KMSKeyList | Get-KMSKey | where CustomKeyStoreId -eq 'cks-1234567890abcdef0'
```
------
接下来，断开 AWS CloudHSM 密钥库的连接。此示例命令使用[DisconnectCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_DisconnectCustomKeyStore.html)操作断开 AWS CloudHSM 密钥库与其 AWS CloudHSM 集群的连接。在运行此命令之前，请将示例自定义密钥存储 ID 替换为有效 ID。
------
#### [ Bash ]
```
$ aws kms disconnect-custom-key-store --custom-key-store-id cks-1234567890abcdef0
```
------
#### [ PowerShell ]
```
PS C:\> Disconnect-KMSCustomKeyStore -CustomKeyStoreId cks-1234567890abcdef0
```
------
断开自定义密钥库的连接后，您可以使用[DeleteCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeleteCustomKeyStore.html)操作将其删除。
------
#### [ Bash ]
```
$ aws kms delete-custom-key-store --custom-key-store-id cks-1234567890abcdef0
```
------
#### [ PowerShell ]
```
PS C:\> Remove-KMSCustomKeyStore -CustomKeyStoreId cks-1234567890abcdef0
```
------
# 对自定义密钥存储进行故障排除
AWS CloudHSM 密钥存储库旨在提供可用性和弹性。但是，为了保持 AWS CloudHSM 密钥库的正常运行，可能需要修复一些错误情况。
**Topics**
+ [如何修复不可用的 KMS 密钥](#fix-unavailable-cmks)
+ [如何修复失败的 KMS 密钥](#fix-cmk-failed)
+ [如何修复连接故障](#fix-keystore-failed)
+ [如何响应加密操作失败](#fix-keystore-communication)
+ [如何修复无效的 `kmsuser` 凭证](#fix-keystore-password)
+ [如何删除孤立密钥材料](#fix-keystore-orphaned-key)
+ [如何恢复 KMS 密钥的已删除密钥材料](#fix-keystore-recover-backing-key)
+ [如何以 `kmsuser` 身份登录](#fix-login-as-kmsuser)
## 如何修复不可用的 KMS 密钥
密[钥库 AWS KMS keys 中的密 AWS CloudHSM 钥状态](key-state.md)通常为`Enabled`。与所有 KMS 密钥一样，当您在密钥存储中禁用 KMS 密钥或安排将其删除时，密钥状态会发生变化。 AWS CloudHSM 但是，与其他 KMS 密钥不同，自定义密钥存储中的 KMS 密钥还可具有[密钥状态](key-state.md) `Unavailable`。
密钥状态 `Unavailable` 表示 KMS 密钥位于被故意[断开连接](disconnect-keystore.md)的自定义密钥存储中，并且尝试重新连接该集群（如果有）失败。当某个 KMS 密钥不可用时，您可以查看和管理该 KMS 密钥，但不能将其用于[加密操作](manage-cmk-keystore.md#use-cmk-keystore)。
要查找 KMS 密钥的密钥状态，请在 **Customer managed keys**（客户托管密钥）页面上，查看 KMS 密钥的 **Status**（状态）字段。或者，使用[DescribeKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html)操作并查看响应中的`KeyState`元素。有关更多信息，请参阅 [识别和查看密钥](viewing-keys.md)。
已断开的自定义密钥存储中的 KMS 密钥的密钥状态将为 `Unavailable` 或 `PendingDeletion`。计划从自定义密钥存储中删除的 KMS 密钥的密钥状态为 `Pending Deletion`，即使自定义密钥存储已断开连接也是如此。这使您可以取消计划的密钥删除而无需重新连接自定义密钥存储。
要修复不可用的 KMS 密钥，请[重新连接自定义密钥存储](disconnect-keystore.md)。重新连接自定义密钥存储后，自定义密钥存储中的 KMS 密钥的密钥状态将自动还原到之前的状态，例如 `Enabled` 或 `Disabled`。待删除的 KMS 密钥将保持 `PendingDeletion` 状态。但是，当问题仍然存在时，[启用和禁用不可用的 KMS 密钥](enabling-keys.md)不会更改其密钥状态。仅当密钥变得可用时，启用或禁用操作才会生效。
如需帮助解决失败的连接，请参阅[如何修复连接故障](#fix-keystore-failed)。
## 如何修复失败的 KMS 密钥
在密钥存储中 AWS CloudHSM 创建和使用 KMS 密钥时出现问题可能是由于您的密 AWS CloudHSM 钥存储库、其关联的 AWS CloudHSM 集群、KMS 密钥或其密钥材料出现问题所致。
当 AWS CloudHSM 密钥存储与其 AWS CloudHSM 集群断开连接时，自定义密钥存储中 KMS 密钥的密钥状态为`Unavailable`。所有在已断开连接的密钥存储中创建 KMS AWS CloudHSM 密钥的请求都会返回`CustomKeyStoreInvalidStateException`异常。所有加密、解密、重新加密或生成数据密钥的请求都将返回 `KMSInvalidStateException` 异常。要修复此问题，[请重新连接 AWS CloudHSM 密钥库](connect-keystore.md)。
但是，即使密钥存储库中的密钥状态为`Enabled`且 AWS CloudHSM 密钥存储的连接状态为，您尝试使用密钥存储库中的 KMS 密 AWS CloudHSM 钥进行[加密操作](manage-cmk-keystore.md#use-cmk-keystore)也`Connected`可能会失败。这可能由以下任一情况导致。
+ KMS 密钥的密钥材料可能已从关联的 AWS CloudHSM 集群中删除。要进行调查，请[查找 KMS 密钥的密钥材料的密钥 ID](find-handle-for-cmk-id.md)，并在必要时尝试[恢复密钥材料](#fix-keystore-recover-backing-key)。
+ 所有 HSMs 内容均已从与 AWS CloudHSM 密钥库关联的 AWS CloudHSM 集群中删除。要在加密操作中使用密 AWS CloudHSM 钥存储中的 KMS 密钥，其 AWS CloudHSM 集群必须包含至少一个活动的 HSM。要验证 AWS CloudHSM 集群 HSMs 中的数量和状态，[请使用 AWS CloudHSM 控制台](https://docs.aws.amazon.com/cloudhsm/latest/userguide/add-remove-hsm.html)或[DescribeClusters](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DescribeClusters.html)操作。要向集群添加 HSM，请使用 AWS CloudHSM 控制台或[CreateHsm](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_CreateHsm.html)操作。
+ 与 AWS CloudHSM 密钥库关联的 AWS CloudHSM 集群已删除。要修复该问题，请[从与原始集群相关的备份创建一个集群](https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-cluster-from-backup.html)，例如原始集群的备份或用于创建原始集群的备份。然后，在自定义密钥存储设置中[编辑集群 ID](update-keystore.md)。有关说明，请参阅[如何恢复 KMS 密钥的已删除密钥材料](#fix-keystore-recover-backing-key)。
+ 与自定义密钥库关联的 AWS CloudHSM 集群没有任何可用的 PKCS \$111 会话。这种情况通常发生在高突发流量期间，此时需要额外的会话来服务流量。要响应带有关 PKCS \$111 会话的错误消息的 `KMSInternalException`，请退后并重试该请求。
## 如何修复连接故障
如果您尝试将[AWS CloudHSM 密钥库连接到](connect-keystore.md)其 AWS CloudHSM 集群，但操作失败，则 AWS CloudHSM 密钥库的连接状态将更改为`FAILED`。要查找 AWS CloudHSM 密钥库的连接状态，请使用 AWS KMS 控制台或[DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html)操作。
另外，由于容易检测到集群配置错误，一些连接尝试会很快失败。在这种情况下，连接状态仍为 `DISCONNECTED`。这些失败将返回错误消息或[例外](https://docs.aws.amazon.com/kms/latest/APIReference/API_ConnectCustomKeyStore.html#API_ConnectCustomKeyStore_Errors)来说明尝试失败的原因。查看异常描述和[集群要求](create-keystore.md#before-keystore)，修复问题，必要时[更新 AWS CloudHSM 密钥库](update-keystore.md)，然后尝试重新连接。
当连接状态为时`FAILED`，运行[DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html)操作并查看响应中的`ConnectionErrorCode`元素。
**注意**
当 AWS CloudHSM 密钥库的连接状态为时`FAILED`，必须先[断开 AWS CloudHSM 密钥库的连接](disconnect-keystore.md)，然后才能尝试重新连接。您无法将密 AWS CloudHSM 钥库与`FAILED`连接状态相连接。
+ `CLUSTER_NOT_FOUND`表示找 AWS KMS 不到具有指定 AWS CloudHSM 集群 ID 的集群。这可能是因为向 API 操作提供了错误的集群 ID，或者集群被删除而不是被替换。要修复此错误，请验证集群 ID，例如使用 AWS CloudHSM 控制台或[DescribeClusters](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DescribeClusters.html)操作。如果集群已被删除，请[从源的最新备份创建一个集群](https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-cluster-from-backup.html)。然后，[断开 AWS CloudHSM 密钥存储](disconnect-keystore.md)的连接，[编辑 AWS CloudHSM 密钥库](update-keystore.md)集群 ID 设置，然后将[AWS CloudHSM 密钥库重新连接到](connect-keystore.md)集群。
+ `INSUFFICIENT_CLOUDHSM_HSMS`表示关联的 AWS CloudHSM 群集不包含任何群集 HSMs。要连接，集群必须至少具有一个 HSM。要查找集群 HSMs 中的数量，请使用[DescribeClusters](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DescribeClusters.html)操作。要解决此错误，请[添加至少一个 HSM](https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-hsm.html) 到集群。如果您添加多个 HSMs，最好在不同的可用区中创建它们。
+ `INSUFFICIENT_FREE_ADDRESSES_IN_SUBNET`表示 AWS KMS 无法将 AWS CloudHSM 密钥库连接到其 AWS CloudHSM 集群，因为至少有一个[与该集群关联的私有子网](https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-subnets.html)没有任何可用的 IP 地址。 AWS CloudHSM 密钥库连接需要在每个关联的私有子网中有一个空闲的 IP 地址，但最好使用两个。
您[无法将 IP 地址](https://aws.amazon.com/premiumsupport/knowledge-center/vpc-ip-address-range/)（CIDR 块）添加到现有子网。如有可能，请移动或删除在子网中使用 IP 地址的其他资源，例如未使用的 EC2 实例或弹性网络接口。否则，您可以使用[具有[更多可用地址空间](https://docs.aws.amazon.com/vpc/latest/userguide/configure-subnets.html#subnet-sizing)的新私有子网或现有私有子网使用 AWS CloudHSM 群集的最新备份创建](https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-cluster-from-backup.html)集群。然后，要将新集群与您的 AWS CloudHSM 密钥存储关联，[请断开自定义密钥存储](disconnect-keystore.md)的连接，将 AWS CloudHSM 密钥存储的[集群 ID 更改](update-keystore.md)为新集群的 ID，然后尝试重新连接。
**提示**
为避免[重置`kmsuser`密码](#fix-keystore-password)，请使用 AWS CloudHSM 群集的最新备份。
+ `INTERNAL_ERROR`表示由于内部错误而 AWS KMS 无法完成请求。重试请求。对于`ConnectCustomKeyStore`请求，请先断开 AWS CloudHSM 密钥库的连接，然后再尝试重新连接。
+ `INVALID_CREDENTIALS`表示 AWS KMS 无法登录关联的 AWS CloudHSM 集群，因为其`kmsuser`账户密码不正确。如需帮助解决此错误，请参阅[如何修复无效的 `kmsuser` 凭证](#fix-keystore-password)。
+ `NETWORK_ERRORS` 通常表示暂时性网络问题。[断开 AWS CloudHSM 密钥库](disconnect-keystore.md)的连接，等待几分钟，然后再次尝试连接。
+ `SUBNET_NOT_FOUND`表示 AWS CloudHSM 群集配置中至少有一个子网已被删除。如果在群集配置中找 AWS KMS 不到所有子网，则尝试将 AWS CloudHSM 密钥库连接到 AWS CloudHSM 集群失败。
要修复此错误[，请使用同一集群的最新备份创建](https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-cluster-from-backup.html) AWS CloudHSM 集群。（此过程使用 VPC 和私有子网创建新的集群配置。） 验证新集群是否满足[自定义密钥存储的要求](create-keystore.md#before-keystore)，并记下新集群 ID。然后，要将新集群与您的 AWS CloudHSM 密钥存储关联，[请断开自定义密钥存储](disconnect-keystore.md)的连接，将 AWS CloudHSM 密钥存储的[集群 ID 更改](update-keystore.md)为新集群的 ID，然后尝试重新连接。
**提示**
为避免[重置`kmsuser`密码](#fix-keystore-password)，请使用 AWS CloudHSM 群集的最新备份。
+ `USER_LOCKED_OUT` 表示 [`kmsuser` 加密用户 (CU) 账户](keystore-cloudhsm.md#concept-kmsuser)无法访问关联的 AWS CloudHSM 集群，因为失败的密码尝试过多。如需帮助解决此错误，请参阅[如何修复无效的 `kmsuser` 凭证](#fix-keystore-password)。
要修复此错误，[请断开 AWS CloudHSM 密钥存储的连接](disconnect-keystore.md)，然后在 CloudHSM CLI 中使用[https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-user-change-password.html](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-user-change-password.html)命令来更改帐户密码。`kmsuser`然后，[编辑自定义密钥存储的 `kmsuser` 密码设置](update-keystore.md)并重试连接。如需帮助，请使用[如何修复无效的 `kmsuser` 凭证](#fix-keystore-password)主题中所述的过程。
+ `USER_LOGGED_IN`表示 `kmsuser` CU 账户已登录到关联的 AWS CloudHSM 集群。这样可以 AWS KMS 防止轮换`kmsuser`账户密码和登录集群。要修复此错误，请从集群中注销 `kmsuser` CU。如果您更改了登录集群的`kmsuser`密码，则还必须更新密钥库的密 AWS CloudHSM 钥库密码值。有关帮助信息，请参阅 [如何注销并重新连接](#login-kmsuser-2)。
+ `USER_NOT_FOUND`表示在关联的 AWS CloudHSM 集群中找 AWS KMS 不到 `kmsuser` CU 账户。要修复此错误，[请在集群中创建一个 `kmsuser` CU 账户](create-keystore.md#kmsuser-concept)，然后[更新密钥库的 AWS CloudHSM 密钥库密码值](update-keystore.md)。有关帮助信息，请参阅 [如何修复无效的 `kmsuser` 凭证](#fix-keystore-password)。
## 如何响应加密操作失败
在自定义密钥存储中使用 KMS 密钥的加密操作可能会失败，并显示 `KMSInvalidStateException`。以下错误消息可能附带 `KMSInvalidStateException`。
| |
| --- |
| KMS 无法与您的 CloudHSM 集群进行通信。这可能是暂时的网络问题。如果您反复看到此错误，请验证 AWS CloudHSM 集群 VPC 的网络 ACLs 和安全组规则是否正确。 |
+ 虽然它是 HTTPS 400 错误，但它可能是由于暂时的网络问题引起的。要进行响应，首先重试请求。但是，如果继续失败，请检查网络组件的配置。此错误很可能是由于网络组件（例如阻止传出流量的防火墙规则或 VPC 安全组规则）的错误配置引起的。例如，KMS 无法通过 AWS CloudHSM 集群进行通信 IPv6。有关先决条件的详细信息，请参阅[创建密 AWS CloudHSM 钥库](create-keystore.md)。
| |
| --- |
| KMS 无法与您的 AWS CloudHSM 集群通信，因为 kmsuser 已被锁定。如果您反复看到此错误，请断开 AWS CloudHSM 密钥存储并重置 kmsuser 帐户密码。更新自定义密钥存储的 kmsuser 密码，然后重试请求。 |
+ 此错误消息表示 [`kmsuser` 加密用户（CU）账户](keystore-cloudhsm.md#concept-kmsuser)无法访问关联的 AWS CloudHSM 集群，因为失败的密码尝试过多。如需帮助解决此错误，请参阅[如何断开和登录](#login-kmsuser-1)。
## 如何修复无效的 `kmsuser` 凭证
[连接 AWS CloudHSM 密钥库](connect-keystore.md)时，以[`kmsuser`加密用户](keystore-cloudhsm.md#concept-kmsuser) (CU) 的身份 AWS KMS 登录到关联的 AWS CloudHSM 集群。它会一直保持登录状态，直到 AWS CloudHSM 密钥存储断开连接。[DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) 响应显示 `ConnectionState` 值 `FAILED` 以及 `ConnectionErrorCode` 值 `INVALID_CREDENTIALS`，如以下示例中所示。
如果您断开 AWS CloudHSM 密钥存储的连接并更改了`kmsuser`密码，则 AWS KMS 无法使用 `kmsuser` CU 账户的凭据登录 AWS CloudHSM 集群。因此，所有连接 AWS CloudHSM 密钥库的尝试都失败了。`DescribeCustomKeyStores` 响应显示 `ConnectionState` 值 `FAILED` 以及 `ConnectionErrorCode` 值 `INVALID_CREDENTIALS`，如以下示例中所示。
```
$ aws kms describe-custom-key-stores --custom-key-store-name ExampleKeyStore
{
"CustomKeyStores": [
"CloudHsmClusterId": "cluster-1a23b4cdefg",
"ConnectionErrorCode": "INVALID_CREDENTIALS"
"CustomKeyStoreId": "cks-1234567890abcdef0",
"CustomKeyStoreName": "ExampleKeyStore",
"TrustAnchorCertificate": "",
"CreationDate": "1.499288695918E9",
"ConnectionState": "FAILED"
],
}
```
此外，在使用不正确的密码登录到集群的尝试失败五次后， AWS CloudHSM 将锁定用户账户。要登录到集群，您必须更改账户密码。
如果在尝试以 `kmsuser` CU 身份登录集群时 AWS KMS 收到锁定响应，则连接 AWS CloudHSM 密钥库的请求将失败。[DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html)响应中包含`ConnectionState`的`ConnectionErrorCode`值为`FAILED`，值为`USER_LOCKED_OUT`，如以下示例所示。
```
$ aws kms describe-custom-key-stores --custom-key-store-name ExampleKeyStore
{
"CustomKeyStores": [
"CloudHsmClusterId": "cluster-1a23b4cdefg",
"ConnectionErrorCode": "USER_LOCKED_OUT"
"CustomKeyStoreId": "cks-1234567890abcdef0",
"CustomKeyStoreName": "ExampleKeyStore",
"TrustAnchorCertificate": "",
"CreationDate": "1.499288695918E9",
"ConnectionState": "FAILED"
],
}
```
要修复上述任一状况，请使用以下过程。
1. [断开 AWS CloudHSM 密钥库的](disconnect-keystore.md)连接。
1. 运行[DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html)操作并查看响应中`ConnectionErrorCode`元素的值。
+ 如果 `ConnectionErrorCode` 值为 `INVALID_CREDENTIALS`，请确定 `kmsuser` 账户的当前密码。必要时，请使用 CloudHSM CLI 中的 [https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-user-change-password.html](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-user-change-password.html) 命令将密码设置为已知值。
+ 如果 `ConnectionErrorCode` 值是 `USER_LOCKED_OUT`，您必须使用 CloudHSM CLI 中的 [https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-user-change-password.html](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-user-change-password.html) 命令更改 `kmsuser` 密码。
1. [编辑 `kmsuser` 密码设置](update-keystore.md)，使其与当前集群中的 `kmsuser` 密码匹配。此操作将告知 AWS KMS 要用来登录到集群的密码。它不会更改集群中的 `kmsuser` 密码。
1. [连接自定义密钥存储](connect-keystore.md)。
## 如何删除孤立密钥材料
计划从密钥库中删除 KMS AWS CloudHSM 密钥后，您可能需要从关联的 AWS CloudHSM 集群中手动删除相应的密钥材料。
在密钥存储中创建 KMS AWS CloudHSM 密钥时， AWS KMS 会在中创建 KMS 密钥元数据， AWS KMS 并在关联的 AWS CloudHSM 集群中生成密钥材料。当您计划删除密钥存储中的 KMS 密 AWS CloudHSM 钥时，等待期过后， AWS KMS 会删除 KMS 密钥元数据。然后 AWS KMS 尽最大努力从 AWS CloudHSM 集群中删除相应的密钥材料。如果 AWS KMS 无法访问集群，例如当集群与 AWS CloudHSM 密钥库断开连接或`kmsuser`密码更改时，尝试可能会失败。 AWS KMS 不会尝试从群集备份中删除密钥材料。
AWS KMS 在 AWS CloudTrail 日志`DeleteKey`的事件条目中报告其尝试从集群中删除密钥材料的结果。它会在 `additionalEventData` 元素的 `backingKeysDeletionStatus` 元素中显示，如以下示例条目所示。该条目还包括 KMS 密钥 ARN、 AWS CloudHSM 集群 ID 和密钥材料的 ID (`backing-key-id`)。
```
{
"eventVersion": "1.08",
"userIdentity": {
"accountId": "111122223333",
"invokedBy": "AWS Internal"
},
"eventTime": "2021-12-10T14:23:51Z",
"eventSource": "kms.amazonaws.com",
"eventName": "DeleteKey",
"awsRegion": "us-west-2",
"sourceIPAddress": "AWS Internal",
"userAgent": "AWS Internal",
"requestParameters": null,
"responseElements": {
"keyId":"arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
},
"additionalEventData": {
"customKeyStoreId": "cks-1234567890abcdef0",
"clusterId": "cluster-1a23b4cdefg",
"backingKeys": "[{\"backingKeyId\":\"backing-key-id\"}]",
"backingKeysDeletionStatus": "[{\"backingKeyId\":\"backing-key-id\",\"deletionStatus\":\"FAILURE\"}]"
},
"eventID": "c21f1f47-f52b-4ffe-bff0-6d994403cf40",
"readOnly": false,
"resources": [
{
"accountId": "111122223333",
"type": "AWS::KMS::Key",
"ARN": "arn:aws:kms:eu-west-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
}
],
"eventType": "AwsServiceEvent",
"recipientAccountId": "111122223333",
"managementEvent": true,
"eventCategory": "Management"
}
```
**注意**
以下过程使用 AWS CloudHSM 客户端 SDK 5 命令行工具 [CloudHSM C](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli.html) LI。CloudHSM CLI 将 `key-handle` 替换为 `key-reference`。
2025 年 1 月 1 日， AWS CloudHSM 将终止对客户端 SDK 3 命令行工具、CloudHSM 管理实用程序 (CMU) 和密钥管理实用程序 (KMU) 的支持。有关客户端 SDK 3 命令行工具和客户端 SDK 5 命令行工具之间区别的更多信息，请参阅《AWS CloudHSM 用户指南》**中的[从客户端 SDK 3 CMU 和 KMU 迁移到客户端 SDK 5 CloudHSM CLI](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-migrate-from-kmu-cmu.html)。
以下过程演示如何从关联的 AWS CloudHSM 集群中删除孤立的密钥材料。
1. 如果 AWS CloudHSM 密钥库尚未断开连接，请断开密钥库的连接，然后[https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-login.html](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-login.html)，如中所述[如何断开和登录](#login-kmsuser-1)。
**注意**
虽然自定义密钥存储已断开连接，但在自定义密钥存储中创建 KMS 密钥或在加密操作中使用现有 KMS 密钥的所有尝试都将失败。此操作可以阻止用户存储和访问敏感数据。
1. 使用 CloudHSM CLI 中的密[钥删除](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-key-delete.html)命令 HSMs 从集群中删除密钥。
密钥存储中使用 KMS 密钥进行加密操作的所有 CloudTrail 日志条目都包含一个带有`customKeyStoreId`和`backingKey`的`additionalEventData`字段。 AWS CloudHSM `backingKeyId` 字段中返回的值是 CloudHSM 密钥 `id` 属性。我们建议通过筛选**密钥删除**操作`id`来删除您在 CloudTrail 日志中标识的孤立密钥材料。
AWS CloudHSM 将该`backingKeyId`值识别为十六进制值。要按 `id` 筛选，必须在 `backingKeyId` 前面加上 `Ox`。例如，如果 CloudTrail 日志`backingKeyId`中的是`1a2b3c45678abcdef`，则可以按此进行筛选`0x1a2b3c45678abcdef`。
以下示例从您的集群 HSMs 中删除密钥。已`backing-key-id`在 CloudTrail 日志条目中列出。在运行此命令之前，请将示例 `backing-key-id` 替换为您账户中的有效密钥 ID。
```
aws-cloudhsm key delete --filter attr.id="0x"
{
"error_code": 0,
"data": {
"message": "Key deleted successfully"
}
}
```
1. 注销并重新连接 AWS CloudHSM 密钥库，如中所述。[如何注销并重新连接](#login-kmsuser-2)
## 如何恢复 KMS 密钥的已删除密钥材料
如果删除的密钥材料，则 KMS 密钥将无法使用，并且无法解密在 KMS 密钥下加密的所有密文。 AWS KMS key 如果从关联的 AWS CloudHSM 集群中删除密钥存储区中 KMS AWS CloudHSM 密钥的密钥材料，则可能会发生这种情况。但是，可以恢复该密钥材料。
在密钥存储中创建 AWS KMS key （KMS AWS CloudHSM 密钥）时， AWS KMS 登录到关联的 AWS CloudHSM 集群并为 KMS 密钥创建密钥材料。它还会将密码更改为只有它知道的值，并且只要 AWS CloudHSM 密钥库已连接，它就会保持登录状态。由于只有密钥所有者（即创建密钥的 CU）才能删除密钥，因此不太可能 HSMs 意外删除密钥。
但是，如果从集群 HSMs 中删除 KMS 密钥的密钥材料，KMS 密钥的密钥状态最终会更改为`UNAVAILABLE`。如果您尝试使用 KMS 密钥进行加密操作，该操作将失败并出现 `KMSInvalidStateException` 异常。最重要的是，在 KMS 密钥下加密的任何数据都无法解密。
在某些情况下，您可以通过[从包含密钥材料的备份创建集群](https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-cluster-from-backup.html)来恢复已删除的密钥材料。仅当在密钥存在且未被删除的情况下创建了一个备份时，此策略才有效。
使用以下过程恢复密钥材料。
1. 查找包含密钥材料的集群备份。备份还必须包含支持集群及其加密数据所需的所有用户和密钥。
使用[DescribeBackups](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DescribeBackups.html)操作列出集群的备份。然后，使用备份时间戳帮助您选择一个备份。要将输出限制为与 AWS CloudHSM 密钥库关联的集群，请使用`Filters`参数，如以下示例所示。
```
$ aws cloudhsmv2 describe-backups --filters clusterIds=
{
"Backups": [
{
"ClusterId": "cluster-1a23b4cdefg",
"BackupId": "backup-9g87f6edcba",
"CreateTimestamp": 1536667238.328,
"BackupState": "READY"
},
...
]
}
```
1. [从所选备份创建集群](https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-cluster-from-backup.html)。验证备份是否包含已删除的密钥以及集群所需的其他用户和密钥。
1. [断开 AWS CloudHSM 密钥库](disconnect-keystore.md)的连接，以便您可以编辑其属性。
1. [编辑 AWS CloudHSM 密钥库的集群 ID](update-keystore.md)。输入您从备份创建的集群的集群 ID。由于该集群与原始集群共享备份历史记录，新集群 ID 应该是有效的。
1. [重新连接 AWS CloudHSM 密钥库](connect-keystore.md)。
## 如何以 `kmsuser` 身份登录
要在 AWS CloudHSM 集群中为密钥存储创建和管理 AWS CloudHSM 密钥材料，请 AWS KMS 使用[`kmsuser`加密用户 (CU) 账户](keystore-cloudhsm.md#concept-kmsuser)。您在集群[中创建 `kmsuser` CU 账户](create-keystore.md#before-keystore)，并在创建 AWS CloudHSM 密钥库 AWS KMS 时提供其密码。
通常， AWS KMS 管理`kmsuser`账户。但是，对于某些任务，您需要断开 AWS CloudHSM 密钥存储的连接，以 `kmsuser` CU 身份登录集群，然后使用 C [loudHSM 命令行界面 (C](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli.html) LI)。
**注意**
虽然自定义密钥存储已断开连接，但在自定义密钥存储中创建 KMS 密钥或在加密操作中使用现有 KMS 密钥的所有尝试都将失败。此操作可以阻止用户存储和访问敏感数据。
本主题介绍如何[断开 AWS CloudHSM 密钥库的连接并以身份登录](#login-kmsuser-1)`kmsuser`、运行 AWS CloudHSM 命令行工具，以及如何[注销和重新连接 AWS CloudHSM 密钥库](#login-kmsuser-2)。
**Topics**
+ [如何断开和登录](#login-kmsuser-1)
+ [如何注销并重新连接](#login-kmsuser-2)
### 如何断开和登录
每当需要以 `kmsuser` 加密用户身份登录到关联的集群时，请使用以下过程。
**注意**
以下过程使用 AWS CloudHSM 客户端 SDK 5 命令行工具 [CloudHSM C](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli.html) LI。CloudHSM CLI 将 `key-handle` 替换为 `key-reference`。
2025 年 1 月 1 日， AWS CloudHSM 将终止对客户端 SDK 3 命令行工具、CloudHSM 管理实用程序 (CMU) 和密钥管理实用程序 (KMU) 的支持。有关客户端 SDK 3 命令行工具和客户端 SDK 5 命令行工具之间区别的更多信息，请参阅《AWS CloudHSM 用户指南》**中的[从客户端 SDK 3 CMU 和 KMU 迁移到客户端 SDK 5 CloudHSM CLI](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-migrate-from-kmu-cmu.html)。
1. 如果 AWS CloudHSM 密钥存储尚未断开连接，请断开其连接。您可以使用 AWS KMS 控制台或 AWS KMS API。
连接 AWS CloudHSM 密钥后 AWS KMS ，将以身份登录`kmsuser`。这将防止您以 `kmsuser` 身份登录或更改 `kmsuser` 密码。
例如，此命令用于断开示例密钥存储的连接。[DisconnectCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_DisconnectCustomKeyStore.html)将示例 AWS CloudHSM 密钥库 ID 替换为有效的密钥库 ID。
```
$ aws kms disconnect-custom-key-store --custom-key-store-id cks-1234567890abcdef0
```
1. 使用 **login** 命令并以管理员身份登录。使用《AWS CloudHSM 用户指南》**的[使用 CloudHSM CLI](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-getting-started.html#w17aac19c11c13b7) 部分中描述的步骤。
```
aws-cloudhsm > login --username admin --role admin
Enter password:
{
"error_code": 0,
"data": {
"username": "admin",
"role": "admin"
}
}
```
1. 使用 CloudHSM CLI 中的[https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-user-change-password.html](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-user-change-password.html)命令将账户密码更改为你知道`kmsuser`的密码。 （连接 AWS CloudHSM 密钥库时AWS KMS 轮换密码。） 密码必须由 7 到 32 个字母数字字符组成。它区分大小写，并且不能包含任何特殊字符。
1. 使用您设置的密码以 `kmsuser` 身份登录。有关详细说明，请参阅《AWS CloudHSM 用户指南》**中的[使用 CloudHSM CLI](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-getting-started.html#w17aac19c11c13b7) 部分。
```
aws-cloudhsm > login --username kmsuser --role crypto-user
Enter password:
{
"error_code": 0,
"data": {
"username": "kmsuser",
"role": "crypto-user"
}
}
```
### 如何注销并重新连接
每次需要以 `kmsuser` 加密用户身份注销并重新连接密钥存储时，请按以下步骤操作。
**注意**
以下过程使用 AWS CloudHSM 客户端 SDK 5 命令行工具 [CloudHSM C](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli.html) LI。CloudHSM CLI 将 `key-handle` 替换为 `key-reference`。
2025 年 1 月 1 日， AWS CloudHSM 将终止对客户端 SDK 3 命令行工具、CloudHSM 管理实用程序 (CMU) 和密钥管理实用程序 (KMU) 的支持。有关客户端 SDK 3 命令行工具和客户端 SDK 5 命令行工具之间区别的更多信息，请参阅《AWS CloudHSM 用户指南》**中的[从客户端 SDK 3 CMU 和 KMU 迁移到客户端 SDK 5 CloudHSM CLI](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-migrate-from-kmu-cmu.html)。
1. 执行任务，然后使用 CloudHSM CLI 中的 [https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-logout.html](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-logout.html) 命令注销。如果您不注销，重新连接 AWS CloudHSM 密钥库的尝试将失败。
```
aws-cloudhsm logout
{
"error_code": 0,
"data": "Logout successful"
}
```
1. 为自定义密钥存储[编辑 `kmsuser` 密码设置](update-keystore.md)。
这 AWS KMS 会告诉集群`kmsuser`中的当前密码。如果您省略此步骤， AWS KMS 将无法以身份登录集群`kmsuser`，并且所有重新连接您的自定义密钥存储的尝试都将失败。您可以使用 AWS KMS 控制台或[UpdateCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_UpdateCustomKeyStore.html)操作的`KeyStorePassword`参数。
例如，此命令 AWS KMS 告诉当前密码是`tempPassword`。将示例密码替换为实际密码。
```
$ aws kms update-custom-key-store --custom-key-store-id cks-1234567890abcdef0 --key-store-password tempPassword
```
1. 将 AWS KMS 密钥库重新连接到其 AWS CloudHSM 集群。将示例 AWS CloudHSM 密钥库 ID 替换为有效的密钥库 ID。在连接过程中，将`kmsuser`密码 AWS KMS 更改为只有它知道的值。
[ConnectCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_ConnectCustomKeyStore.html)操作很快就会恢复，但连接过程可能需要很长时间。初始响应不指示连接过程是否成功。
```
$ aws kms connect-custom-key-store --custom-key-store-id cks-1234567890abcdef0
```
1. 使用该[DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html)操作验证 AWS CloudHSM 密钥库是否已连接。将示例 AWS CloudHSM 密钥库 ID 替换为有效的密钥库 ID。
在此示例中，连接状态字段显示 AWS CloudHSM 密钥库现已连接。
```
$ aws kms describe-custom-key-stores --custom-key-store-id cks-1234567890abcdef0
{
"CustomKeyStores": [
"CustomKeyStoreId": "cks-1234567890abcdef0",
"CustomKeyStoreName": "ExampleKeyStore",
"CloudHsmClusterId": "cluster-1a23b4cdefg",
"TrustAnchorCertificate": "",
"CreationDate": "1.499288695918E9",
"ConnectionState": "CONNECTED"
],
}
```
# 外部密钥存储
外部密钥存储允许您使用外部的加密密钥来保护您的 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中解决此错误。