排查外部密钥存储的问题 - AWS Key Management Service
故障排除工具配置错误外部密钥存储连接错误延迟和超时错误身份验证凭证错误密钥状态错误解密错误外部密钥错误代理问题代理授权问题

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

排查外部密钥存储的问题

大多数外部密钥存储问题的解决方案由错误消息指示，该消息由 AWS KMS 显示，并提供各个异常，或者由连接错误代码指示，在尝试将外部密钥存储连接到其外部密钥存储代理失败时，AWS KMS 会返回此错误代码。但是，有些问题较为复杂。

在诊断外部密钥存储的问题时，首先需要找到原因。这将缩小补救措施的范围，提高故障排除的效率。

  • AWS KMS – 问题可能出在 AWS KMS 内部，例如外部密钥存储配置中的值不正确。

  • 外部 – 问题可能源于 AWS KMS 外部，包括外部密钥存储代理、外部密钥管理器、外部密钥或 VPC 端点服务的配置或操作问题。

  • 网络 – 可能是连接或网络问题，例如您的代理端点、端口或私有 DNS 名称或域有问题。

注意

当外部密钥存储的管理操作失败时，这些操作会生成几个不同的异常。但是，对于与外部密钥存储的外部配置或连接状态有关的所有操作失败，AWS KMS 加密操作都会返回 KMSInvalidStateException。若要确定问题，请使用随附的错误消息文本。

在连接过程完成之前，ConnectCustomKeyStore 操作会很快成功。要确定连接过程是否成功，请查看外部密钥存储的连接状态。如果连接过程失败，则 AWS KMS 将返回连接错误代码，用于解释原因并提出补救措施建议。

外部密钥存储故障排除工具

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

注意

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

AWS KMS 异常和错误消息

AWS KMS 提供有关其遇到的任何问题的详细错误消息。您可以在 AWS Key Management Service API 参考和 AWS 开发工具包中找到有关 AWS KMS 异常的更多信息。即使您使用的是 AWS KMS 控制台，这些参考文献也很有帮助。例如，您可以参阅 CreateCustomKeyStores 操作的错误列表。

要优化外部密钥存储代理的性能，AWS KMS 在给定的 5 分钟聚合期内，根据代理的可靠性返回异常。如果出现 500 内部服务器错误、503 服务不可用或连接超时，可靠性高的代理会返回 KMSInternalException 并触发自动重试，以确保请求最终成功。但是，可靠性较低的代理会返回 KMSInvalidStateException。有关更多信息，请参阅监控外部密钥存储。

如果问题出现在其他 AWS 服务中，例如当您在外部密钥存储中使用 KMS 密钥来保护其他 AWS 服务中的资源时，该 AWS 服务可能会提供其他信息来帮助您确定问题。如果 AWS 服务未提供消息，则可以在记录 KMS 密钥使用情况的 CloudTrail 日志中查看错误消息。

CloudTrail 日志

每个 AWS KMS API 操作，包括 AWS KMS 控制台中的操作，都记录在 AWS CloudTrail 日志中。AWS KMS 会针对成功和失败操作记录日志条目。对于失败的操作，日志条目包括 AWS KMS 异常名称（errorCode）和错误消息（errorMessage）。您可以使用此信息来确定和解决错误。有关示例，请参阅使用外部密钥存储中的 KMS 密钥解密失败。

日志条目还包括请求 ID。如果请求到达您的外部密钥存储代理，则您可以使用日志条目中的请求 ID，在代理日志中查找相应的请求（前提是您的代理提供日志）。

CloudWatch 指标

AWS KMS 会记录有关外部密钥存储运行和性能的详细 Amazon CloudWatch 指标，包括延迟、节流、代理错误、外部密钥管理器状态、TLS 证书过期之前的天数，以及所报告的代理身份验证凭证的期限。您可以使用这些指标，针对外部密钥存储和 CloudWatch 警报（此类警报会在即将出现的问题发生之前提醒您）的运行开发数据模型。

重要

AWS KMS 建议您创建 CloudWatch 警报来监控外部密钥存储指标。这些警报将在问题出现之前提醒您注意问题的早期迹象。

监控图表

