Mengelola file terenkripsi sisi klien dengan Drive API

Enkripsi sisi klien (CSE) memastikan bahwa data Anda dienkripsi sebelum mencapai server Drive, sehingga Anda memiliki kontrol atas data Anda. Panduan ini akan memandu Anda dalam proses mengenkripsi dan mengupload, serta mendownload dan mendekripsi file CSE secara terprogram menggunakan Drive API. Selain itu, panduan ini mencakup pendekatan yang direkomendasikan untuk menguji dan memvalidasi penerapan Anda.

Sebelum memulai

Sebelum mengelola file terenkripsi, siapkan domain Google Workspace Anda menggunakan checklist berikut:

• Mengonfigurasi enkripsi sisi klien (CSE) untuk domain Anda.

• Siapkan Penyedia Identitas (IdP) Anda.

• Pastikan Layanan Daftar Kontrol Akses Kunci (KACLS) Anda mendukung endpoint /wrap, /unwrap, /privilegedwrap, /privilegedunwrap, dan /digest.

• Buat project di konsol Google Cloud dan aktifkan Drive API.

Autentikasi dan otorisasi

Untuk berinteraksi dengan Drive API dan KACLS Anda, Anda harus memilih metode autentikasi. Pilihan ini memengaruhi cara Anda berinteraksi dengan kedua layanan:

• Individu: Untuk melakukan autentikasi sebagai individu, gunakan alur OAuth untuk bertindak atas nama pengguna tersebut. Gunakan endpoint /wrap dan /unwrap standar, serta berikan token otorisasi Google untuk pengguna tersebut.
• Administrator: Untuk meniru identitas pengguna lain di domain, gunakan akun layanan dengan delegasi seluruh domain (DWD). Gunakan endpoint /privilegedwrap dan /privilegedunwrap tanpa token otorisasi Google.

Perhatian: Jika akun layanan digunakan tanpa delegasi tingkat domain, file yang dibuat akan ditambahkan ke drive akun layanan, bukan ke drive pengguna tertentu, sehingga file tidak dapat diakses oleh pengguna.

Untuk mengetahui detail tambahan terkait cara membuat kredensial, lihat panduan Membuat kredensial akses.

Autentikasi IdP Domain

Untuk melakukan autentikasi dengan IdP Anda, Anda harus mengonfigurasi ID klien OAuth dan mendownload file rahasia kliennya. Aplikasi Anda harus mendapatkan token autentikasi dari IdP Anda untuk mengautentikasi permintaan ke KACLS Anda. Token ini diperlukan untuk mengizinkan aplikasi Anda mengakses Kunci Enkripsi Data.

Menangani kredensial dengan aman

Aplikasi Anda menangani kredensial sensitif untuk mengautentikasi ke Drive API dan IdP Anda. Ini mencakup:

• Materi rahasia dari IdP, seperti client-secret-file
• Materi rahasia dari Google, seperti service-account-private-key-file
• Materi rahasia yang disimpan oleh aplikasi, seperti kredensial tersimpan

Anda harus memastikan bahwa semua kredensial ini disimpan dengan aman.

Batas dan kuota

File terenkripsi sisi klien tunduk pada batas dan kuota Drive standar. Perhatikan batas drive bersama, batas file dan folder umum, serta cara mengelola kuota Anda. Selain itu, alat impor Anda harus menangani batas kecepatan dari Layanan Daftar Kontrol Akses Kunci (KACLS) dan Penyedia Identitas (IdP).

Struktur file terenkripsi

Drive mengharapkan format file terenkripsi sisi klien berikut untuk upload dan download.

+-------------------+
| Magic header      |
+-------------------+
| Encrypted Chunk 1 |
+-------------------+
| Encrypted Chunk 2 |
+-------------------+
| ...               |
+-------------------+
| Encrypted Chunk N |
+-------------------+

Header ajaib

