本主题将帮助您了解使用 Cloud External Key Manager (Cloud EKM) 时可能发生的错误以及排查相关问题。
错误的结构
错误消息的结构提供尽可能多的粒度，以帮助您诊断和排查问题。错误以 google.rpc.Status 结构返回。在该结构内：
google.rpc.Status.code字段显示错误的广泛类别。google.rpc.Status.message字段显示简单易懂的消息，包括尝试执行的特定操作的详细信息以及用于排查错误的上下文相关建议。如果
google.rpc.Status.code为FAILED_PRECONDITION，则google.rpc.PreconditionFailure结构是机器可读的。它包含两个violation结构。violation[0]包含有关 Cloud EKM 密钥的状态的信息。violation[1]包含有关尝试联系外部密钥管理合作伙伴系统的信息。violation[1].type包含有关错误类型的信息。Cloud EKM 将此信息称为“错误网域”。如果这些错误仍然存在，请与外部密钥管理合作伙伴的支持团队联系。
在此参考中，google.rpc.Status.message 中的消息会被截断，以便于阅读。被截断的部分包括外部密钥 URI 或密钥路径等信息。
问题排查
使用 Cloud EKM 时，导致出现错误的可能因素包括输入错误、Cloud EKM、外部密钥管理合作伙伴系统、它们之间的通信或其他因素。您可以在每种错误类型的相应部分中阅读特定的问题排查信息。
根据错误类型，您可能需要与 Cloud EKM 支持团队或外部密钥管理合作伙伴系统支持团队联系。
如果下表中未列出您所遇到的错误，请参阅通过 VPC 错误排查 EKM 问题。
输入错误
请按照错误的 google.rpc.Status.message 字段中的问题排查建议执行操作。如果问题仍然存在，请与 Google Cloud 支持团队联系。
除非另有说明，否则本部分中的错误为 google.rpc.Status.code，其含有 FAILED_PRECONDITION。
google.rpc.Status.message |
violation[1].type（错误网域） |
问题排查 |
|---|---|---|
Permission was denied when accessing the EKM_ELEMENT. |
EXTERNAL_PERMISSION_DENIED |
当 EKM_ELEMENT 为 key 时，Cloud EKM 还会停用密钥版本。请在外部密钥管理器中授予适当的权限，然后轮替 Cloud EKM 密钥重试。如果 EKM_ELEMENT 为 crypto space 或 EKM host，请向服务账号授予适当的角色或权限，然后重试。 |
Could not find a EKM_ELEMENT 或 Could not query EKM host. |
EXTERNAL_NOT_FOUND |
当 EKM_ELEMENT 为 key 时，请检查外部密钥 URI 或密钥路径是否正确。当 EKM_ELEMENT 为 crypto space 时，请检查加密空间路径是否正确。如果无法查询 EKM host，请检查 EKM 主机名是否正确。如果拼写正确，请与外部密钥管理合作伙伴系统的支持团队联系。 |
Key URI has invalid format. |
EXTERNAL_KEY_URI_INVALID |
请检查此请求中的密钥 URI 是否正确，然后轮替 Cloud EKM 密钥重试。 |
Key URI host is not supported. |
EXTERNAL_KEY_HOST_NOT_WHITELISTED |
检查密钥 URI 是否正确。如果您自行部署外部密钥管理合作伙伴系统，请与 Google Cloud 支持团队联系。否则，请与外部密钥管理合作伙伴系统的支持团队联系。 |
Could not resolve the domain name for EKM_ELEMENT. |
DNS |
检查密钥 URI、密钥路径、加密空间或 EKM 主机名是否正确。如果正确，请与外部密钥管理合作伙伴系统的支持团队联系。 |
可重试错误
请按照错误的 google.rpc.Status.message 字段中的问题排查建议执行操作。如果您频繁看到超时或网络错误，请确保 Cloud EKM 密钥的地理位置尽可能接近您用于外部密钥的区域。如果问题仍然存在，请与外部密钥管理合作伙伴的支持团队联系。
除非另有说明，否则本部分中的错误为 google.rpc.Status.code，其含有 FAILED_PRECONDITION。EKM_ELEMENT 可以是以下值之一：key、crypto space 或 EKM host。
google.rpc.Status.message |
violation[1].type（错误网域） |
|---|---|
Throttled when trying to access key URI. |
EXTERNAL_RESOURCE_EXHAUSTED |
Could not reach the EKM_ELEMENT due to an external networking error. |
UNREACHABLE_NETWORK |
Could not reach the EKM_ELEMENT because the external key manager reports that it is overloaded. |
OVERLOADED_EKM |
Timed out when trying to access the EKM_ELEMENT. |
TIMEOUT |
| 出现此错误通常是因为 EKM 响应速度太慢。响应缓慢可能是由于 EKM 收到的请求数量超出其处理能力，或者网络延迟时间过长。 | REQUEST_CANCELLED |
外部密钥管理系统错误
如果您遇到这些错误且问题仍然存在，请与外部密钥管理合作伙伴的支持团队联系。
除非另有说明，否则本部分中的错误为 google.rpc.Status.code，其含有 FAILED_PRECONDITION。EKM_ELEMENT 可以是以下值之一：key、crypto space 或 EKM host。
google.rpc.Status.message |
violation[1].type（错误网域） |
|---|---|
Could not validate the TLS server certificate for the EKM_ELEMENT. |
TLS_CERT |
Got garbled or unusable response when trying to access the EKM_ELEMENT. |
UNEXPECTED_RESPONSE |
External server error when trying to access the EKM_ELEMENT. |
EXTERNAL_SERVER_ERROR |
The external key manager indicated they have not implemented the appropriate method to support Cloud KMS's EKM_API.
EKM_API 可以是 AsymmetricSign、CheckCryptoSpacePermissions、CreateKey、Decrypt、DestroyKey、Encrypt、GetInfo 或 GetPublicKey |
EXTERNAL_NOT_IMPLEMENTED |
Got unexpected error when trying to access the EKM_ELEMENT. |
UNEXPECTED_ERROR |
Decryption failed: The EKM reports that decryption failed.这表示密钥 URI 有效，但外部密钥管理合作伙伴系统未能解密封装的 Blob 或其他经过身份验证的数据 (AAD)。 google.rpc.Status.code 为 INVALID_ARGUMENT。 |
DECRYPTION_FAILED |
获取支持
如果您遇到未在此参考文档中列出的错误，请与 Google Cloud 支持团队联系。