AWS KMS 会在 AWS KMS 控制台中每个外部密钥存储的详细信息页面上，显示外部密钥存储 CloudWatch 指标的图表。您可以使用图表中的数据来帮助定位错误来源、检测即将出现的问题、建立基准和优化 CloudWatch 警报阈值。有关监控图标解释和使用其数据的详细信息，请参阅 监控外部密钥存储。

显示外部密钥存储和 KMS 密钥

AWS KMS 会在 AWS KMS 控制台以及对 DescribeCustomKeyStores 和 DescribeKey 操作的响应中显示有关外部密钥存储及其中的 KMS 密钥的详细信息。这些显示信息包括外部密钥存储和 KMS 密钥的特殊字段，其中包含可用于故障排除的信息，例如外部密钥存储的连接状态和与 KMS 密钥关联的外部密钥的 ID。有关详细信息，请参阅查看外部密钥存储。

XKS 代理测试客户端

AWS KMS 提供开源测试客户端，可用于验证您的外部密钥存储代理是否符合 AWS KMS 外部密钥存储代理 API 规范。您可以使用此测试客户端来确定和解决外部密钥存储代理的问题。

配置错误

创建外部密钥存储时，您需要指定构成外部密钥存储配置的属性值，例如代理身份验证凭证、代理 URI 端点、代理 URI 路径和 VPC 端点服务名称。AWS KMS 在属性值中检测到错误时，操作将失败并返回错误，指示错误值。

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

为避免代理 URI 路径和代理身份验证凭证值出错，在创建或更新外部密钥存储时，请将代理配置文件上传到 AWS KMS 控制台。这是一个基于 JSON 的文件，其中包含由外部密钥存储代理或外部密钥管理器提供的代理 URI 路径和代理身份验证凭证值。您不能将代理配置文件与 AWS KMS API 操作结合使用，但您可以使用文件中的值来为 API 请求提供与代理中的值相匹配的参数值。

常规配置错误

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

连接错误代码：XKS_PROXY_INVALID_CONFIGURATION、XKS_PROXY_INVALID_TLS_CONFIGURATION

对于使用公有端点连接的外部密钥存储，AWS KMS 会在您创建和更新外部密钥存储时测试属性值。对于使用 VPC 端点服务连接的外部密钥存储，AWS KMS 会在您连接和更新外部密钥存储时测试属性值。

注意

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

如果 AWS KMS 检测到属性值错误，则操作将会失败并返回 XksProxyInvalidConfigurationException 和以下错误消息中的一种。

由于 URI 路径无效，外部密钥存储代理拒绝了该请求。请验证外部密钥存储的 URI 路径，并在必要时进行更新。

  • 代理 URI 路径是对代理 API 的 AWS KMS 请求的基本路径。如果此路径不正确，则对代理的所有请求都将失败。如需查看外部密钥存储的当前代理 URI 路径，请使用 AWS KMS 控制台或 DescribeCustomKeyStores 操作。如需查找正确的代理 URI 路径，请参阅您的外部密钥存储代理文档。有关更正代理 URI 路径值的帮助，请参阅 编辑外部密钥存储属性。

  • 随着外部密钥存储代理或外部密钥管理器的更新，外部密钥存储代理的代理 URI 路径可能会发生变化。有关此类变化的详细信息，请参阅外部密钥存储代理或外部密钥管理器的文档。

XKS_PROXY_INVALID_TLS_CONFIGURATION

