用戶端加密 (CSE) 可確保資料在傳送至 Google 雲端硬碟伺服器前經過加密，讓您掌握資料控制權。本指南將逐步說明如何使用 Drive API，以程式輔助方式加密及上傳 CSE 檔案，以及下載及解密 CSE 檔案。此外，本指南也涵蓋測試及驗證導入作業的建議方法。
事前準備
管理加密檔案前，請先使用下列檢查清單設定 Google Workspace 網域：
為網域設定用戶端加密 (CSE)。
確認金鑰存取控制清單服務 (KACLS) 支援
/wrap、/unwrap、/privilegedwrap、/privilegedunwrap和/digest端點。在 Google Cloud 控制台中建立專案，並啟用 Drive API。
驗證及授權
如要與 Drive API 和 KACLS 互動，您必須選擇驗證方式。這項選擇會影響您與這兩項服務的互動方式：
- 個人：如要以個人身分進行驗證，請使用 OAuth 流程代表該使用者執行動作。使用標準
/wrap和/unwrap端點，並提供該使用者的 Google 授權權杖。 - 管理員：如要在網域中模擬其他使用者，請使用服務帳戶搭配全網域委派 (DWD)。使用
/privilegedwrap和/privilegedunwrap端點，無需 Google 授權權杖。
如要進一步瞭解如何建立憑證，請參閱「建立存取憑證」指南。
網域 IdP 驗證
如要透過 IdP 進行驗證，您必須設定 OAuth 用戶端 ID，並下載其用戶端密鑰檔案。應用程式必須從 IdP 取得驗證權杖，才能驗證對 KACLS 的要求。應用程式必須使用這個權杖，才能存取資料加密金鑰。
安全處理憑證
您的應用程式會處理機密憑證，以向 Drive API 和 IdP 進行驗證。包括：
- IdP 的密鑰資料，例如用戶端密鑰檔案
- Google 提供的密鑰資料，例如服務帳戶私密金鑰檔案
- 應用程式儲存的私密資料，例如已儲存的憑證
請務必妥善儲存所有這些憑證。
限制與配額
用戶端加密檔案適用標準雲端硬碟限制和配額。請注意共用雲端硬碟限制、一般檔案和資料夾限制，以及如何管理配額。此外，匯入工具必須處理金鑰存取控管清單服務 (KACLS) 和身分識別提供者 (IdP) 的速率限制。
加密檔案結構
雲端硬碟上傳及下載的用戶端加密檔案格式如下。
+-------------------+
| Magic header |
+-------------------+
| Encrypted Chunk 1 |
+-------------------+
| Encrypted Chunk 2 |
+-------------------+
| ... |
+-------------------+
| Encrypted Chunk N |
+-------------------+
魔術標題
魔術標頭 (又稱檔案簽章或魔術數字) 是放在檔案開頭的常數位元組序列，用於明確識別檔案格式。檔案開頭必須為 0x99 0x5E 0xCC 0x5E 位元組。
加密區塊
檔案必須分割成 2 MiB 的區塊。每個區塊都會使用 Google Tink 程式庫的「已驗證的加密與相關聯資料」(AEAD) 基本類型，搭配 AES-GCM 金鑰類型加密，並以區塊索引和最終區塊標記做為相關聯資料。如需使用 Drive API 並符合這項規格的程式碼範例，請參閱開放原始碼的示範。
加密並上傳檔案
如要上傳 CSE 檔案，應用程式必須先進行驗證、要求 CSE 權杖、在本機加密檔案內容、包裝加密金鑰，最後將加密內容和中繼資料上傳至 Google 雲端硬碟。
取得 CSE 權杖
呼叫 Drive API Files:generateCseToken 方法，向 Google 雲端硬碟要求 CSE 權杖。請確保要求中未包含 fileId 查詢參數。如要在特定資料夾中建立檔案，請加入 parent 查詢參數和資料夾 ID。如果省略 parent，系統會在使用者「我的雲端硬碟」的根資料夾中建立檔案。回應會包含上傳作業的專屬檔案 ID 和 JWT 授權權杖，這是金鑰包裝步驟的必要條件。
在本機加密資料
- 使用 Google Tink 為檔案產生專屬的資料加密金鑰 (DEK)。
- 根據加密檔案結構加密檔案內容。
計算資源金鑰雜湊值
如何計算資源金鑰雜湊：
- 從
generateCseToken收到的jwt授權權杖中，擷取resource_name和perimeter_id。如果缺少perimeter_id，請使用空字串。 - 使用明文 DEK 做為金鑰，並以字串
ResourceKeyDigest:my_resource_name:my_perimeter_id做為要簽署的資料，計算 HMAC-SHA256。 - 以 Base64 編碼產生的雜湊值。
詳情請參閱「資源金鑰雜湊」。
包裝加密金鑰
如要保護資料加密金鑰，請使用外部 KACLS 加密 (包裝) 資料加密金鑰。
- 呼叫適當的端點：
- 個人：
/wrap - 管理員：
/privilegedwrap
- 個人：
- 傳遞明文 DEK、IdP 驗證權杖、Google 授權權杖 (如有需要)、JWT 中的
resource_name和reason。 - 從 KACLS 接收經過包裝的 DEK (WDEK)。
上傳到雲端硬碟
使用 Drive API files.create 端點，對加密檔案 Blob 執行標準檔案上傳作業。在檔案中繼資料中設定下列欄位：
id：從generateCseToken回應收到的專屬檔案 ID。mimeType：application/vnd.google-gsuite.encrypted; content="application/octet-stream"。content參數可以設為原始檔案的 MIME 類型。
clientEncryptionDetails：encryptionState："encrypted"。decryptionMetadata：
開放原始碼範例
如要實際瞭解加密及上傳程序，請參閱開放原始碼範例。這項解決方案可正常運作，並做為寶貴的參考資料。
下載並解密檔案
如要下載 CSE 檔案，必須從 Google 雲端硬碟擷取已加密內容和中繼資料，向 KACLS 索取明文資料加密金鑰，然後在本機解密檔案。
擷取檔案中繼資料和加密內容
呼叫 Drive API Files:get 方法，擷取檔案的中繼資料和內容。clientEncryptionDetails 包含 DecryptionMetadata，其中包含經過包裝的 DEK (WDEK) 和含有 KACLS 資訊的 JWT。
解開加密金鑰
- 呼叫適當的端點：
- 個人：
/unwrap - 管理員：
/privilegedunwrap
- 個人：
- 傳遞 WDEK、IdP 驗證權杖、Google 授權權杖 (如有需要)、
resource_name和reason。 - 從 KACLS 接收純文字 DEK。
在本機解密資料
- 使用從 KACLS 收到的明文 DEK 初始化密碼。
- 略過初始魔術位元，並根據加密檔案結構解密其餘內容。
開放原始碼範例
如要實際瞭解下載和解密程序，請參閱開放原始碼範例。這項解決方案可正常運作，並做為寶貴的參考資料。
驗證匯入的檔案
由於 Google 無法存取加密金鑰，因此無法在伺服器端解密及驗證檔案。如果在本機加密或金鑰包裝階段發生實作錯誤，用戶端解密檔案時就會發生錯誤。使用自己的實作項目之前，請務必進行徹底驗證。
如要讓上傳的 Google 雲端硬碟 CSE 內容正常運作，必須經過適當加密並包含正確的中繼資料。您有責任確保內容有效且可解密。
執行來回加密和解密測試
如要驗證導入成果，請務必測試端對端流程。這包括取得一組測試檔案、使用本機邏輯加密檔案、使用 API 將檔案上傳至雲端硬碟，然後下載並解密檔案。解密後，請將產生的內容與原始檔案比較，確保兩者相同。這個過程有助於找出加密、金鑰包裝或中繼資料處理方面的任何問題。開放原始碼的示範應用程式，說明如何在自己的應用程式中實作這類驗證程序。
使用 Google 雲端硬碟進行抽查
確認上傳的檔案在雲端硬碟網頁版用戶端中包含鎖頭圖示。手動下載少量上傳的檔案，確認檔案運作正常。這項檢查會使用 Google 的 CSE 實作項目嘗試解密，協助找出加密或金鑰包裝邏輯中的問題。包含「我的雲端硬碟」和「共用雲端硬碟」中的檔案。
開放原始碼範例
開放原始碼的 Drive CSE 上傳套件提供完整的 Python 程式庫和指令列範例，可實作本指南所述的 CSE 上傳和下載流程。強烈建議您先檢查示範程式碼，再建構自己的自訂搜尋引擎整合。