排查透明数据加密问题

选择文档版本：

本页面介绍了如何排查 透明数据加密 (TDE) 问题在 AlloyDB Omni 中。

检索问题排查日志

如需排查 TDE 问题，您可以根据部署类型收集日志。

收集 AlloyDB Omni 服务的 systemd 日志，并过滤与 TDE 相关的消息：

sudo journalctl -u alloydbomni18 | grep "TDE"

日志可能包含如下条目：

  • TDE: TdeContext initialization failed
  • TDE: Vault server unreachable
  • TDE: Certificate expired

错误场景

本部分介绍了常见的 TDE 错误场景，并提供了建议的修复方法。

JWT 错误

如果您在收集的日志中看到 HashiCorp Vault 身份验证或初始化失败，这些失败通常与 JSON Web 令牌 (JWT) 问题有关。

说明

您可能会看到如下错误：

错误 说明 原因
TDE: Failed to register Key Store with URL: VAULT_URL, error code: 3, error message: JWT cannot be empty 找不到 JWT 或 JWT 为空 JWT 令牌缺失或为空。
TDE: Failed to register Key Store with URL: VAULT_URL, error code: 3, error message: Invalid JWT format. Expected JWS compact serialization (three dot-separated segments: header, payload, and signature) with base64url encoded values. JWT 格式错误 JWT 令牌的格式不正确，不是 JWS 紧凑序列化格式。
TDE: Failed to register Key Store with URL: VAULT_URL, error code: 3, error message: Vault request failed with HTTP code: 400, Vault errors: ["error validating token: invalid expiration time (exp) claim: token is expired"] JWT 已过期 JWT 令牌已过期。
TDE: Failed to register Key Store with URL: VAULT_URL, error code: 3, error message: Vault request failed with HTTP code: 400, Vault errors: ["error validating token: error verifying token signature: failed to verify id token signature"] JWT 签名无效 Vault 服务器无法验证 JWT 令牌的签名。
TDE: Failed to register Key Store with URL: VAULT_URL, error code: 9, error message: Failed to get Vault configuration parameter 'VAULT_JWT' 权限问题 AlloyDB Omni 缺少读取 JWT 令牌文件的权限，或者未设置 VAULT_JWT 环境变量。

如需解决 JWT 问题，请执行以下操作：

  1. 检索活跃的 JWT：

    验证 JWT 令牌路径是否在环境或服务配置中定义，例如在 override.conf 中：

    cat PATH_TO_JWT_FILE

  2. 检查 JWT 结构：确保令牌有效且符合 JWT 紧凑序列化格式。

  3. 验证令牌状态：确保令牌处于活跃状态且未过期。

KMS 网址错误

如果数据库无法初始化或启动，可能是因为密钥管理服务 (KMS) 密钥加密密钥 (KEK) 网址配置错误。

说明

您可能会看到如下错误：

错误 说明 原因
TDE: Failed to register Key Store with URL: KMS_URL, error code: 12, error message: Unsupported key store type 密钥库类型不受支持 如果 KEK 网址协议不是 vault，就会发生此错误。例如，使用 http:// 或 https:// 而不是 vault://，或者完全省略方案。
TDE: Failed to register Key Store with URL: KMS_URL, error code: 3, error message: Invalid Vault address format. Expected hostname or hostname:port Vault 地址格式无效 如果网址的 Vault 地址部分格式不正确，就会发生此错误。例如，如果它再次包含协议方案，例如 vault://https://vault.example.com:8200/...。
TDE: Failed to read KEK, error code: 3, error message: Invalid key path format. Must start with '/', not end with '/', and contain only valid characters 密钥路径格式无效 如果 Vault 网址的路径部分格式错误，就会发生此错误。路径必须以正斜杠 / 开头，并且不得以尾部斜杠结尾。
TDE: Failed to register Key Store with URL: KMS_URL, error code: 13, error message: curl_easy_perform() failed: Could not resolve hostname 主机名解析失败 如果无法解析 KEK 网址中的 Vault 主机名，就会发生此错误。如果网址格式错误（例如 vault://https:）或存在 DNS 配置问题，则可能会发生这种情况。
  • 验证 KEK 网址协议：确保网址以 vault:// 开头。请勿使用 https:// 作为前缀。
    • 正确：vault://vault.example.com:8200/v1/secret/data/key
    • 错误：https://vault.example.com:8200/v1/secret/data/key
  • 检查地址格式：确保在 vault:// 前缀后立即正确指定主机和端口。
  • 验证路径格式：确保路径以 / 开头，并且没有尾部斜杠（例如，使用 /v1/secret/data/key，而不是 /v1/secret/data/key/）。
  • 验证主机解析：确保网址中指定的 Vault 主机名正确，并且可以从数据库服务器内解析。