AWS KMS 无法与外部密钥存储代理建立 TLS 连接。请验证 TLS 配置，包括其证书。

  • 所有外部密钥存储代理都需要 TLS 证书。TLS 证书必须由支持外部密钥存储的公有证书颁发机构（CA）颁发。有关受支持的 CA 列表，请参阅 AWS KMS 外部密钥存储代理 API 规范中的 Trusted Certificate Authorities（受信任的证书颁发机构）。

  • 对于公有端点连接，TLS 证书上的主题公用名（CN）必须与外部密钥存储代理的代理 URI 端点中的域名相匹配。例如，如果公有端点是 https://myproxy.xks.example.com，即 TLS，则 TLS 证书上的 CN 必须为 myproxy.xks.example.com 或 *.xks.example.com。

  • 对于 VPC 端点服务连接，TLS 证书上的主题公用名（CN）必须与您的 VPC 端点服务的私有 DNS 名称相匹配。例如，如果私有 DNS 名称是 myproxy-private.xks.example.com，则 TLS 证书上的 CN 必须为 myproxy-private.xks.example.com 或 *.xks.example.com。

  • TLS 证书不得过期。要获取 TLS 证书的到期日期，请使用 SSL 工具，例如 OpenSSL。要监控与外部密钥存储关联的 TLS 证书的到期日期，请使用 XksProxyCertificateDaysToExpire CloudWatch 指标。距离您的 TLS 证书过期日期的天数也显示在 AWS KMS 控制台的 Monitoring（监控）部分中。

  • 如果您使用公有端点连接，请使用 SSL 测试工具来测试您的 SSL 配置。TLS 连接错误可能是由不正确的证书链导致。

VPC 端点服务连接配置错误

异常：XksProxyVpcEndpointServiceNotFoundException、XksProxyVpcEndpointServiceInvalidConfigurationException

除了一般连接问题，在创建、连接或更新使用 VPC 端点服务连接的外部密钥存储时，您可能会遇到以下问题。AWS KMS 会在创建、连接和更新外部密钥存储时，使用 VPC 端点服务连接测试外部密钥存储的属性值。当管理操作由于配置错误而失败时，这些操作会生成以下异常：

XksProxyVpcEndpointServiceNotFoundException

原因可能是以下之一：

  • VPC 端点服务名称不正确。请验证外部密钥存储的 VPC 端点服务名称是否正确，以及是否与外部密钥存储的代理 URI 端点值相匹配。要查找 VPC 端点服务名称，请使用 Amazon VPC 控制台或 DescribeVpcEndpointServices 操作。要查找现有外部密钥存储的 VPC 端点服务名称和代理 URI 端点，请使用 AWS KMS 控制台或 DescribeCustomKeyStores 操作。有关详细信息，请参阅查看外部密钥存储。

  • VPC 端点服务可能处于与外部密钥存储不同的 AWS 区域。请验证 VPC 端点服务和外部密钥存储是否处于同一区域。（区域名称的外部名称，例如 us-east-1，是 VPC 端点服务名称的一部分，例如 com.amazonaws.vpce.us-east-1.vpce-svc-example。） 有关对外部密钥存储的 VPC 端点服务的要求列表，请参阅 VPC 终端节点服务。您无法将 VPC 端点服务或外部密钥存储移至其他区域。但是，您可以在 VPC 端点服务所在的同一区域中创建新的外部密钥存储。有关详细信息，请参阅 配置 VPC 端点服务连接 和 创建外部密钥存储。

  • AWS KMS 不是 VPC 端点服务允许的主体。VPC 端点服务的 Allow principals（允许主体）列表必须包含 cks.kms.<region>.amazonaws.com 值，例如 cks.kms.eu-west-3.amazonaws.com。有关添加此值的说明，请参阅《AWS PrivateLink 指南》中的管理权限。

XksProxyVpcEndpointServiceInvalidConfigurationException

当 VPC 端点服务无法满足以下要求之一时，就会出现此错误：

  • VPC 需要至少两个私有子网，每个子网均位于不同的可用区内。有关将子网添加到 VPC 中的帮助，请参阅《Amazon VPC 用户指南》中的在您的 VPC 中创建子网。

  • 您的 VPC 端点服务类型必须使用网络负载均衡器，而不是网关负载均衡器。

  • 不得要求 VPC 端点服务接受请求 [Acceptance required（需要接受）必须是“false”]。如果需要手动接受每个连接请求，则 AWS KMS 将无法使用 VPC 端点服务连接到外部密钥存储代理。有关详细信息，请参阅《AWS PrivateLink 指南》中的接受或拒绝连接请求。

  • VPC 端点服务必须具有私有 DNS 名称，该名称是公有域的子域。例如，如果私有 DNS 名称为 https://myproxy-private.xks.example.com，则 xks.example.com 或 example.com 域必须具有公有 DNS 服务器。要查看或更改 VPC 端点服务的私有 DNS 名称，请参阅《AWS PrivateLink 指南》中的管理 VPC 端点服务的 DNS 名称。

  • 您的私有 DNS 名称域的 Domain verification status（域验证状态）必须为 verified。要查看和更新私有 DNS 名称域的验证状态，请参阅 步骤 5：验证私有 DNS 名称域。添加所需的文本记录后，可能需要几分钟才能显示更新的验证状态。

    注意

    只有当私有 DNS 域是公有域的子域时，才能对其进行验证。否则，即使您添加了所需的 TXT 记录，私有 DNS 域的验证状态也不会更改。

  • VPC 端点服务的私有 DNS 名称必须与外部密钥存储的代理 URI 端点值相匹配。对于使用 VPC 端点服务连接的外部密钥存储，代理 URI 端点必须是 https://，后跟 VPC 端点服务的私有 DNS 名称。要查看代理 URI 端点值，请参阅 查看外部密钥存储。要更改代理 URI 端点值，请参阅 编辑外部密钥存储属性。

