排解透明資料加密問題

選取文件版本：

本頁面說明如何排解 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 Token (JWT) 問題有關。

說明

您可能會看到類似下方的錯誤訊息：

錯誤 說明 原因
TDE: Failed to register Key Store with URL: VAULT_URL, error code: 3, error message: JWT cannot be empty 找不到或沒有 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 缺少使用者名稱 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 憑證無效 username 或 password遭 Thales CipherTrust Manager 驗證端點 (/api/v1/auth/tokens) 拒絕。

確認容器環境中已設定 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
或
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: ..."		 金鑰版本遺失或已刪除 要求的 KEK 版本在 KMS 中遺失、刪除或永久刪除。
  • 驗證 KMS 中的 KEK 版本：確認 KMS 中有要求的 KEK 版本，且該版本處於有效狀態 (未刪除或銷毀)。
  • 還原遺失的 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 使用者可讀取。

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)。