排查透明数据加密问题

选择文档版本：

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

检索问题排查日志

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

收集容器日志并过滤与 TDE 相关的消息：

docker logs CONTAINER_NAME | grep "TDE"

将 CONTAINER_NAME 替换为您的 AlloyDB Omni 容器的名称。

日志可能包含如下条目：

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

错误场景

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

JWT 错误 (HashiCorp Vault)

如果您在收集的日志中看到 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：

    运行以下命令，检查容器中由 VAULT_JWT_PATH 环境变量配置的 JWT 令牌文件：

    docker exec -it CONTAINER_NAME sh -c 'cat "$VAULT_JWT_PATH"'

    将 CONTAINER_NAME 替换为您的 AlloyDB Omni 容器的名称。

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

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

CipherTrust 凭据错误 (Thales CipherTrust Manager)

如果您在收集的日志中看到 Thales CipherTrust Manager 身份验证或初始化失败，这些失败通常是由用户凭据（username 和 password）缺失或无效引起的。

说明

您可能会看到如下错误：

错误 说明 原因
TDE: Failed to register Key Store with URL: CIPHERTRUST_URL, error code: 3, error message: CipherTrust user cannot be empty 缺少用户名 Kubernetes Secret 中的 CIPHERTRUST_USER 环境变量或 username 键为空。
TDE: Failed to register Key Store with URL: CIPHERTRUST_URL, error code: 3, error message: CipherTrust password cannot be empty 缺少密码 Kubernetes Secret 中的 CIPHERTRUST_PASSWORD 环境变量或 password 键为空。
TDE: Failed to register Key Store with URL: CIPHERTRUST_URL, error code: 9, error message: Failed to get CipherTrust configuration parameter 'CIPHERTRUST_USER'
Or
TDE: Failed to register Key Store with URL: CIPHERTRUST_URL, error code: 9, error message: Failed to get CipherTrust configuration parameter 'CIPHERTRUST_PASSWORD'		 未设置环境变量 缺少 CIPHERTRUST_USER 或 CIPHERTRUST_PASSWORD 环境变量。
TDE: Failed to register Key Store with URL: CIPHERTRUST_URL, error code: 16, error message: CipherTrust request failed with HTTP code: 401 无效凭据 Thales CipherTrust Manager 身份验证端点 (/api/v1/auth/tokens) 拒绝了 username 或 password。

验证是否在容器环境中设置了 CIPHERTRUST_USER 和 CIPHERTRUST_PASSWORD：

docker inspect CONTAINER_NAME | grep CIPHERTRUST_

将 <var>CONTAINER_NAME</var> 替换为您的 AlloyDB Omni 容器的名称。

KMS 网址错误

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

说明

您可能会看到如下错误：

错误 说明 原因
TDE: Failed to register Key Store with URL: KMS_URL, error code: 12, error message: Unsupported key store type 密钥库类型不受支持 当 KEK 网址协议不是 vault 或 ciphertrust 时，会发生此错误。例如，使用 http:// 或 https:// 而不是 vault:// 或 ciphertrust://，或者完全省略架构。
TDE: Failed to register Key Store with URL: KMS_URL, error code: 3, error message: Invalid Vault address format. Expected hostname or hostname:port
Or
TDE: Failed to register Key Store with URL: KMS_URL, error code: 3, error message: Invalid CipherTrust address format. Expected hostname or hostname:port		 KMS 地址格式无效 当网址的 KMS 地址部分格式不正确时，会发生此错误。例如，如果它再次包含协议架构，例如 vault://https://vault.example.com:8200/... 或 ciphertrust://https://ciphertrust.example.com:443/...。
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 密钥路径格式无效 当 KMS 网址的路径部分格式错误时，会发生此错误。路径必须以正斜杠 / 开头，且不得以尾部斜杠结尾。
TDE: Failed to register Key Store with URL: KMS_URL, error code: 13, error message: curl_easy_perform() failed: Could not resolve hostname 主机名解析失败 当 KEK 网址中的 KMS 主机名无法解析时，会发生此错误。如果网址格式错误或存在 DNS 配置问题，可能会发生这种情况。
  • 验证 KEK 网址协议：确保网址以 vault://（适用于 HashiCorp Vault）或 ciphertrust://（适用于 Thales CipherTrust Manager）开头。请勿使用 https:// 作为前缀。
    • 正确（Vault）：vault://vault.example.com:8200/v1/secret/data/key
    • 正确 (CipherTrust)：ciphertrust://ciphertrust.example.com:443/api/v1/vault/secrets/key
    • 不正确：https://vault.example.com:8200/v1/secret/data/key
  • 检查地址格式：确保在 vault:// 或 ciphertrust:// 前缀后立即正确指定主机和端口。
  • 验证路径格式：确保路径以 /开头，且没有尾部斜杠（例如，对于 HashiCorp Vault，使用 /v1/secret/data/key；对于 Thales CipherTrust Manager，使用 /api/v1/vault/secrets/key，不带尾部/）。
  • 验证主机解析：确保网址中指定的 KMS 主机名正确，并且可以从数据库容器内解析。

KEK 未采用 base64 编码

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

说明

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

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

KMS 中缺少 KEK 版本

当 AlloyDB Omni 尝试使用特定历史版本的 KEK 解封本地 DEK 时，但该版本在外部 KMS 中被删除、销毁或缺失，就会发生 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 ...}
Or
TDE: Failed to read KEK, error code: 5, error message: CipherTrust request failed with HTTP code: 404, CipherTrust error: "NCERRResourceNotFound: ..."		 密钥版本缺失或已销毁 请求的 KEK 版本在 KMS 中缺失、被删除或永久销毁。
  • 验证 KMS 中的 KEK 版本：确保请求的 KEK 版本在 KMS 中存在且处于活跃状态（未被删除或销毁）。
  • 恢复缺失的 KEK 版本：如果请求的 KEK 版本已被删除但未被销毁，请在 KMS 中恢复或取消删除该版本。
  • 处理已销毁的密钥：如果请求的密钥版本在 KMS 中被永久销毁，则使用该版本加密的数据或备份将永久无法恢复。

TLS 或 SSL 证书错误或缺失

当 AlloyDB Omni 无法与外部 KMS（HashiCorp Vault 或 Thales CipherTrust Manager）建立安全的 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		 KMS 服务器证书验证失败 无法使用提供的 CA 证书验证 KMS 服务器的证书。
TDE: Failed to register Key Store with URL: KMS_URL, error code: 13, error message: curl_easy_perform() failed: Problem with the local SSL certificate 本地 SSL 证书存在问题 如果需要客户端证书但存在问题，则会发生此错误。

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

Docker 要求使用装载的主机卷提供证书。

  1. 确认已设置 VAULT_CERT_PATH（适用于 HashiCorp Vault）或 CIPHERTRUST_CERT_PATH（适用于 Thales CipherTrust Manager），并且指向容器内的正确目录：

    docker inspect CONTAINER_NAME | grep _CERT_PATH

  2. 检查证书文件是否存在，并且数据库用户 (uid 999) 是否可读取这些文件：

    docker exec -it CONTAINER_NAME ls -la PATH_TO_CERTS_DIRECTORY

    确保 ca.crt、tls.crt 和 tls.key 存在，并且数据库用户拥有读取权限。

替换以下内容：

  • CONTAINER_NAME：AlloyDB Omni 容器的名称。
  • PATH_TO_CERTS_DIRECTORY：容器内证书目录的路径（例如 /tde-tls）。