外部密钥存储连接错误

将外部密钥存储连接到其外部密钥存储代理的过程大约需要五分钟才能完成。除非该过程迅速失败，否则 ConnectCustomKeyStore 操作将返回 HTTP 200 响应和无属性的 JSON 对象。但是，此初始响应不指示连接是否成功。要确定外部密钥存储是否已连接，请查看其连接状态。如果连接失败，外部密钥存储的连接状态将变为 FAILED，并且 AWS KMS 会返回一个 连接错误代码 以解释失败原因。

注意

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

查看外部密钥存储的连接状态：

  • 在 DescribeCustomKeyStores 响应中查看 ConnectionState 元素的值。

  • 在 AWS KMS控制台中，Connection state（连接状态）显示在外部密钥存储表中。此外，每个外部密钥存储的详细信息页面上的 General configuration（常规配置）部分中也显示了 Connection state（连接状态）。

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

要查看连接错误代码，请执行以下操作：

  • 在 DescribeCustomKeyStores 响应中查看 ConnectionErrorCode 元素的值。只有当 ConnectionState 为 FAILED 时，此元素才会出现在 DescribeCustomKeyStores 响应中。

  • 要在 AWS KMS 控制台中查看连接错误代码，请将鼠标悬停在外部密钥存储详细信息页面的 Failed（失败）值上。

    自定义密钥存储详细信息页面上的连接错误代码

外部密钥存储的连接错误代码

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

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 值中的主机名匹配，以及是否由受信任的证书颁发机构列表中包含的受信任的证书颁发机构签名。

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.<region>.amazonaws.com，例如 cks.kms.us-east-1.amazonaws.com。

  • 其不得要求接受连接请求。

  • 其必须具有私有 DNS 名称。使用 VPC_ENDPOINT_SERVICE 连接的外部密钥存储的私有 DNS 名称在其 AWS 区域 中必须是唯一的。

  • 私有 DNS 名称域的验证状态必须为 verified。

  • TLS 证书指定了端点可以访问的私有 DNS 主机名。

XKS_VPC_ENDPOINT_SERVICE_NOT_FOUND

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

延迟和超时错误

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

连接错误代码：XKS_PROXY_NOT_REACHABLE、XKS_PROXY_TIMED_OUT

当 AWS KMS 无法在 250 毫秒的超时间隔内联系到代理时，将返回异常。CreateCustomKeyStore 和 UpdateCustomKeyStore 会返回 XksProxyUriUnreachableException。加密操作会返回标准 KMSInvalidStateException，其中包含描述问题的错误消息。如果 ConnectCustomKeyStore 失败，则 AWS KMS 会返回描述问题的连接错误代码。

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

要跟踪延迟模式，请使用 AWS KMS 控制台 Monitoring（监控）部分中的 XksProxyLatency CloudWatch 指标和（基于该指标的）Average latency（平均延迟）图表。您的外部密钥存储代理可能还会生成跟踪延迟和超时的日志和指标。

XksProxyUriUnreachableException