Header ajaib (juga dikenal sebagai tanda tangan file atau angka ajaib) adalah urutan byte konstan yang ditempatkan di awal file untuk mengidentifikasi formatnya secara unik. File harus dimulai dengan byte 0x99 0x5E 0xCC 0x5E.

Chunk terenkripsi

File harus dibagi menjadi beberapa bagian berukuran 2 MiB. Setiap bagian dienkripsi menggunakan primitif Enkripsi Terautentikasi dengan Data Terkait (AEAD) dari library Google Tink dengan jenis kunci AES-GCM, menggunakan indeks bagian dan tanda bagian akhir sebagai Data Terkait. Untuk contoh kode yang menggunakan Drive API dan sesuai dengan spesifikasi ini, lihat demo open source.

Peringatan: Drive tidak akan dapat mendekripsi file sisi klien yang terstruktur dengan tidak benar. Lihat teknik validasi untuk metode pengujian yang direkomendasikan.

Mengenkripsi dan mengupload file

Untuk mengupload file CSE, aplikasi Anda harus melakukan autentikasi, meminta token CSE, mengenkripsi konten file secara lokal, membungkus kunci enkripsi, dan terakhir mengupload konten dan metadata terenkripsi ke Google Drive.

Mendapatkan token CSE

Minta token CSE dari Google Drive dengan memanggil metode Drive API Files:generateCseToken. Pastikan Anda tidak menyertakan parameter kueri fileId dalam permintaan. Untuk membuat file di folder tertentu, sertakan parameter kueri parent dengan ID folder. Jika parent tidak disertakan, file akan dibuat di folder root Drive Saya pengguna. Responsnya menyertakan ID file unik untuk upload dan token otorisasi JWT, yang diperlukan untuk langkah pembungkusan kunci.

Mengenkripsi data secara lokal

1. Gunakan Google Tink untuk membuat Kunci Enkripsi Data (DEK) yang unik untuk file.
2. Enkripsi konten file sesuai dengan struktur file terenkripsi.

Menghitung Hash Kunci Resource

Untuk menghitung hash kunci resource:

1. Ekstrak resource_name dan perimeter_id dari token otorisasi jwt yang diterima dari generateCseToken. Jika perimeter_id tidak ada, gunakan string kosong.
2. Hitung HMAC-SHA256 menggunakan DEK teks biasa sebagai kunci dan string ResourceKeyDigest:my_resource_name:my_perimeter_id sebagai data yang akan ditandatangani.
3. Enkode hash yang dihasilkan menggunakan Base64.

Untuk mengetahui detail selengkapnya, lihat Hash Kunci Resource.

Gabungkan kunci enkripsi

Untuk melindungi DEK, enkripsi (bungkus) DEK menggunakan KACL eksternal Anda.

1. Panggil endpoint yang sesuai:
   • Perorangan: /wrap
   • Administrator: /privilegedwrap
2. Teruskan DEK teks biasa, token autentikasi IdP Anda, token otorisasi Google (jika diperlukan), resource_name dari JWT, dan reason.
3. Menerima DEK yang di-Wrap (WDEK) dari KACLS.

Upload ke Drive

Gunakan endpoint Drive API files.create untuk melakukan upload file standar dari blob file terenkripsi. Tetapkan kolom berikut dalam metadata file:

• id: ID file unik yang diterima dari respons generateCseToken.
• mimeType: application/vnd.google-gsuite.encrypted; content="application/octet-stream".
  • Parameter content dapat disetel ke jenis MIME file asli.
• clientEncryptionDetails:
  • encryptionState: "encrypted".
  • decryptionMetadata:
    • wrappedKey: DEK Gabungan (WDEK) yang diterima dari KACLS.
    • kaclsId: ID KACLS yang diterima dari respons generateCseToken.
    • keyFormat: "tinkAesGcmKey".
    • aes256GcmChunkSize: "default".
    • encryptionResourceKeyHash: Hash yang dikomputasi di Compute Resource Key Hash.

Catatan: Beberapa kolom memerlukan encoding base64. Lihat dokumentasi Drive API untuk mengetahui detailnya

