排解透明資料加密問題

選取文件版本：

本頁說明如何排解 AlloyDB Omni 中的透明資料加密 (TDE) 問題。

擷取疑難排解記錄

如要排解 TDE 問題，可以根據部署類型收集記錄。

收集 AlloyDB Omni 服務的 systemd 記錄，並篩選出與 TDE 相關的訊息：

sudo journalctl -u alloydbomni18 | grep "TDE"

記錄可能包含類似以下的項目：

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

錯誤情況

本節說明常見的 TDE 錯誤情境，並提供建議的修正方式。

JWT 錯誤 (HashiCorp Vault)

如果收集到的記錄顯示 HashiCorp Vault 驗證或初始化失敗，通常與 JSON Web Token (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

    將 PATH_TO_JWT_FILE 替換為主機上 JWT 權杖的路徑。

  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 缺少使用者名稱 CIPHERTRUST_USER 環境變數或 Kubernetes Secret 中的 username 鍵空白。
TDE: Failed to register Key Store with URL: CIPHERTRUST_URL, error code: 3, error message: CipherTrust password cannot be empty 缺少密碼 CIPHERTRUST_PASSWORD 環境變數或 Kubernetes Secret 中的 password 鍵空白。
TDE: Failed to register Key Store with URL: CIPHERTRUST_URL, error code: 9, error message: Failed to get CipherTrust configuration parameter 'CIPHERTRUST_USER'
或
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 已在 /etc/systemd/system/alloydbomni18.service.d/override.conf 中設定：

systemctl show alloydbomni18 -p Environment

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
或
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.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 擷取的密鑰，但字串並非有效的 Base64。
  • 擷取 KEK 值：直接從 KMS (HashiCorp Vault 或 Thales CipherTrust Manager) 擷取及檢查 KEK 值。
  • 更新 KMS 中的值：請確認儲存在 KMS 中的 KEK 已採用 Base64 編碼。如果儲存為原始二進位檔或純文字，請在 KMS 中將值更新為對應的 base64 編碼值。
    1. 將原始金鑰轉換為 Base64： 
      echo -n "RAW_KEY" | base64
       將 <var>RAW_KEY</var> 替換為未編碼的金鑰值。
    2. 將 KMS 中的密鑰更新為產生的 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 ...}
或
TDE: Failed to read KEK, error code: 5, error message: CipherTrust request failed with HTTP code: 404, CipherTrust error: "NCERRResourceNotFound: ..."		 缺少或已刪除金鑰版本 KMS 中缺少、已刪除或永久銷毀所要求的 KEK 版本。
  • 在 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
或
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 使用者掛接及讀取。

Linux 預期憑證會提供在 VAULT_CERT_PATH (適用於 HashiCorp Vault) 或 CIPHERTRUST_CERT_PATH (適用於 Thales CipherTrust Manager) 環境變數中指定的路徑。

  1. 確認環境或服務覆寫中的 VAULT_CERT_PATH 或 CIPHERTRUST_CERT_PATH 設定正確無誤：

    systemctl show alloydbomni18 -p Environment

  2. 確認憑證檔案存在，且 postgres 使用者可讀取：

    ls -la CERT_PATH

    確認 ca.crt、tls.crt 和 tls.key 檔案名稱存在，且 postgres 使用者擁有讀取的權限。

將 CERT_PATH 替換為主機上 TLS 憑證目錄的路徑 (例如 /tde-tls)。