AWS KMS 无法与外部密钥存储代理通信。这可能是暂时的网络问题。如果您反复看到此错误，请验证您的外部密钥存储代理是否处于活动状态并已连接到网络，以及其在外部密钥存储中的端点 URI 是否正确。

  • 外部密钥存储代理未在 250 毫秒的超时间隔内响应 AWS KMS 代理 API 请求。这可能表示出现临时网络问题或代理存在操作或性能问题。如果重试不能解决该问题，请通知您的外部密钥存储代理管理员。

延迟和超时错误通常表现为连接失败。当 ConnectCustomKeyStore 操作失败时，外部密钥存储的连接状态将变为 FAILED，并且 AWS KMS 会返回一个 连接错误代码 以解释错误。有关连接错误代码的列表和解决错误的建议，请参阅 外部密钥存储的连接错误代码。All custom key stores（所有自定义密钥存储）和 External key stores（外部密钥存储）的连接代码列表适用于外部密钥存储。以下连接错误与延迟和超时有关。

XKS_PROXY_NOT_REACHABLE

–或者–

CustomKeyStoreInvalidStateException, KMSInvalidStateException, XksProxyUriUnreachableException

AWS KMS 无法与外部密钥存储代理通信。请验证您的外部密钥存储代理是否处于活动状态并已连接到网络，以及其在外部密钥存储中的 URI 路径和端点 URI 或 VPC 服务名称是否正确。

出现此错误可能的原因如下：

  • 外部密钥存储代理未处于活动状态或未连接到网络。

  • 外部密钥存储配置中的代理 URI 端点、代理 URI 路径或 VPC 端点服务名称（如果适用）值有错误。要查看外部密钥存储，请使用 DescribeCustomKeyStores 操作，或在 AWS KMS 控制台中查看外部密钥存储的详细信息页面。

  • AWS KMS 与外部密钥存储代理之间的网络路径上可能存在网络配置错误，例如端口错误。AWS KMS 通过端口 443 与外部密钥存储代理通信。此值不可配置。

  • 当外部密钥存储代理（在 GetHealthStatus 响应中）报告所有外部密钥管理器实例均 UNAVAILABLE 时，ConnectCustomKeyStore 操作将失败，且 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 和外部密钥管理器是否可以有效通信。有关解决任何问题的帮助，请参阅《AWS Direct Connect User Guide》中的 Troubleshooting AWS Direct Connect。

XKS_PROXY_TIMED_OUT

–或者–

CustomKeyStoreInvalidStateException, KMSInvalidStateException, XksProxyUriUnreachableException

外部密钥存储代理未在分配的时间内响应请求。重试 请求。如果您反复看到此错误，请将其报告给您的外部密钥存储代理管理员。

  • 此错误可能是由外部密钥管理器与外部密钥存储代理之间的物理距离过远所致。如可行，请将外部密钥存储代理移到离外部密钥管理器更近的地方。

身份验证凭证错误

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

您在外部密钥存储代理中建立和维护 AWS KMS 身份验证凭证。然后，您在创建外部密钥存储区时告诉 AWS KMS 凭证值。要更改身份验证凭证，请在外部密钥存储代理中进行更改。然后，针对外部密钥存储更新凭证。如果您的代理轮换凭证，则必须针对外部密钥存储更新凭证。

如果外部密钥存储代理无法针对您的外部密钥存储，对具有代理身份验证凭证签名的请求进行身份验证，则效果取决于请求：

  • CreateCustomKeyStore 和 UpdateCustomKeyStore 失败，并显示 XksProxyIncorrectAuthenticationCredentialException。

  • ConnectCustomKeyStore 成功，但连接失败。连接状态为 FAILED，连接错误代码为 INVALID_CREDENTIALS。有关详细信息，请参阅外部密钥存储连接错误。

  • 加密操作将返回 KMSInvalidStateException，指出外部密钥存储中的所有外部配置错误和连接状态错误。随附的错误消息描述了问题。

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

出现此错误可能的原因如下：

  • 外部密钥存储的访问密钥 ID 或秘密访问密钥与在外部密钥存储代理上建立的值不匹配。

    要修复此错误，请针对外部密钥存储更新代理身份验证凭证。无需断开外部密钥存储的连接即可进行此更改。

  • AWS KMS 和外部密钥存储代理之间的反向代理可能会操作 HTTP 标头，从而使 SigV4 签名失效。要修复此错误，请通知您的代理管理员。