Contoh open source

Untuk demonstrasi praktis proses mengenkripsi dan mengupload, lihat demo open source. Hal ini memberikan solusi yang berfungsi dan dapat menjadi referensi yang berharga.

Mendownload dan mendekripsi file

Mendownload file CSE memerlukan pengambilan konten dan metadata terenkripsi dari Google Drive, meminta DEK teks biasa dari KACLS Anda, dan mendekripsi file secara lokal.

Mengambil metadata file dan konten terenkripsi

Panggil metode Files:get Drive API untuk mengambil metadata dan konten file. clientEncryptionDetails berisi DecryptionMetadata yang mencakup DEK yang Di-wrap (WDEK) dan JWT yang berisi informasi KACLS.

Membuka kunci enkripsi

1. Panggil endpoint yang sesuai:
   • Perorangan: /unwrap
   • Administrator: /privilegedunwrap
2. Teruskan WDEK, token autentikasi IdP Anda, token otorisasi Google (jika diperlukan), resource_name, dan reason.
3. Menerima DEK teks biasa dari KACLS.

Mendekripsi data secara lokal

1. Lakukan inisialisasi sandi menggunakan DEK teks biasa yang diterima dari KACLS.
2. Lewati byte ajaib awal dan dekripsi konten yang tersisa sesuai dengan struktur file terenkripsi.

Contoh open source

Untuk melihat demonstrasi praktis tentang proses download dan dekripsi, lihat demo open source. Hal ini memberikan solusi yang berfungsi dan dapat menjadi referensi yang berharga.

Memvalidasi file yang diimpor

Karena Google tidak memiliki akses ke kunci enkripsi, Google tidak dapat mendekripsi dan memvalidasi file Anda di sisi server. Error penerapan selama fase enkripsi lokal atau pembungkusan kunci akan menyebabkan error saat mendekripsi file sisi klien. Validasi menyeluruh sangat penting sebelum menggunakan implementasi Anda sendiri.

Agar konten CSE Google Drive yang diupload berfungsi dengan benar, konten tersebut harus dienkripsi dengan benar dan berisi metadata yang benar. Anda bertanggung jawab untuk memastikan bahwa konten valid dan dapat didekripsi.

Melakukan pengujian enkripsi dan dekripsi roundtrip

Untuk memvalidasi implementasi Anda, penting untuk menguji alur menyeluruh. Hal ini melibatkan pengambilan serangkaian file pengujian, mengenkripsinya menggunakan logika lokal Anda, menguploadnya ke Drive menggunakan API, lalu mendownload dan mendekripsinya. Setelah dekripsi, bandingkan konten yang dihasilkan dengan file asli untuk memastikan keduanya identik. Proses ini membantu mendeteksi masalah dalam enkripsi, pembungkusan kunci, atau penanganan metadata. Demo open source menunjukkan cara menerapkan proses validasi tersebut dalam aplikasi Anda sendiri.

Memeriksa secara acak dengan Google Drive

Pastikan file yang diupload menyertakan ikon gembok di klien web Drive. Download sejumlah kecil file yang diupload secara manual untuk memverifikasi bahwa file tersebut berfungsi seperti yang diharapkan. Pemeriksaan ini menggunakan penerapan CSE Google untuk mencoba dekripsi, sehingga membantu mengisolasi masalah dalam logika pembungkusan kunci atau enkripsi Anda. Sertakan file dari Drive Saya dan Drive bersama.

Peringatan: Jangan hapus file sumber asli Anda hingga Anda sepenuhnya memvalidasi bahwa versi CSE yang diimpor dapat didekripsi.

Demo open source

Paket Upload CSE Drive open source menyediakan contoh command line dan library Python yang berfungsi dan lengkap yang menerapkan alur upload dan download CSE yang dijelaskan dalam panduan ini. Sangat disarankan untuk meninjau kode demo sebelum membuat integrasi CSE Anda sendiri.