KEK 未采用 base64 编码

如果存储在 HashiCorp Vault 中的 KEK 未正确采用 base64 编码，AlloyDB Omni 在检索时无法对其进行解码。这会阻止它解封本地数据加密密钥 (DEK)，并导致启动失败。

说明

您可能会在数据库诊断日志 (postgresql.log) 中看到如下错误：

错误 说明 原因
TDE: Failed to read KEK, error code: 13, error message: Error decoding base64 key string 解码 base64 密钥字符串时出错 如果密钥管理器尝试使用 Base64 对从 Vault 检索到的 Secret 进行解码，但字符串不是有效的 Base64，就会发生此错误。
  • 检索 KEK 值：直接从 HashiCorp Vault 检索并检查 KEK 值。
  • 更新 Vault 中的值：确保存储在 Vault 中的 KEK 采用 base64 编码。如果它以原始二进制文件或纯文本形式存储，请使用其 base64 编码的等效值更新 Vault 中的值。
    1. 将原始密钥转换为 Base64： 
      echo -n "RAW_KEY" | base64
    2. 将 HashiCorp Vault 中的 Secret 更新为生成的 base64 编码的字符串。

Vault 中缺少 KEK 版本

当 AlloyDB Omni 尝试使用特定历史版本的 KEK 解封本地 DEK，但该版本在 HashiCorp Vault 中被删除、销毁或缺失时，就会发生 Vault 中缺少 KEK 版本的错误。这种情况在备份恢复操作或备用副本初始化期间最为常见。

说明

您可能会在数据库诊断日志 (postgresql.log) 中看到如下错误：

错误 说明 原因
TDE: Failed to read KEK, error code: 5, error message: Vault request failed with HTTP code: 404, Response body: {... "destroyed":true, "version":4 ...} 密钥版本已销毁 请求的 KEK 版本在 Vault 中被永久销毁。
  • 验证 Vault 中的 KEK 版本：确保请求的 KEK 版本在 HashiCorp Vault 中存在且处于活跃状态（未被删除或销毁）。
  • 恢复缺失的 KEK 版本：如果请求的 KEK 版本已被删除但未被销毁，请在 Vault 中恢复或取消删除该版本。
  • 处理已销毁的密钥：如果请求的密钥版本在 Vault 中被永久销毁，则使用该版本加密的数据或备份将永久无法恢复。

TLS 或 SSL 证书错误或缺失

如果 AlloyDB Omni 无法与 HashiCorp Vault 建立安全的 TLS 连接，因为证书缺失、过期、不受信任或配置错误，就会发生 TLS 或 SSL 证书错误或缺失的错误。

说明

您可能会在数据库诊断日志 (postgresql.log) 中看到如下错误：

错误 说明 原因
TDE: Failed to read KEK, error code: 13, error message: curl_easy_perform() failed: SSL peer certificate or SSH remote key was not OK
Or
TDE: Failed to read KEK, error code: 13, error message: curl_easy_perform() failed: Peer certificate cannot be authenticated with given CA certificates		 Vault 服务器证书验证失败 无法使用提供的 CA 证书验证 Vault 服务器的证书。
TDE: Failed to register Key Store with URL: VAULT_URL, error code: 13, error message: curl_easy_perform() failed: Problem with the local SSL certificate 本地 SSL 证书存在问题 如果需要客户端证书但存在问题，就会发生此错误。

如需解决 TLS 验证问题，请确保 postgres 用户提供、装载和读取的证书正确无误。

Linux 要求在 VAULT_CERT_PATH 环境变量中指定的路径下提供证书。

  1. 确认 VAULT_CERT_PATH 在环境或服务替换中设置正确：

    systemctl show alloydbomni18 -p Environment

  2. 检查证书文件是否存在，以及 postgres 用户是否可以读取这些文件：

    ls -la VAULT_CERT_PATH

    确保 ca.crt、tls.crt 和 tls.key 文件名存在，并且 postgres 用户对这些文件名具有读取权限。