密钥状态错误

异常：KMSInvalidStateException

KMSInvalidStateException 对自定义密钥存储中的 KMS 密钥有两个不同的用途。

  • 当管理操作（例如 CancelKeyDeletion）失败并返回此异常时，这表明 KMS 密钥的密钥状态与该操作不兼容。

  • 当对自定义密钥存储中 KMS 密钥的加密操作失败，并显示 KMSInvalidStateException 时，这可能表明 KMS 密钥的密钥状态存在问题。但是，对于外部密钥存储中的所有外部配置错误和连接状态错误，AWS KMS 加密操作将返回 KMSInvalidStateException。要确定问题，请使用随异常显示的错误消息。

要查找 AWS KMS API 操作所需的密钥状态，请参阅 AWS KMS 密钥的密钥状态。要查找 KMS 密钥的密钥状态，请在 Customer managed keys（客户托管密钥）页面上，查看 KMS 密钥的 Status（状态）字段。或者，使用 DescribeKey 操作并查看响应中的 KeyState 元素。有关详细信息，请参阅识别和查看密钥。

注意

外部密钥存储中 KMS 密钥的密钥状态并不表明其关联的外部密钥的状态。有关外部密钥状态的信息，请使用外部密钥管理器和外部密钥存储代理工具。

CustomKeyStoreInvalidStateException 指的是外部密钥存储的连接状态，而不是 KMS 密钥的密钥状态。

对自定义存储中 KMS 密钥的加密操作可能会失败，因为 KMS 密钥的密钥状态为 Unavailable 或 PendingDeletion。（禁用的密钥将返回 DisabledException。）

  • 只有当您在 AWS KMS 控制台中有意禁用 KMS 密钥或使用 DisableKey 操作禁用 KMS 密钥时，KMS 密钥才会处于 Disabled 密钥状态。当某个 KMS 密钥已禁用时，您可以查看和管理该密钥，但不能在加密操作中使用该密钥。要修复此问题，请启用密钥。有关详细信息，请参阅启用和禁用密钥。

  • 当外部密钥存储与其外部密钥存储代理断开连接时，KMS 密钥会处于 Unavailable 密钥状态。要修复不可用的 KMS 密钥，请重新连接外部密钥存储。重新连接外部密钥存储后，外部密钥存储中的 KMS 密钥的密钥状态将自动还原到之前的状态，例如 Enabled 或 Disabled。

    在计划删除 KMS 密钥，或 KMS 密钥处于等待期时，其会处于 PendingDeletion 密钥状态。待删除的 KMS 密钥的密钥状态错误表明不应删除该密钥，因为其正在用于加密，或者其是解密所必需的密钥。要重新启用 KMS 密钥，请取消计划的删除，然后启用密钥。有关详细信息，请参阅计划密钥删除。

解密错误

异常：KMSInvalidStateException

当使用外部密钥存储中 KMS 密钥的 解密 操作失败时，对于外部密钥存储的所有外部配置错误和连接状态错误，AWS KMS 将返回加密操作使用的标准 KMSInvalidStateException。此错误消息指示该问题。

要解密使用 双重加密 进行加密的加密文字，外部密钥管理器应首先使用外部密钥解密加密文字的外层。然后，AWS KMS 使用 KMS 密钥中的 AWS KMS 密钥材料解密加密文字的内层。无效或损坏的加密文字可能会被外部密钥管理器或 AWS KMS 拒绝。

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

外部密钥存储代理拒绝了该请求，因为指定的加密文字或其他经过身份验证的数据已损坏、丢失或无效。

  • 当外部密钥存储代理或外部密钥管理器报告加密文字或其加密上下文无效时，通常表示发送到 AWS KMS 的 Decrypt 请求中的加密文字或加密上下文存在问题。对于 Decrypt 操作，AWS KMS 向代理发送与其在 Decrypt 请求中接收的相同的加密文字和加密上下文。

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

外部密钥存储代理提交解密的加密文字或加密上下文已损坏、丢失或无效。

  • 当 AWS KMS 拒绝其从代理收到的加密文字时，这表示外部密钥管理器或代理向 AWS KMS 返回了无效或损坏的加密文字。

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

外部密钥错误

