Mengelola file terenkripsi sisi klien dengan Drive API

Enkripsi sisi klien (CSE) memastikan data Anda dienkripsi sebelum mencapai server Drive, sehingga Anda dapat mengontrol data Anda. Panduan ini akan memandu Anda melalui proses mengenkripsi dan mengupload secara terprogram, serta mendownload dan mendekripsi file CSE menggunakan Drive API. Panduan ini juga mencakup pendekatan yang direkomendasikan untuk menguji dan memvalidasi penerapan Anda.

Sebelum memulai

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

• Konfigurasi 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:

• Perorangan: Untuk melakukan autentikasi sebagai perorangan, gunakan alur OAuth untuk bertindak atas nama pengguna tersebut. Gunakan endpoint standar /wrap dan /unwrap, serta berikan token otorisasi Google untuk pengguna tersebut.
• Administrator: Untuk meniru 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 seluruh 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 pembuatan 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 melakukan autentikasi ke Drive API dan IdP Anda. Kredensial ini mencakup:

• Materi rahasia dari IdP, seperti file-rahasia-klien
• Materi rahasia dari Google, seperti file-kunci-pribadi-akun-layanan
• 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 frekuensi dari Layanan Daftar Kontrol Akses Kunci (KACLS) dan Penyedia Identitas (IdP) Anda.

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.

Potongan terenkripsi

File harus dibagi menjadi potongan 2MiB. Setiap potongan dienkripsi menggunakan library Google Tink primitif Enkripsi Terautentikasi dengan Data Terkait (AEAD) dengan jenis kunci AES-GCM, menggunakan indeks potongan dan tanda potongan 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 strukturnya salah. 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, menggabungkan kunci enkripsi, dan akhirnya 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 dihilangkan, file akan dibuat di folder Drive Saya root pengguna. Responsnya mencakup ID file unik untuk upload dan token otorisasi JWT, yang diperlukan untuk langkah penggabungan kunci.

Mengenkripsi data secara lokal

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

Hash Kunci Resource Komputasi

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 Base64 hash yang dihasilkan.

Untuk mengetahui detail selengkapnya, lihat Hash Kunci Resource.

Menggabungkan kunci enkripsi

Untuk melindungi DEK, enkripsi (gabungkan) menggunakan KACLS 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. Terima DEK Gabungan (WDEK) dari KACLS.

Upload ke Drive

Gunakan endpoint Drive API files.create untuk melakukan upload file standar dari file blob 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 ditetapkan 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 dihitung di Hash Kunci Resource Komputasi.

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

Contoh open source

Untuk demonstrasi praktis proses enkripsi dan upload, 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 Drive API Files:get untuk mengambil metadata dan konten file. clientEncryptionDetails berisi DecryptionMetadata yang mencakup DEK Gabungan (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. Terima 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 demonstrasi praktis 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 penggabungan kunci akan menyebabkan error saat mendekripsi file sisi klien. Validasi menyeluruh sangat penting sebelum menggunakan penerapan 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 tersebut valid dan dapat didekripsi.

Melakukan pengujian enkripsi dan dekripsi pulang-pergi

Untuk memvalidasi penerapan Anda, penting untuk menguji alur end-to-end. Hal ini melibatkan pengambilan kumpulan 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 menangkap masalah apa pun dalam enkripsi, penggabungan kunci, atau penanganan metadata. Demo open source menunjukkan cara menerapkan proses validasi tersebut dalam aplikasi Anda sendiri.

Pemeriksaan acak dengan Google Drive

Pastikan file yang diupload menyertakan ikon kunci di klien web Drive. Download secara manual sejumlah kecil file yang diupload untuk memverifikasi bahwa file tersebut berfungsi seperti yang diharapkan. Pemeriksaan ini menggunakan penerapan CSE Google untuk mencoba dekripsi, yang membantu mengisolasi masalah dalam logika enkripsi atau penggabungan kunci 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 Drive CSE open source menyediakan library Python dan contoh command line lengkap yang berfungsi dan menerapkan alur upload dan download CSE yang dijelaskan dalam panduan ini. Sebaiknya tinjau kode demo sebelum membuat integrasi CSE Anda sendiri.