本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 排查外部密钥存储的问题
<a name="xks-troubleshooting"></a>

大多数外部密钥存储问题的解决方法由每个异常时 Amazon KMS 显示的错误消息或尝试将外部密钥存储库[连接到其外部密钥存储](xks-connect-disconnect.md)代理失败时 Amazon KMS 返回的[连接错误代码](#fix-xks-connection)来指示。但是，有些问题较为复杂。

在诊断外部密钥存储的问题时，首先需要找到原因。这将缩小补救措施的范围，提高故障排除的效率。
+ Amazon KMS — 问题可能出在内部 Amazon KMS，例如[外部密钥存储配置](create-xks-keystore.md#xks-requirements)中的值不正确。
+ 外部 — 问题可能源于外部 Amazon KMS，包括外部密钥存储代理、外部密钥管理器、外部密钥或 VPC 端点服务的配置或操作问题。
+ 联网：可能是连接或网络问题，例如代理端点、端口、IP 堆栈或私有 DNS 名称或域存在问题。

**注意**  
当外部密钥存储的管理操作失败时，这些操作会生成几个不同的异常。但是，所有与外部密钥存储库的外部配置或连接状态相关的失败都会返回 Amazon KMS `KMSInvalidStateException`加密操作。若要确定问题，请使用随附的错误消息文本。  
在连接过程完成之前，[ConnectCustomKeyStore](xks-connect-disconnect.md)操作很快就会成功。要确定连接过程是否成功，请查看外部密钥存储的[连接状态](xks-connect-disconnect.md#xks-connection-state)。如果连接过程失败，则 Amazon 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)

## 外部密钥存储故障排除工具
<a name="xks-troubleshooting-tools"></a>

Amazon KMS 提供了多种工具来帮助您识别和解决外部密钥存储库及其密钥的问题。请将这些工具与随外部密钥存储代理和外部密钥管理器提供的工具结合使用。

**注意**  
您的外部密钥存储代理和外部密钥管理器可能会提供更简单的方法来创建和维护外部密钥存储及其 KMS 密钥。有关详细信息，请参阅外部工具的相关文档。

**Amazon KMS 异常和错误消息**  
Amazon KMS 提供了有关它遇到的任何问题的详细错误消息。您可以在《API 参考》和《[https://docs.amazonaws.cn/kms/latest/APIReference/](https://docs.amazonaws.cn/kms/latest/APIReference/)》中找到有关 Amazon KMS 异常的更多信息 Amazon SDKs。即使你使用的是 Amazon KMS 控制台，你也可能会发现这些参考资料很有帮助。例如，您可以参阅 `CreateCustomKeyStores` 操作的[错误](https://docs.amazonaws.cn/kms/latest/APIReference/API_CreateCustomKeyStore.html#API_CreateCustomKeyStore_Errors)列表。  
要优化外部密钥存储代理的性能， Amazon KMS 在给定的 5 分钟聚合期内，根据代理的可靠性返回异常。如果出现 500 内部服务器错误、503 服务不可用或连接超时，可靠性高的代理会返回 `KMSInternalException` 并触发自动重试，以确保请求最终成功。但是，可靠性较低的代理会返回 `KMSInvalidStateException`。有关更多信息，请参阅[监控外部密钥存储](https://docs.amazonaws.cn/kms/latest/developerguide/xks-monitoring.html)。  
如果问题出现在其他 Amazon 服务中，例如当您使用外部密钥存储中的 KMS 密钥来保护其他 Amazon 服务中的资源时，该 Amazon 服务可能会提供其他信息来帮助您识别问题。如果 Amazon 服务未提供消息，则可以在记录您的 KMS 密钥使用情况的[CloudTrail 日志](logging-using-cloudtrail.md)中查看错误消息。

**[CloudTrail logs](logging-using-cloudtrail.md)**  
每 Amazon KMS 个 API 操作，包括 Amazon KMS 控制台中的操作，都记录在 Amazon CloudTrail 日志中。 Amazon KMS 记录成功和失败操作的日志条目。对于失败的操作，日志条目包括 Amazon KMS 异常名称（`errorCode`）和错误消息（`errorMessage`）。您可以使用此信息来确定和解决错误。有关示例，请参阅[使用外部密钥存储中的 KMS 密钥解密失败](ct-decrypt.md#ct-decrypt-xks-fail)。  
日志条目还包括请求 ID。如果请求到达您的外部密钥存储代理，则您可以使用日志条目中的请求 ID，在代理日志中查找相应的请求（前提是您的代理提供日志）。

**[CloudWatch metrics](monitoring-cloudwatch.md#kms-metrics)**  
Amazon KMS 记录有关您的外部密钥存储操作和性能的详细亚马逊 CloudWatch 指标，包括延迟、限制、代理错误、外部密钥管理器状态、距您的 TLS 证书到期的天数以及您的代理身份验证证书报告的使用期限。您可以使用这些指标为外部密钥存储的操作开发数据模型，并使用 CloudWatch 警报在即将发生的问题发生之前提醒您。  
Amazon KMS 建议您创建 CloudWatch 警报以监控外部密钥存储指标。这些警报将在问题出现之前提醒您注意问题的早期迹象。

**[监控图表](xks-monitoring.md)**  
Amazon KMS 在 Amazon KMS 控制台中每个外部密钥存储的详细信息页面上显示外部密钥存储 CloudWatch 指标的图表。您可以使用图表中的数据来帮助定位错误来源、检测即将发生的问题、建立基线和完善 CloudWatch 警报阈值。有关监控图标解释和使用其数据的详细信息，请参阅 [监控外部密钥存储](xks-monitoring.md)。

**显示外部密钥存储和 KMS 密钥**  
Amazon KMS 在 Amazon KMS 控制台的外部密钥存储区以及对和[DescribeKey](https://docs.amazonaws.cn/kms/latest/APIReference/API_DescribeKey.html)操作的响应中显示有关您的外部密钥存储和 KMS 密钥的[DescribeCustomKeyStores](https://docs.amazonaws.cn/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)**  
Amazon KMS 提供了一个开源测试客户端，用于验证您的外部密钥存储代理是否符合[Amazon KMS 外部密钥库代理 API](https://github.com/aws/aws-kms-xksproxy-api-spec/) 规范。您可以使用此测试客户端来确定和解决外部密钥存储代理的问题。

## 配置错误
<a name="fix-xks-configuration"></a>

创建外部密钥存储时，您需要指定构成外部密钥存储*配置*的属性值，例如[代理身份验证凭证](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)。当 Amazon KMS 检测到属性值中有错误时，操作将失败并返回一个指示错误值的错误。

通过修复错误的值，可以解决许多配置问题。您可以修复无效的代理 URI 路径或代理身份验证凭证，而无需断开外部密钥存储的连接。有关这些值的定义，包括唯一性要求，请参阅 [汇编先决条件](create-xks-keystore.md#xks-requirements)。有关更新这些值的说明，请参阅 [编辑外部密钥存储属性](update-xks-keystore.md)。

为避免代理 URI 路径和代理身份验证凭证值出错，在创建或更新外部密钥存储时，请将[代理配置文件](create-xks-keystore.md#proxy-configuration-file)上传到 Amazon KMS 控制台。这是一个基于 JSON 的文件，其中包含由外部密钥存储代理或外部密钥管理器提供的代理 URI 路径和代理身份验证凭证值。您不能在 Amazon KMS API 操作中使用代理配置文件，但您可以使用该文件中的值来帮助您为 API 请求提供与代理中的值相匹配的参数值。

### 常规配置错误
<a name="fix-xks-gen-configuration"></a>

**异常**：`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)的外部密钥存储，请在创建和更新外部密钥存储时 Amazon KMS 测试属性值。对于使用 [VPC 端点服务连接](choose-xks-connectivity.md#xks-vpc-connectivity)的外部密钥存储， Amazon KMS 会在您连接和更新外部密钥存储时测试属性值。

**注意**  
即使尝试将外部密钥存储连接到其外部密钥存储代理失败，异步 `ConnectCustomKeyStore` 操作也可能会成功。在这种情况下，不会出现异常，但外部密钥存储的连接状态为“Failed（失败）”，并且连接错误代码将说明错误消息。有关更多信息，请参阅 [外部密钥存储连接错误](#fix-xks-connection)。

如果在属性值中 Amazon KMS 检测到错误，则操作将失败`XksProxyInvalidConfigurationException`并返回以下错误消息之一。


|  | 
| --- |
| 由于 URI 路径无效，外部密钥存储代理拒绝了该请求。请验证外部密钥存储的 URI 路径，并在必要时进行更新。 | 
+ 代[理 URI 路径](create-xks-keystore.md#require-path)是向代理 Amazon KMS 发出请求的基本路径 APIs。如果此路径不正确，则对代理的所有请求都将失败。如需[查看外部密钥存储的当前代理 URI 路径](view-xks-keystore.md)，请使用 Amazon KMS 控制台或 `DescribeCustomKeyStores` 操作。如需查找正确的代理 URI 路径，请参阅您的外部密钥存储代理文档。有关更正代理 URI 路径值的帮助，请参阅 [编辑外部密钥存储属性](update-xks-keystore.md)。
+ 随着外部密钥存储代理或外部密钥管理器的更新，外部密钥存储代理的代理 URI 路径可能会发生变化。有关此类变化的详细信息，请参阅外部密钥存储代理或外部密钥管理器的文档。


|  | 
| --- |
| `XKS_PROXY_INVALID_TLS_CONFIGURATION`Amazon KMS 无法与外部密钥存储代理建立 TLS 连接。请验证 TLS 配置，包括其证书。 | 
+ 所有外部密钥存储代理都需要 TLS 证书。TLS 证书必须由支持外部密钥存储的公有证书颁发机构（CA）颁发。有关支持的列表 CAs，请参阅《 Amazon 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 指标。 Amazon KMS 控制台的 “[**监控**” 部分](xks-monitoring.md)还会显示 TLS 认证到期日期的天数。
+ 如果您使用[公有端点连接](choose-xks-connectivity.md#xks-connectivity-public-endpoint)，请使用 SSL 测试工具来测试您的 SSL 配置。TLS 连接错误可能是由不正确的证书链导致。

### VPC 端点服务连接配置错误
<a name="fix-xks-vpc-configuration"></a>

**异常**：`XksProxyVpcEndpointServiceNotFoundException`、`XksProxyVpcEndpointServiceInvalidConfigurationException`

除了一般的连接问题外，在创建、连接或更新具有 VPC 终端节点服务连接的外部密钥存储库时，您可能会遇到以下问题。 Amazon KMS 在[创建](create-xks-keystore.md)、连接和[更新](update-xks-keystore.md)外部密钥存储库时，测试具有 VPC 终端节点服务[连接](xks-connect-disconnect.md)的外部密钥存储的属性值。当管理操作由于配置错误而失败时，这些操作会生成以下异常：


|  | 
| --- |
| XksProxyVpcEndpointServiceNotFoundException | 

原因可能是以下之一：
+ VPC 端点服务名称不正确。请验证外部密钥存储的 VPC 端点服务名称是否正确，以及是否与外部密钥存储的代理 URI 端点值相匹配。要查找 VPC 终端节点服务名称，请使用 [Amazon VPC 控制台](https://console.amazonaws.cn/vpc)或[DescribeVpcEndpointServices](https://docs.amazonaws.cn/AmazonVPC/latest/APIReference/DescribeVpcEndpointServices.html)操作。要查找现有外部密钥存储区的 VPC 终端节点服务名称和代理 URI 终端节点，请使用 Amazon KMS 控制台或[DescribeCustomKeyStores](https://docs.amazonaws.cn/kms/latest/APIReference/API_DescribeCustomKeyStores.html)操作。有关更多信息，请参阅 [查看外部密钥存储](view-xks-keystore.md)。
+ VPC 终端节点服务可能位于与外部密钥存储区 Amazon Web Services 区域 不同的位置。请验证 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)。
+ Amazon KMS 不是 VPC 终端节点服务的允许委托人。VPC 端点服务的 **Allow principals**（允许主体）列表必须包含 `cks.kms.{{<region>}}.amazonaws.com` 值，例如 `cks.kms.{{eu-west-3}}.amazonaws.com`。有关添加此值的说明，请参阅《Amazon PrivateLink 指南》**中的[管理权限](https://docs.amazonaws.cn/vpc/latest/privatelink/configure-endpoint-service.html#add-remove-permissions)。


|  | 
| --- |
| XksProxyVpcEndpointServiceInvalidConfigurationException | 

当 VPC 端点服务无法满足以下要求之一时，就会出现此错误：
+ VPC 需要至少两个私有子网，每个子网均位于不同的可用区内。有关将子网添加到 VPC 中的帮助，请参阅《Amazon VPC 用户指南》**中的[在您的 VPC 中创建子网](https://docs.amazonaws.cn/vpc/latest/userguide/working-with-subnets.html#create-subnets)。
+ 您的 [VPC 端点服务类型](https://docs.amazonaws.cn/vpc/latest/privatelink/create-endpoint-service.html)必须使用网络负载均衡器，而不是网关负载均衡器。
+ 不得要求 VPC 端点服务接受请求 [**Acceptance required**（需要接受）必须是“false”]。如果需要手动接受每个连接请求，则 Amazon KMS 无法使用 VPC 终端节点服务连接到外部密钥存储代理。有关详细信息，请参阅《Amazon PrivateLink 指南》**中的[接受或拒绝连接请求](https://docs.amazonaws.cn/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 名称，请参阅《Amazon PrivateLink 指南》**中的[管理 VPC 端点服务的 DNS 名称](https://docs.amazonaws.cn/vpc/latest/privatelink/manage-dns-names.html)。
+ 您的私有 DNS 名称域的 **Domain verification status**（域验证状态）必须为 `verified`。要查看和更新私有 DNS 名称域的验证状态，请参阅 [步骤 5：验证私有 DNS 名称域](vpc-connectivity.md#xks-private-dns)。添加所需的文本记录后，可能需要几分钟才能显示更新的验证状态。
**注意**  
只有当私有 DNS 域是公有域的子域时，才能对其进行验证。否则，即使您添加了所需的 TXT 记录，私有 DNS 域的验证状态也不会更改。
+ 确保与外部密钥存储代理 Amazon KMS 之间的任何防火墙都允许进出代理上端口 443 的流量。 Amazon 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)。

## 外部密钥存储连接错误
<a name="fix-xks-connection"></a>

[将外部密钥存储连接到其外部密钥存储代理的过程](about-xks-connecting.md)大约需要五分钟才能完成。除非该过程迅速失败，否则 `ConnectCustomKeyStore` 操作将返回 HTTP 200 响应和无属性的 JSON 对象。但是，此初始响应不指示连接是否成功。要确定外部密钥存储是否已连接，请查看其[连接状态](xks-connect-disconnect.md#xks-connection-state)。如果连接失败，则外部密钥存储库的[连接状态将更改为`FAILED`并 Amazon KMS 返回一个解释失败原因的连接错误代码](#xks-connection-error-codes)。

**注意**  
当自定义密钥存储的连接状态为 `FAILED` 时，您必须先断开自定义密钥存储的连接，然后再尝试重新连接。您无法连接具有 `FAILED` 连接状态的自定义密钥存储。

查看外部密钥存储的连接状态：
+ 在[DescribeCustomKeyStores](https://docs.amazonaws.cn/kms/latest/APIReference/API_DescribeCustomKeyStores.html)响应中，查看`ConnectionState`元素的值。
+ 在 Amazon KMS 控制台中，**连接状态**显示在外部密钥存储表中。此外，每个外部密钥存储的详细信息页面上的 **General configuration**（常规配置）部分中也显示了 **Connection state**（连接状态）。

当连接状态为 `FAILED` 时，连接错误代码有助于解释错误。

要查看连接错误代码，请执行以下操作：
+ 在[DescribeCustomKeyStores](https://docs.amazonaws.cn/kms/latest/APIReference/API_DescribeCustomKeyStores.html)响应中，查看`ConnectionErrorCode`元素的值。只有当 `ConnectionState` 为 `FAILED` 时，此元素才会出现在 `DescribeCustomKeyStores` 响应中。
+ 要在 Amazon KMS 控制台中查看连接错误代码，请在外部密钥存储的详细信息页面上将鼠标悬停在 Faile **d** 值上。  
![自定义密钥存储详细信息页面上的连接错误代码](http://docs.amazonaws.cn/kms/latest/developerguide/images/connection-error-code.png)

### 外部密钥存储的连接错误代码
<a name="xks-connection-error-codes"></a>

以下连接错误代码适用于外部密钥存储

`INTERNAL_ERROR`  
Amazon KMS 由于内部错误，无法完成请求。重试请求。对于 `ConnectCustomKeyStore` 请求，先断开自定义密钥存储，然后再尝试重新连接它。

`INVALID_CREDENTIALS`  
其中一个或两个 `XksProxyAuthenticationCredential` 值在指定的外部密钥存储代理上无效。

`NETWORK_ERRORS`  
网络错误使自定义密钥存储无法 Amazon KMS 连接到其备用密钥存储库。

`XKS_PROXY_ACCESS_DENIED`  
Amazon KMS 请求被拒绝访问外部密钥库代理。如果外部密钥存储代理有授权规则，请验证这些规则是否允许 Amazon KMS 代表您与代理进行通信。

`XKS_PROXY_INVALID_CONFIGURATION`  
配置错误导致外部密钥存储无法连接到其代理。验证 `XksProxyUriPath` 的值。

`XKS_PROXY_INVALID_RESPONSE`  
Amazon KMS 无法解释来自外部密钥存储代理的响应。如果您反复看到此连接错误代码，请通知您的外部密钥存储代理供应商。

`XKS_PROXY_INVALID_TLS_CONFIGURATION`  
Amazon 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`  
Amazon KMS 无法与您的外部密钥存储代理通信。请验证 `XksProxyUriEndpoint` 和 `XksProxyUriPath` 是否正确。使用外部密钥存储代理的工具来验证该代理是否处于活动状态并在其网络上可用。此外，请验证您的外部密钥管理器实例是否正常运行。如果代理报告所有外部密钥管理器实例都不可用，则连接尝试失败，并显示此连接错误代码。

`XKS_PROXY_TIMED_OUT`  
Amazon KMS 可以连接到外部密钥存储代理，但该代理 Amazon KMS 在分配的时间内没有响应。如果您反复看到此连接错误代码，请通知您的外部密钥存储代理供应商。

`XKS_VPC_ENDPOINT_SERVICE_INVALID_CONFIGURATION`  
Amazon VPC 终端节点服务配置不符合 Amazon KMS 外部密钥存储的要求。  
+ VPC 端点服务必须是调用方 Amazon Web Services 账户中的接口端点的端点服务。
+ 其必须有至少连接到两个子网的网络负载均衡器（NLB），每个子网位于不同的可用区中。
+ 该`Allow principals`列表必须包括该地区的 Amazon KMS 服务主体`cks.kms.<region>.amazonaws.com`，例如`cks.kms.us-east-1.amazonaws.com`。
+ 其*不得*要求[接受](https://docs.amazonaws.cn/vpc/latest/privatelink/create-endpoint-service.html)连接请求。
+ 其必须具有私有 DNS 名称。使用 `VPC_ENDPOINT_SERVICE` 连接的外部密钥存储的私有 DNS 名称在其 Amazon Web Services 区域中必须是唯一的。
+ 私有 DNS 名称域的[验证状态](https://docs.amazonaws.cn/vpc/latest/privatelink/verify-domains.html)必须为 `verified`。
+ [TLS 证书](https://docs.amazonaws.cn/elasticloadbalancing/latest/network/create-tls-listener.html)指定了端点可以访问的私有 DNS 主机名。

`XKS_VPC_ENDPOINT_SERVICE_NOT_FOUND`  
Amazon KMS 找不到用于与外部密钥存储代理通信的 VPC 终端节点服务。请验证 `XksProxyVpcEndpointServiceName` 是否正确，以及 Amazon KMS 服务主体是否拥有 Amazon VPC 端点服务中的服务使用者权限。

## 延迟和超时错误
<a name="fix-xks-latency"></a>

**异常**：`CustomKeyStoreInvalidStateException`（`CreateKey`）、`KMSInvalidStateException`（加密操作）、`XksProxyUriUnreachableException`（管理操作）

[**连接错误代码**](#xks-connection-error-codes)：`XKS_PROXY_NOT_REACHABLE`、`XKS_PROXY_TIMED_OUT`

当 Amazon KMS 无法在 250 毫秒的超时间隔内联系代理时，它会返回异常。 `CreateCustomKeyStore`然后`UpdateCustomKeyStore`返回`XksProxyUriUnreachableException`。加密操作会返回标准 `KMSInvalidStateException`，其中包含描述问题的错误消息。如果`ConnectCustomKeyStore`失败，则 Amazon KMS 返回描述问题的[连接错误代码](#fix-xks-connection)。

超时错误可能是暂时性问题，可以通过重试请求来解决。如果问题仍然存在，请验证您的外部密钥存储代理是否处于活动状态并已连接到网络，以及其在外部密钥存储中的代理 URI 端点、代理 URI 路径和 VPC 端点服务名称（如果有）是否正确。此外，请验证您的外部密钥管理器是否接近外部密钥存储库。 Amazon Web Services 区域 如果您需要更新其中任何值，请参阅 [编辑外部密钥存储属性](update-xks-keystore.md)。

要跟踪延迟模式，请使用 Amazon KMS 控制台[**监控**部分](xks-monitoring.md)中的指标**和平均延迟**图表（基于该指标）。[`XksProxyLatency`](monitoring-cloudwatch.md#metric-xks-proxy-latency) CloudWatch 您的外部密钥存储代理可能还会生成跟踪延迟和超时的日志和指标。


|  | 
| --- |
| `XksProxyUriUnreachableException`Amazon KMS 无法与外部密钥存储代理通信。这可能是暂时的网络问题。如果您反复看到此错误，请验证您的外部密钥存储代理是否处于活动状态并已连接到网络，以及其在外部密钥存储中的端点 URI 是否正确。 | 
+ 外部密钥存储代理未在 250 毫秒的超时间隔内响应 Amazon KMS 代理 API 请求。这可能表示出现临时网络问题或代理存在操作或性能问题。如果重试不能解决该问题，请通知您的外部密钥存储代理管理员。

延迟和超时错误通常表现为连接失败。[ConnectCustomKeyStore](https://docs.amazonaws.cn/kms/latest/APIReference/API_ConnectCustomKeyStore.html)操作失败时，外部密钥存储库的*连接状态*将更改为`FAILED`并 Amazon KMS 返回解释*错误的连接错误代码*。有关连接错误代码的列表和解决错误的建议，请参阅 [外部密钥存储的连接错误代码](#xks-connection-error-codes)。**All custom key stores**（所有自定义密钥存储）和 **External key stores**（外部密钥存储）的连接代码列表适用于外部密钥存储。以下连接错误与延迟和超时有关。


|  | 
| --- |
| `XKS_PROXY_NOT_REACHABLE`<br />–或者–<br />`CustomKeyStoreInvalidStateException`, `KMSInvalidStateException`, `XksProxyUriUnreachableException`Amazon 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.amazonaws.cn/kms/latest/APIReference/API_DescribeCustomKeyStores.html)操作或[在 Amazon KMS 控制台中查看外部密钥存储的详细信息页面](view-xks-keystore.md)。
+ 与外部密钥存储代理之间的网络路径上可能存在网络配置错误 Amazon KMS ，例如端口错误。 Amazon KMS 通过端口 443 与外部密钥存储代理通信。 IPv4此值不可配置。
+ 当外部密钥存储代理报告（在[GetHealthStatus](keystore-external.md#concept-proxy-apis)响应中）所有外部密钥管理器实例均为时`UNAVAILABLE`，[ConnectCustomKeyStore](https://docs.amazonaws.cn/kms/latest/APIReference/API_ConnectCustomKeyStore.html)操作将失败，并显示为`ConnectionErrorCode``XKS_PROXY_NOT_REACHABLE`。有关帮助信息，请参阅外部密钥管理器的文档。
+ 此错误可能是由于外部密钥管理器 Amazon Web Services 区域 与外部密钥存储库之间的物理距离较远所致。 Amazon Web Services 区域 和外部密钥管理器之间的 ping 延迟（网络往返时间 (RTT)）不应超过 35 毫秒。您可能需要在离外部密钥管理器更近的地方创建外部密钥存储库，或者将外部密钥管理器移到离外部密钥管理器更近的数据中心 Amazon Web Services 区域。 Amazon Web Services 区域 


|  | 
| --- |
| `XKS_PROXY_TIMED_OUT`<br />–或者–<br />`CustomKeyStoreInvalidStateException`, `KMSInvalidStateException`, `XksProxyUriUnreachableException`Amazon KMS 拒绝了该请求，因为外部密钥存储代理没有及时响应。重试请求。如果您反复看到此错误，请将其报告给您的外部密钥存储代理管理员。 | 

出现此错误可能的原因如下：
+ 此错误可能是由外部密钥管理器与外部密钥存储代理之间的物理距离过远所致。如可行，请将外部密钥存储代理移到离外部密钥管理器更近的地方。
+ 如果代理不是为处理来自的请求量和频率而设计的，则可能会发生超时错误 Amazon KMS。如果您的 CloudWatch 指标显示问题持续存在，请通知您的外部密钥存储代理管理员。
+ 当外部密钥管理器与外部密钥存储的 Amazon VPC 之间的连接无法正常运行时，可能会出现超时错误。如果您正在使用 Amazon Direct Connect，请验证您的 VPC 和外部密钥管理器是否可以有效通信。要获得解决任何问题的帮助，请参阅《 Amazon Direct Connect 用户指南》 Amazon Direct Connect中的 “[疑难解答](https://docs.amazonaws.cn/directconnect/latest/UserGuide/Troubleshooting.html)”。


|  | 
| --- |
| `XKS_PROXY_TIMED_OUT`<br />–或者–<br />`CustomKeyStoreInvalidStateException`, `KMSInvalidStateException`, `XksProxyUriUnreachableException` 外部密钥存储代理未在分配的时间内响应请求。重试请求。如果您反复看到此错误，请将其报告给您的外部密钥存储代理管理员。 | 
+ 此错误可能是由外部密钥管理器与外部密钥存储代理之间的物理距离过远所致。如可行，请将外部密钥存储代理移到离外部密钥管理器更近的地方。

## 身份验证凭证错误
<a name="fix-xks-credentials"></a>

**异常**：`CustomKeyStoreInvalidStateException`（`CreateKey`）、`KMSInvalidStateException`（加密操作）、`XksProxyIncorrectAuthenticationCredentialException`（管理操作，`CreateKey` 除外）

您在外部密钥存储代理 Amazon KMS 上建立和维护的身份验证凭据。然后， Amazon 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`，指出外部密钥存储中的所有外部配置错误和连接状态错误。随附的错误消息描述了问题。


|  | 
| --- |
| 外部密钥存储代理拒绝了该请求，因为其无法对 Amazon KMS进行身份验证。请验证外部密钥存储的凭证，并在必要时进行更新。 | 

出现此错误可能的原因如下：
+ 外部密钥存储的访问密钥 ID 或秘密访问密钥与在外部密钥存储代理上建立的值不匹配。

  要修复此错误，请针对外部密钥存储[更新代理身份验证凭证](update-xks-keystore.md#xks-edit-name)。无需断开外部密钥存储的连接即可进行此更改。
+  Amazon KMS 和外部密钥存储代理之间的反向代理可能正在操纵 HTTP 标头，从而使 SigV4 签名失效。要修复此错误，请通知您的代理管理员。

## 密钥状态错误
<a name="fix-unavailable-xks-keys"></a>

**异常**：`KMSInvalidStateException`

`KMSInvalidStateException` 对自定义密钥存储中的 KMS 密钥有两个不同的用途。
+ 当管理操作（例如 `CancelKeyDeletion`）失败并返回此异常时，这表明 KMS 密钥的[密钥状态](key-state.md)与该操作不兼容。
+ 当对自定义密钥存储中 KMS 密钥的[加密操作](kms-cryptography.md#cryptographic-operations)失败，并显示 `KMSInvalidStateException` 时，这可能表明 KMS 密钥的密钥状态存在问题。但是， Amazon KMS 加密操作会返回`KMSInvalidStateException`外部密钥存储库中的所有外部配置错误和连接状态错误。要确定问题，请使用随异常显示的错误消息。

要查找 Amazon KMS API 操作所需的密钥状态，请参阅[密 Amazon KMS 钥的关键状态](key-state.md)。要查找 KMS 密钥的密钥状态，请在 **Customer managed keys**（客户托管密钥）页面上，查看 KMS 密钥的 **Status**（状态）字段。或者，使用[DescribeKey](https://docs.amazonaws.cn/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`。）
+ 只有当您在 Amazon KMS 控制台或使用[DisableKey](https://docs.amazonaws.cn/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)。

## 解密错误
<a name="fix-xks-decrypt"></a>

**异常**：`KMSInvalidStateException`

当使用外部[密钥存储库中的 KMS 密钥执行解](https://docs.amazonaws.cn/kms/latest/APIReference/API_Decrypt.html)密操作失败时，将 Amazon KMS 返回加密操作用于处理外部密钥存储库上所有外部配置错误和连接状态错误的标准`KMSInvalidStateException`。此错误消息指示该问题。

要解密使用 [双重加密](keystore-external.md#concept-double-encryption) 进行加密的加密文字，外部密钥管理器应首先使用外部密钥解密加密文字的外层。然后 Amazon KMS 使用 KMS Amazon KMS 密钥中的密钥材料来解密密文的内层。无效或损坏的加密文字可能会被外部密钥管理器或 Amazon KMS拒绝。

解密失败时，会随 `KMSInvalidStateException` 出现以下错误消息。它表示请求中的加密文字或可选加密上下文存在问题。


|  | 
| --- |
| 外部密钥存储代理拒绝了该请求，因为指定的加密文字或其他经过身份验证的数据已损坏、丢失或无效。 | 
+ 当外部密钥存储代理或外部密钥管理器报告密文或其加密上下文无效时，通常表示发送到的请求中的密文或加密上下文存在问题。`Decrypt` Amazon KMS对于`Decrypt`操作， Amazon KMS 向代理发送它在请求中收到的相同密文和加密上下文。`Decrypt`

  此错误可能由传输过程中的网络问题引起，例如位反转。重试 `Decrypt` 请求。如果问题仍然存在，请验证加密文字是否未被更改或损坏。此外，请验证`Decrypt`请求中的加密上下文是否与加密数据的请求中的加密上下文 Amazon KMS 相匹配。


|  | 
| --- |
| 外部密钥存储代理提交解密的加密文字或加密上下文已损坏、丢失或无效。 | 
+  Amazon KMS 拒绝从代理收到的密文时，表示外部密钥管理器或代理向其返回了无效或损坏的密文。 Amazon KMS

  此错误可能由传输过程中的网络问题引起，例如位反转。重试 `Decrypt` 请求。如果问题仍然存在，请验证外部密钥管理器是否运行正常，并且外部密钥存储代理在返回外部密钥管理器之前不会更改从外部密钥管理器接收的密文。 Amazon KMS

## 外部密钥错误
<a name="fix-external-key"></a>

[外部密钥](keystore-external.md#concept-external-key)是外部密钥管理器中的加密密钥，用作 KMS 密钥的外部密钥材料。 Amazon KMS 无法直接访问外部密钥。其必须要求外部密钥管理器（通过外部密钥存储代理）使用外部密钥来加密数据或解密加密文字。

在外部密钥存储中创建 KMS 密钥时，您可以在其外部密钥管理器中指定外部密钥的 ID。创建 KMS 密钥后，您无法更改外部密钥 ID。为防止 KMS 密钥出现问题，`CreateKey` 操作会要求外部密钥存储代理验证外部密钥的 ID 和配置。如果外部密钥不[符合与 KMS 密钥一起使用的要求](create-xks-keys.md#xks-key-requirements)，则 `CreateKey` 操作将失败，并显示说明问题的异常和错误消息。

但是，在创建 KMS 密钥后，可能会出现问题。如果加密操作因外部密钥问题而失败，则此操作将会失败并返回 `KMSInvalidStateException`，以及一条包含说明问题的错误消息。

### CreateKey 外部密钥错误
<a name="fix-external-key-create"></a>

**异常**：`XksKeyAlreadyInUseException`、`XksKeyNotFoundException`、`XksKeyInvalidConfigurationException`

该[CreateKey](https://docs.amazonaws.cn/kms/latest/APIReference/API_CreateKey.html)操作会尝试验证您在外部密钥 ID（控制台）或`XksKeyId`（API）参数中提供的**外部密钥的 ID** 和属性。这种做法是为了在您尝试结合使用 KMS 密钥和外部密钥之前及早发现错误。

**正在使用外部密钥** 

外部密钥存储中的每个 KMS 密钥都必须使用不同的外部密钥。当`CreateKey`识别出 KMS 密钥的外部密钥 ID (XksKeyId) 在外部密钥存储中不是唯一的，则会失败，并显示为`XksKeyAlreadyInUseException`。

如果您 IDs 对同一个外部密钥使用多个外键，则`CreateKey`无法识别重复的外键。但是，具有相同外部密钥的 KMS 密钥不可互操作，因为它们具有不同的 Amazon 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\_256。指定外部密钥的密钥规格为{{<key-spec>}}。 | 
+ 外部密钥必须是 256 位对称加密密钥，密钥规格为 AES\_256。如果指定的外部密钥是不同的类型，请指定符合此要求的外部密钥的 ID。


|  | 
| --- |
| 外部密钥的状态必须为“ENABLED”（已启用）。指定外部密钥的状态为{{<status>}}。 | 
+ 必须在外部密钥管理器中启用外部密钥。如果未启用指定的外部密钥，请使用外部密钥管理器工具将其启用，或指定已启用的外部密钥。


|  | 
| --- |
| 外部密钥的密钥用法必须包括“ENCRYPT”（加密）和“DECRYPT”（解密）。指定外部密钥的密钥用法为 < {{key-usage}} >。 | 
+ 必须在外部密钥管理器中配置外部密钥以进行加密和解密。如果指定的外部密钥不包括这些操作，请使用外部密钥管理器工具更改操作，或指定其他外部密钥。

### 外部密钥的加密操作错误
<a name="fix-external-key-crypto"></a>

**异常**：`KMSInvalidStateException`

当外部密钥存储代理找不到与 KMS 密钥关联的外部密钥，或者外部密钥不[符合与 KMS 密钥一起使用的要求](create-xks-keys.md#xks-key-requirements)时，加密操作将失败。

在加密操作期间检测到的外部密钥问题比在创建 KMS 密钥之前检测到的外部密钥问题更难解决。创建 KMS 密钥后，您无法更改外部密钥 ID。如果 KMS 密钥尚未加密任何数据，则可以删除 KMS 密钥并使用其他外部密钥 ID 创建一个新密钥。但是，使用 KMS 密钥生成的密文无法被任何其他 KMS 密钥解密，即使是具有相同外部密钥的密钥也是如此，因为密钥将具有不同的密钥元数据和不同的密钥材料。 Amazon KMS 相反，应尽可能使用外部密钥管理器工具来解决外部密钥的问题。

当外部密钥存储代理报告外部密钥问题时，加密操作会返回 `KMSInvalidStateException`，以及一条说明该问题的错误消息题。

**未找到外部密钥**

当外部密钥存储代理报告无法使用 KMS 密钥的外部密钥 ID (XksKeyId) 找到外部密钥时，加密操作会返回`KMSInvalidStateException`带有以下错误消息的。


|  | 
| --- |
| 外部密钥存储代理拒绝了该请求，因为其无法找到外部密钥。 | 

出现此错误可能的原因如下：
+ KMS 密钥的外部密钥（`XksKeyId`）ID 不再有效。

  要查找与您的 KMS 密钥关联的外部密钥 ID，请[查看 KMS 密钥的详细信息](identify-key-types.md#view-xks-key)。要查找外部密钥代理用于识别外部密钥的 ID，请参阅外部密钥存储代理或外部密钥管理器文档。

  Amazon 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`，请使用外部密钥管理器工具将其启用。

## 代理问题
<a name="fix-xks-proxy"></a>

**例外：**

 `CustomKeyStoreInvalidStateException`（`CreateKey`）、`KMSInvalidStateException`（加密操作）、`UnsupportedOperationException`、`XksProxyUriUnreachableException`、`XksProxyInvalidResponseException`（管理操作，`CreateKey` 除外）

外部密钥存储代理调解 Amazon KMS 和外部密钥管理器之间的所有通信。它将通用 Amazon KMS 请求转换为您的外部密钥管理器可以理解的格式。如果外部密钥存储代理不符合[Amazon KMS 外部密钥存储代理 API 规范](https://github.com/aws/aws-kms-xksproxy-api-spec/)，或者运行不正常或无法与之通信 Amazon KMS，则您将无法在外部密钥存储中创建或使用 KMS 密钥。

尽管许多错误都提到了外部密钥存储代理（因其在外部密钥存储架构中起着关键作用），但这些问题可能源于外部密钥管理器或外部密钥。

本节中的问题与外部密钥存储代理的设计或运行问题有关。要解决这些问题，可能需要更改代理软件。请咨询您的代理管理员。为帮助解决代理问题， Amazon KMS 提供 [XKS 代理测试客户端](https://github.com/aws-samples/aws-kms-xksproxy-test-client)，这是一个开源测试客户端，可用于验证您的外部密钥存储代理是否符合 [Amazon KMS 外部密钥存储代理 API 规范](https://github.com/aws/aws-kms-xksproxy-api-spec/)。


|  | 
| --- |
| `CustomKeyStoreInvalidStateException`、`KMSInvalidStateException` 或 `XksProxyUriUnreachableException`外部密钥存储代理运行状况不佳。如果您反复看到此消息，请通知您的外部密钥存储代理管理员。 | 
+ 此错误可能表示外部密钥存储代理存在运行问题或软件错误。您可以找到生成每个错误的 Amazon KMS API 操作的 CloudTrail 日志条目。重试该操作可能会解决此错误。但是，如果问题仍然存在，请通知您的外部密钥存储代理管理员。
+ 当外部密钥存储代理报告（在[GetHealthStatus](keystore-external.md#concept-proxy-apis)响应中）所有外部密钥管理器实例均为外部密钥管理器实例时`UNAVAILABLE`，尝试创建或更新外部密钥存储将失败，但会出现此异常。如果此错误仍然存在，请查阅您的外部密钥管理器文档。


|  | 
| --- |
| `CustomKeyStoreInvalidStateException`、`KMSInvalidStateException` 或 `XksProxyInvalidResponseException`Amazon KMS 无法解释来自外部密钥存储代理的响应。如果您反复看到此错误，请咨询您的外部密钥存储代理管理员。 | 
+ Amazon KMS 当代理返回 Amazon KMS 无法解析或解释的未定义响应时，操作会生成此异常。此错误可能由于暂时的外部问题或偶然的网络错误而偶尔发生。但是，如果此错误持续存在，则可能表明外部密钥存储代理不符合 [Amazon KMS 外部密钥存储代理 API 规范](https://github.com/aws/aws-kms-xksproxy-api-spec/)。通知您的外部密钥存储管理员或供应商。


|  | 
| --- |
| `CustomKeyStoreInvalidStateException`、`KMSInvalidStateException` 或 `UnsupportedOperationException`<br />外部密钥存储代理拒绝了该请求，因为其不支持所请求的加密操作。 | 
+ 外部密钥存储代理应支持《[Amazon KMS 外部密钥存储[代](keystore-external.md#concept-proxy-apis)理 API 规范》中 APIs定义的所有代理](https://github.com/aws/aws-kms-xksproxy-api-spec/)。此错误表示代理不支持与请求相关的操作。通知您的外部密钥存储管理员或供应商。

## 代理授权问题
<a name="fix-xks-authorization"></a>

**异常**：`CustomKeyStoreInvalidStateException`、`KMSInvalidStateException`

一些外部密钥存储代理针对其外部密钥的使用执行授权要求。允许（但并非必需）外部密钥存储代理设计并实施授权方案，以允许特定用户在特定条件下请求特定操作。例如，代理可能允许用户使用特定的外部密钥进行加密，但不允许使用该外部密钥进行解密。有关更多信息，请参阅 [外部密钥存储代理授权（可选）](authorize-xks-key-store.md#xks-proxy-authorization)。

代理授权基于其对代理的请求中 Amazon KMS 包含的元数据。仅当请求来自 VPC 端点且调用者与 KMS 密钥位于同一个账户时，`awsSourceVpc` 和 `awsSourceVpce` 字段才包含在元数据中。

```
"requestMetadata": {
    "awsPrincipalArn": string,
    "awsSourceVpc": string, // optional
    "awsSourceVpce": string, // optional
    "kmsKeyArn": string,
    "kmsOperation": string,
    "kmsRequestId": string,
    "kmsViaService": string // optional
}
```

当代理因授权失败而拒绝请求时，相关 Amazon KMS 操作将失败。 `CreateKey`返回`CustomKeyStoreInvalidStateException`。 Amazon KMS 加密操作返回`KMSInvalidStateException`。两者都使用以下错误消息：


|  | 
| --- |
| 外部密钥存储代理拒绝对该操作的访问。请验证用户和外部密钥是否均已获得执行此操作的授权，然后重试请求。 | 
+ 要解决错误，请使用外部密钥管理器或外部密钥存储代理工具来确定授权失败的原因。然后，更新导致未经授权的请求的过程，或使用外部密钥存储代理工具更新授权策略。您无法在 Amazon KMS中解决此错误。