外部密钥是外部密钥管理器中的加密密钥，用作 KMS 密钥的外部密钥材料。AWS KMS 无法直接访问外部密钥。其必须要求外部密钥管理器（通过外部密钥存储代理）使用外部密钥来加密数据或解密加密文字。

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

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

外部密钥的 CreateKey 错误

异常：XksKeyAlreadyInUseException、XksKeyNotFoundException、XksKeyInvalidConfigurationException

CreateKey 操作会尝试验证您在 External key ID（外部密钥 ID）（控制台）或 XksKeyId（API）参数中提供的外部密钥的 ID 和属性。这种做法是为了在您尝试结合使用 KMS 密钥和外部密钥之前及早发现错误。

正在使用外部密钥

外部密钥存储中的每个 KMS 密钥都必须使用不同的外部密钥。当 CreateKey 识别出 KMS 密钥的外部密钥 ID（XksKeyId）在外部密钥存储中不是唯一时，其将失败并显示 XksKeyAlreadyInUseException。

如果您为同一个外部密钥使用多个 ID，CreateKey 无法识别重复的密钥。但是，具有相同外部密钥的 KMS 密钥不可互操作，因为它们的 AWS KMS 密钥材料和元数据不同。

未找到外部密钥

当外部密钥存储代理报告无法使用 KMS 密钥的外部密钥 ID（XksKeyId）找到该外部密钥时，CreateKey 操作将会失败并返回 XksKeyNotFoundException，以及以下错误消息。

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

出现此错误可能的原因如下：

  • KMS 密钥的外部密钥（XksKeyId）ID 可能无效。要查找外部密钥代理用于识别外部密钥的 ID，请参阅外部密钥存储代理或外部密钥管理器文档。

  • 外部密钥可能已从您的外部密钥管理器中删除。要进行调查，请使用外部密钥管理器工具。如果外部密钥已永久删除，请将其他外部密钥与 KMS 密钥结合使用。有关外部密钥的列表或要求，请参阅 外部密钥存储中 KMS 密钥的要求。

未符合外部密钥要求

当外部密钥存储代理报告外部密钥不 符合要求，无法与 KMS 密钥一起使用时，CreateKey 操作将会失败并返回 XksKeyInvalidConfigurationException，以及如下错误消息中的一条。

外部密钥的密钥规格必须为 AES_256。指定的外部密钥的密钥规格为 <key-spec>。

  • 外部密钥必须是 256 位对称加密密钥，密钥规格为 AES_256。如果指定的外部密钥是不同的类型，请指定符合此要求的外部密钥的 ID。

外部密钥的状态必须为“ENABLED”（已启用）。指定外部密钥的状态为 <status>。

  • 必须在外部密钥管理器中启用外部密钥。如果未启用指定的外部密钥，请使用外部密钥管理器工具将其启用，或指定已启用的外部密钥。

外部密钥的密钥用法必须包括“ENCRYPT”（加密）和“DECRYPT”（解密）。指定的外部密钥的密钥用法是 <key-usage>。

  • 必须在外部密钥管理器中配置外部密钥以进行加密和解密。如果指定的外部密钥不包括这些操作，请使用外部密钥管理器工具更改操作，或指定其他外部密钥。

外部密钥的加密操作错误

异常：KMSInvalidStateException

当外部密钥存储代理找不到与 KMS 密钥关联的外部密钥，或者外部密钥不符合与 KMS 密钥一起使用的要求时，加密操作将失败。

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

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

未找到外部密钥

当外部密钥存储代理报告无法使用 KMS 密钥的外部密钥 ID（XksKeyId）找到外部密钥时，加密操作将返回 KMSInvalidStateException，其中包含以下错误消息。

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

