クライアントサイド暗号化（CSE）を使用すると、データがドライブのサーバーに到達する前に暗号化されるため、データを制御できます。このガイドでは、Drive API を使用して CSE ファイルをプログラムで暗号化してアップロードし、ダウンロードして復号するプロセスについて説明します。また、実装をテストして検証するための推奨アプローチについても説明します。
始める前に
暗号化されたファイルを管理する前に、次のチェックリストを使用して Google Workspace ドメインを設定します。
ドメインのクライアントサイド暗号化（CSE）を設定します。
ID プロバイダ（IdP）を設定します。
キー アクセス制御リスト サービス（KACLS）が
/wrap、/unwrap、/privilegedwrap、/privilegedunwrap、/digestエンドポイントをサポートしていることを確認します。Google Cloud コンソールでプロジェクトを作成し、 Drive API を有効にします。
認証と認可
Drive API と KACLS を操作するには、認証方法を選択する必要があります。この選択は、両方のサービスとのやり取りに影響します。
- 個人: 個人として認証するには、OAuth フローを使用して、そのユーザーに代わって操作します。標準の
/wrapエンドポイントと/unwrapエンドポイントを使用し、そのユーザーの Google 認可トークンを指定します。 - 管理者: ドメイン内の他のユーザーの権限を借用するには、ドメイン全体の委任（DWD）を使用するサービス アカウントを使用します。Google 認証トークンなしで
/privilegedwrapエンドポイントと/privilegedunwrapエンドポイントを使用します。
認証情報の作成の詳細については、アクセス認証情報を作成するガイドをご覧ください。
ドメイン IdP 認証
IdP で認証するには、OAuth クライアント ID を構成し、そのクライアント シークレット ファイルをダウンロードする必要があります。アプリケーションは、IdP から認証トークンを取得して、KACLS へのリクエストを認証する必要があります。このトークンは、アプリケーションがデータ暗号鍵にアクセスできるようにするために必要です。
認証情報を安全に処理する
アプリケーションは、Drive API と IdP に対する認証用の機密性の高い認証情報を処理します。以下はその一例です。
- IdP からのシークレット マテリアル（クライアント シークレット ファイルなど）
- Google のシークレット マテリアル（service-account-private-key-file など）
- アプリによって保存されたシークレット マテリアル（保存された認証情報など）
これらの認証情報はすべて安全に保存する必要があります。
制限と割り当て
クライアントサイド暗号化が適用されたファイルには、標準のドライブの上限と割り当てが適用されます。共有ドライブの制限、一般的なファイルとフォルダの制限、割り当ての管理方法についてご確認ください。また、インポート ツールは、鍵アクセス制御リスト サービス（KACLS）と ID プロバイダ（IdP）のレート制限を処理する必要があります。
暗号化されたファイルの構造
ドライブでは、アップロードとダウンロードに次のクライアントサイド暗号化ファイル形式が想定されています。
+-------------------+
| Magic header |
+-------------------+
| Encrypted Chunk 1 |
+-------------------+
| Encrypted Chunk 2 |
+-------------------+
| ... |
+-------------------+
| Encrypted Chunk N |
+-------------------+
マジック ヘッダー
マジック ヘッダー（ファイル署名またはマジック ナンバーとも呼ばれます）は、ファイルの形式を一意に識別するためにファイルの先頭に配置される定数のバイト シーケンスです。ファイルの先頭はバイト 0x99 0x5E 0xCC 0x5E にする必要があります。
暗号化されたチャンク
ファイルは 2 MiB のチャンクに分割する必要があります。各チャンクは、Google Tink ライブラリの AEAD（Authenticated Encryption with Associated Data）プリミティブと AES-GCM 鍵タイプを使用して暗号化されます。このとき、チャンク インデックスと最終チャンク フラグが関連データとして使用されます。Drive API を使用し、この仕様に準拠したコード例については、オープンソース デモをご覧ください。
ファイルを暗号化してアップロードする
CSE ファイルをアップロードするには、アプリケーションで認証を行い、CSE トークンをリクエストし、ファイルの内容をローカルで暗号化し、暗号鍵をラップしてから、暗号化されたコンテンツとメタデータを Google ドライブにアップロードする必要があります。
CSE トークンを取得する
Drive API の Files:generateCseToken メソッドを呼び出して、Google ドライブから CSE トークンをリクエストします。リクエストに fileId クエリ パラメータが含まれていないことを確認します。特定のフォルダにファイルを作成するには、フォルダ ID を含む parent クエリ パラメータを指定します。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 でエンコードします。
詳しくは、リソースキーのハッシュをご覧ください。
暗号鍵をラップする
DEK を保護するには、外部 KACLS を使用して DEK を暗号化（ラップ）します。
- 適切なエンドポイントを呼び出します。
- 個人:
/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:wrappedKey: KACLS から受信したラップされた DEK（WDEK）。kaclsId:generateCseTokenレスポンスから受信した KACLS ID。keyFormat:"tinkAesGcmKey"aes256GcmChunkSize:"default"encryptionResourceKeyHash: コンピューティング リソースキーのハッシュで計算されたハッシュ。
オープンソースの例
暗号化とアップロードのプロセスの実用的なデモについては、オープンソース デモをご覧ください。これは動作するソリューションであり、貴重な参考資料として活用できます。
ファイルをダウンロードして復号する
CSE ファイルをダウンロードするには、Google ドライブから暗号化されたコンテンツとメタデータを取得し、KACLS から平文の DEK をリクエストして、ファイルをローカルで復号する必要があります。
ファイルのメタデータと暗号化されたコンテンツを取得する
Drive API の Files:get メソッドを呼び出して、ファイルのメタデータとコンテンツを取得します。clientEncryptionDetails には、ラップされた DEK（WDEK）と KACLS 情報を含む JWT を含む DecryptionMetadata が含まれています。
暗号鍵をアンラップする
- 適切なエンドポイントを呼び出します。
- 個人:
/unwrap - 管理者:
/privilegedunwrap
- 個人:
- WDEK、IdP 認証トークン、Google 認証トークン（必要な場合）、
resource_name、reasonを渡します。 - KACLS から平文の DEK を受け取ります。
データをローカルで復号する
- KACLS から受信した平文 DEK を使用して暗号を初期化します。
- 最初のマジック バイトをスキップし、暗号化されたファイル構造に従って残りのコンテンツを復号します。
オープンソースの例
ダウンロードと復号プロセスの実演については、オープンソース デモをご覧ください。これは動作するソリューションであり、貴重な参考資料として活用できます。
インポートしたファイルを検証する
Google は暗号鍵にアクセスできないため、ファイルを復号してサーバーサイドで検証することはできません。ローカル暗号化または鍵のラッピング フェーズでの実装エラーは、クライアントサイドでファイルの復号を行う際にエラーが発生します。独自の実装を利用する前に、徹底的な検証を行うことが重要です。
アップロードされた Google ドライブ CSE コンテンツが正しく機能するには、適切に暗号化され、正しいメタデータが含まれている必要があります。コンテンツが有効で、復号化できることを確認する責任はお客様にあります。
往復の暗号化と復号のテストを実施する
実装を検証するには、エンドツーエンドのフローをテストすることが重要です。これには、一連のテストファイルを取得し、ローカル ロジックを使用して暗号化し、API を使用してドライブにアップロードし、ダウンロードして復号化することが含まれます。復号化後、結果のコンテンツと元のファイルを比較して、同一であることを確認します。このプロセスは、暗号化、鍵のラッピング、メタデータの処理に関する問題を検出するのに役立ちます。オープンソースのデモでは、独自のアプリケーション内でこのような検証プロセスを実装する方法を示しています。
Google ドライブでスポットチェックする
アップロードされたファイルにドライブ ウェブ クライアントで鍵アイコンが表示されていることを確認します。アップロードされたファイルを少数手動でダウンロードして、想定どおりに機能することを確認します。このチェックでは、Google の CSE 実装を使用して復号を試み、暗号化または鍵ラッピング ロジックの問題を特定します。マイドライブと共有ドライブの両方のファイルを含めます。
オープンソース デモ
オープンソースの Drive CSE アップロード パッケージには、このガイドで説明する CSE アップロードとダウンロードのフローを実装する、完全な動作可能な Python ライブラリとコマンドラインの例が用意されています。独自の CSE 統合を構築する前に、デモコードを確認することを強くおすすめします。