出现此错误可能的原因如下：

  • KMS 密钥的外部密钥（XksKeyId）ID 不再有效。

    要查找与您的 KMS 密钥关联的外部密钥 ID，请查看 KMS 密钥的详细信息。要查找外部密钥代理用于识别外部密钥的 ID，请参阅外部密钥存储代理或外部密钥管理器文档。

    AWS KMS 在外部密钥存储中创建 KMS 密钥时，会验证外部密钥 ID。但是，ID 可能会失效，尤其是在外部密钥 ID 值是别名或可变名称的情况下。您无法更改与现有 KMS 密钥关联的外部密钥 ID。要对通过 KMS 密钥加密的任何加密文字进行解密，必须将外部密钥与现有外部密钥 ID 重新关联。

    如果您尚未使用 KMS 密钥加密数据，则可以使用有效的外部密钥 ID 创建新的 KMS 密钥。但是，如果您已使用 KMS 密钥生成加密文字，则即使使用相同的外部密钥，也无法使用任何其他 KMS 密钥来对加密文字进行解密。

  • 外部密钥可能已从您的外部密钥管理器中删除。要进行调查，请使用外部密钥管理器工具。如果可能，请尝试从外部密钥管理器的副本或备份中恢复密钥材料。如果外部密钥已永久删除，则以关联的 KMS 密钥加密的任何加密文字都将无法恢复。

外部密钥配置错误

当外部密钥存储代理报告外部密钥不 符合要求，不能与 KMS 密钥一起使用时，加密操作将返回 KMSInvalidStateException，以及如下错误消息中的一条。

外部密钥存储代理拒绝了该请求，因为外部密钥不支持所请求的操作。

  • 外部密钥必须同时支持加密和解密。如果密钥用法不包括加密和解密，请使用外部密钥管理器工具更改密钥用法。

外部密钥存储代理拒绝了该请求，因为该外部密钥未在外部密钥管理器中启用。

  • 外部密钥必须在外部密钥管理器中启用并处于可用状态。如果外部密钥的状态不是 Enabled，请使用外部密钥管理器工具将其启用。

代理问题

例外：

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

外部密钥存储代理负责调解 AWS KMS 与外部密钥管理器之间的所有通信。其还将通用 AWS KMS 请求转换为外部密钥管理器可以解析的格式。如果外部密钥存储代理不符合 AWS KMS 外部密钥存储代理 API 规范，或者运行不正常或无法与 AWS KMS 通信，则您将无法在外部密钥存储中创建或使用 KMS 密钥。

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

本节中的问题与外部密钥存储代理的设计或运行问题有关。要解决这些问题，可能需要更改代理软件。请咨询您的代理管理员。为帮助解决代理问题，AWS KMS 提供 XKS 代理测试客户端，这是一个开源测试客户端，可用于验证您的外部密钥存储代理是否符合 AWS KMS 外部密钥存储代理 API 规范。

CustomKeyStoreInvalidStateException、KMSInvalidStateException 或 XksProxyUriUnreachableException

外部密钥存储代理运行状况不佳。如果您反复看到此消息，请通知您的外部密钥存储代理管理员。

  • 此错误可能表示外部密钥存储代理存在运行问题或软件错误。您可以找到生成每个错误的 AWS KMS API 操作的 CloudTrail 日志条目。重试该操作可能会解决此错误。但是，如果问题仍然存在，请通知您的外部密钥存储代理管理员。

  • 当外部密钥存储代理（在 GetHealthStatus 响应中）报告所有外部密钥管理器实例均处于 UNAVAILABLE 状态时，对创建或更新外部密钥存储的尝试会失败，并出现此异常。如果此错误仍然存在，请查阅您的外部密钥管理器文档。

CustomKeyStoreInvalidStateException、KMSInvalidStateException 或 XksProxyInvalidResponseException

AWS KMS 无法解析来自外部密钥存储代理的响应。如果您反复看到此错误，请咨询您的外部密钥存储代理管理员。

  • 当代理返回 AWS KMS 无法解析或解释的未定义响应时，AWS KMS 操作会生成此异常。此错误可能由于暂时的外部问题或偶然的网络错误而偶尔发生。但是，如果此错误持续存在，则可能表明外部密钥存储代理不符合 AWS KMS 外部密钥存储代理 API 规范。通知您的外部密钥存储管理员或供应商。

CustomKeyStoreInvalidStateException、KMSInvalidStateException 或 UnsupportedOperationException

外部密钥存储代理拒绝了该请求，因为其不支持所请求的加密操作。

代理授权问题

异常：CustomKeyStoreInvalidStateException、KMSInvalidStateException

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

代理授权基于 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 中解决此错误。