Enkripsi

Capgo menyediakan enkripsi end-to-end yang robust untuk bundle aplikasi Anda, memastikan bahwa code JavaScript dan aset Anda terlindungi selama transmisi dan penyimpanan. Sistem enkripsi ini dirancang untuk memberikan Anda kendali penuh atas keamanan aplikasi sambil tetap mempertahankan kenyamanan live updates.

Ikhtisar

Sistem enkripsi Capgo menggunakan metode kriptografi standar industri untuk melindungi bundle Anda dari akses tidak sah. Saat enkripsi diaktifkan, bundle Anda dienkripsi sebelum meninggalkan lingkungan pengembangan Anda dan tetap terenkripsi hingga didekripsi oleh aplikasi Anda di perangkat pengguna.

Apa yang Sebenarnya Dilindungi oleh Enkripsi: Berbeda dengan sistem OTA yang hanya menandatangani update, Capgo mengenkripsi bundle yang di-upload sebelum disimpan dan dikirim. Ini melindungi isi bundle dari akses sembarangan saat disimpan atau transit, serta memastikan hanya pemegang private key Anda yang bisa membuat update terenkripsi yang valid. Ini tidak tidak membuat aset web yang sudah dirilis mustahil untuk di-reverse engineer: public key yang digunakan client untuk mendekripsi update didistribusikan di dalam aplikasi, sehingga penyerang yang gigih tetap bisa mengekstraknya dan memeriksa isi bundle dengan upaya yang cukup.

Kapan Anda Membutuhkan Enkripsi

Jika Anda meng-upload bundle tanpa enkripsi, anggaplah itu sebagai aset publik. Private channel membatasi perangkat mana yang menerima update, tetapi tidak membuat bundle yang di-upload menjadi rahasia. Enkripsi berguna jika Anda ingin perlindungan lebih baik saat disimpan dan transit, serta ingin hanya pemegang private key yang bisa mempublikasikan update terenkripsi yang valid. Ini tidak menjamin JavaScript, HTML, atau CSS yang sudah dirilis tidak akan pernah bisa diperiksa.

Model Ancaman

Enkripsi Capgo melindungi dari paparan bundle oleh Capgo, penyedia penyimpanan, CDN, atau siapa pun yang hanya melihat artefak pengiriman terenkripsi. Ini juga mencegah pihak ketiga membuat update terenkripsi yang valid tanpa kunci privat Anda. Karena kunci publik tertanam di aplikasi yang didistribusikan agar klien dapat mendekripsi update, seseorang yang memiliki biner aplikasi Anda dan motivasi yang cukup masih dapat memulihkan materi kunci yang diperlukan untuk memeriksa bundle.

Tips

Enkripsi sangat penting untuk:

• Aplikasi yang menangani data sensitif atau logika bisnis
• Aplikasi enterprise dengan persyaratan kepatuhan
• Aplikasi yang di-deploy di industri yang diatur
• Organisasi dengan kebijakan keamanan yang ketat

Model keamanan

Kerahasiaan terhadap Capgo

Kunci privat RSA Anda dibuat dan disimpan di mesin Anda. Capgo CLI tidak pernah mengirimkan kunci privat Anda, dan Capgo tidak menyimpannya. Capgo juga tidak menyimpan kunci publik RSA Anda secara penuh: upload hanya mencakup key_id (20 karakter pertama dari body PEM) agar channel bisa mencocokkan key pair yang Anda pakai.

Full bundle terenkripsi disimpan dan dikirim sebagai ciphertext AES-128-CBC. Layanan Capgo, CDN, object storage, maupun siapa pun di jalur pengiriman yang hanya melihat artefak yang dihosting tidak bisa membaca JavaScript, HTML, atau aset Anda tanpa private key Anda.

Kerahasiaan maksimal dari Capgo

Enkripsi default sudah menjaga bundle konten tetap rahasia di penyimpanan Capgo dan saat transit. Jika Anda juga ingin membatasi informasi yang bisa dipelajari Capgo dengan menghubungkan update channel ke binary store tertentu, ikuti panduan berikut.

Gunakan app ID Capgo khusus. Atur plugins.CapacitorUpdater.appId (Capgo Anda app_id) ke nilai yang tidak sama dengan iOS bundle ID atau Android application ID Anda. Build Store dan MDM menyematkan RSA public key Anda di capacitor.config. Saat Capgo app_id cocok dengan nama package store, akan lebih mudah mengaitkan aplikasi Capgo dengan binary yang dipublikasikan yang berisi public key tersebut. App ID Capgo yang terpisah mencegah kaitan langsung tersebut.

Capgo Builder dan public key. Capgo Builder mengunggah zip proyek Anda dengan capacitor.config (dan native tree), termasuk plugins.CapacitorUpdater.publicKey setelah key save. Agar public key tidak masuk ke upload Builder:

• Build aplikasi native secara lokal atau di CI Anda sendiri saat kerahasiaan dari Capgo penting, dan hindari mengunggah tree tersebut melalui Capgo Builder selama public key masih ada di config, atau
• Tambahkan public key dengan key save hanya setelah semua upload Builder yang tidak boleh mengekspos key sudah selesai, atau
• Jika Anda mengandalkan Capgo Builder untuk native builds, anggap workflow ini memberikan integritas (checksum bertanda tangan) tetapi jangan tidak asumsikan kerahasiaan dari Capgo setelah public key disertakan dalam upload Builder.

Enkripsikan upload delta. Isi file delta (parsial) berupa plaintext kecuali jika Anda menggunakan @capgo/capacitor-updater 6.14.4 atau yang lebih baru (enkripsi parsial otomatis diaktifkan untuk upload terenkripsi pada versi updater yang didukung) atau teruskan --encrypt-partial aktif bundle upload. Bahkan dengan enkripsi parsial, nama file yang tercantum dalam delta manifest tidak dienkripsi; hanya hash per file yang dibungkus RSA.

Integritas

Setelah dekripsi, updater menghitung SHA-256 atas bundle dan membandingkannya dengan checksum yang dipulihkan dari tanda tangan yang dibungkus RSA. Jika tidak cocok, bundle dihapus dan tidak pernah diaktifkan:

• Android memeriksa checksum setelah dekripsi dan sebelum mengekstrak arsip.
• iOS mendekripsi dan mengekstrak terlebih dahulu, lalu memverifikasi checksum sebelum bundle dapat diaktifkan.

Jika kunci publik dikonfigurasi, checksum yang hilang atau tidak ditandatangani RSA dengan benar akan ditolak.

Penanganan key

Untuk setiap upload zip penuh, CLI menghasilkan acak baru AES-128 session key baru secara acak dan IV 16-byte, mengenkripsi bundle dengan AES-128-CBC, dan mengenkripsi session key dengan RSA-2048 private key menggunakan PKCS#1 v1.5 tipe 1 padding. Perangkat memulihkan AES key dengan RSA public key yang tertanam di app. Key dan IV tidak digunakan ulang di antara upload bundle CLI yang terpisah. Dalam satu delta upload, semua file parsial terenkripsi memakai session key dan IV dari upload tersebut.

Public key untuk dekripsi tertanam di app yang Anda rilis. Konten bundle plaintext tersedia di perangkat yang menjalankan app melalui jalur dekripsi yang sama dengan updater, serupa dengan aset lain di paket app.

Kegagalan dan pelaporan

Kegagalan dekripsi dan checksum dilaporkan sebagai event stats (download_fail, checksum_fail, decrypt_fail) ke endpoint stats Capgo atau handler statistik self-hosted. Statistik dikirim dari perangkat; tidak ada laporan yang dikirim ke host bundle pihak ketiga berdasarkan keberhasilan atau kegagalan dekripsi. Setiap percobaan biasanya berupa unduhan penuh yang diinisiasi perangkat, sehingga probing gaya padding-oracle tidak praktis, dan plaintext yang dimodifikasi tetap gagal pada checksum yang ditandatangani.

Hardening di masa depan

Rilis mayor di masa depan mungkin menambahkan format berversi dengan AES-GCM dan RSA-PSS di atas hash sebagai defense in depth di samping desain saat ini. Itu akan menjadi langkah penguatan bertahap, bukan perbaikan keamanan darurat untuk format saat ini.

Cara Kerja Enkripsi

Capgo menggunakan pendekatan enkripsi hibrida yang menggabungkan enkripsi RSA dan AES untuk keamanan dan kinerja optimal:

1. Pembuatan Key

• Kunci Privat: Dibuat dan disimpan dengan aman di environment development Anda (digunakan untuk enkripsi)
• Kunci Publik: Diturunkan dari private key Anda dan disimpan di config Capacitor aplikasi Anda (digunakan untuk dekripsi)
• Kunci Sesi: Key AES acak yang dibuat untuk setiap upload bundle

2. Proses Enkripsi

1. Session key AES acak dibuat untuk setiap upload bundle
2. Bundle Anda dienkripsi menggunakan kunci sesi AES
3. Checksum bundle dihitung
4. Kunci sesi AES dan checksum dienkripsi bersama menggunakan kunci privat RSA Anda (membuat “signature”)
5. Bundle terenkripsi dan signature terenkripsi disimpan

Checksum dienkripsi bersama kunci AES untuk mencegah manipulasi. Karena hanya kunci privat RSA Anda yang dapat membuat signature ini, dan hanya kunci publik yang sesuai yang dapat mendekripsinya, hal ini memastikan bahwa kunci sesi AES dan checksum yang diharapkan bersifat autentik dan tidak dimodifikasi oleh penyerang.

3. Proses Dekripsi

1. Aplikasi Anda mengunduh bundle terenkripsi dan signature terenkripsi
2. Capgo SDK menggunakan kunci publik RSA Anda (disimpan di aplikasi) untuk mendekripsi signature
3. Ini mengungkapkan kunci sesi AES dan checksum asli
4. Kunci sesi AES digunakan untuk mendekripsi bundle
5. Checksum dari bundle yang didekripsi dihitung dan dibandingkan dengan checksum asli untuk verifikasi integritas

Proses ini memastikan bahwa meskipun penyerang mencegat bundle terenkripsi, mereka tidak dapat mengubah AES session key atau memberikan checksum palsu, karena mereka memerlukan private key Anda untuk membuat signature valid yang dapat didekripsi oleh public key.

Tips

RSA tidak bisa mengenkripsi data dalam jumlah besar secara efisien, jadi AES digunakan untuk enkripsi bundle yang sebenarnya, sementara RSA mengamankan AES key dan menyediakan verifikasi integritas melalui checksum signing.

Capgo vs Platform Lain

Fitur	Capgo	Platform OTA Lainnya
Konten Bundle	Terenkripsi saat disimpan/ditransmisikan; tetap dapat diinspeksi oleh reverse engineer yang gigih dengan binary aplikasi	Dapat dibaca secara publik
Metode Keamanan	Enkripsi end-to-end yang benar	hanya signing Code
Tingkat Privasi	Perlindungan pengiriman/penyimpanan yang kuat; bukan anti-reverse-engineering	Platform dapat mengakses code Anda
Perlindungan	Konten + integritas + keaslian	Hanya integritas + keaslian

Mengapa Ini Penting:

• signing Code hanya memverifikasi bahwa update tidak diubah dan berasal dari sumber yang benar
• Enkripsi Capgo melindungi bundle saat disimpan dan dikirim, serta mempersulit pemalsuan update terenkripsi karena penyerang membutuhkan private key Anda
• Reverse engineering masih mungkin dilakukan setelah aplikasi dirilis, karena klien berisi kunci publik yang diperlukan untuk mendekripsi dan memuat update

Metode Enkripsi

Capgo menggunakan Encryption V2 sebagai metode enkripsi standar:

Encryption V2 (Standar Saat Ini)

• Menggunakan RSA-4096 untuk keamanan yang lebih baik
• AES-256-GCM untuk enkripsi terautentikasi
• Menyediakan verifikasi integritas
• Performa dan keamanan lebih baik

Enkripsi V1 (Usang)

• Menggunakan RSA-2048 untuk enkripsi kunci
• AES-256-CBC untuk enkripsi bundle
• Tidak lagi tersedia di CLI saat ini
• Aplikasi lama yang menggunakan V1 harus migrasi ke V2

Bahaya

Encryption V1 tidak lagi didukung di Capgo CLI saat ini. Jika Anda menggunakan enkripsi V1, Anda harus migrasi ke V2. Lihat panduan migrasi untuk instruksi detail.

Menyiapkan Enkripsi

Langkah 1: Membuat Kunci Enkripsi

Pertama, buat kunci enkripsi Anda menggunakan Capgo CLI:

# Generate new encryption keys (creates files in current directory)
npx @capgo/cli@latest key create

Ini membuat:

• .capgo_key_v2: Kunci privat Anda (jaga kerahasiaannya!)
• .capgo_key_v2.pub: Kunci publik Anda (digunakan oleh aplikasi Anda)

File-file ini dibuat di direktori tempat Anda menjalankan perintah.

Peringatan

Catatan Penting Penyimpanan:

• Private Key (.capgo_key_v2): Jangan pernah commit ke version control. File ini harus dijaga keamanannya dan hanya digunakan untuk enkripsi saat bundle upload.
• Kunci Publik (.capgo_key_v2.pub): Aman untuk di-commit ke version control karena ini adalah backup dari public key Anda.
• Lokasi File: Key dibuat di direktori aktif tempat Anda menjalankan key create perintah.
• Public Key di Config: Anda harus menjalankan key save untuk menyimpan public key di config Capacitor agar bisa digunakan oleh aplikasi mobile.

Untuk penggunaan produksi, simpan private key dengan aman (environment variables, key management services) dan hapus dari proyek lokal setelah setup.

Langkah 2: Simpan Public Key ke Konfigurasi Capacitor (Wajib)

Anda harus simpan public key Anda ke konfigurasi Capacitor agar aplikasi mobile Anda dapat mendekripsi bundle:

# Save public key from file to Capacitor config (required)
npx @capgo/cli@latest key save --key ./.capgo_key_v2.pub

# Or save public key data directly
npx @capgo/cli@latest key save --key-data "$CAPGO_PUBLIC_KEY"

Langkah 3: Sinkronkan Platform Capacitor (Wajib)

Setelah menyimpan public key, Anda harus sinkronkan platform Capacitor untuk menyalin config yang diperbarui ke lapisan native:

# Sync the platform to copy config to native
npx cap sync

Peringatan

Langkah Wajib:

1. Panduan key save command menyimpan public key di config Capacitor Anda
2. npx cap sync menyalin config ini ke lapisan native agar aplikasi mobile dapat mengaksesnya
3. Tanpa kedua langkah ini, aplikasi Anda tidak akan dapat mendekripsi update terenkripsi

Mengenkripsi Bundle

Metode 1: Enkripsi Saat Upload

Cara termudah adalah melakukan enkripsi saat proses upload:

# Upload with automatic encryption
npx @capgo/cli@latest bundle upload --key-v2

# For external storage, you must encrypt first (see Manual Encryption Workflow below)

Metode 2: Workflow Enkripsi Manual

Untuk kontrol lebih, Anda bisa mengenkripsi bundle secara manual:

1. Buat bundle zip:

   npx @capgo/cli@latest bundle zip com.example.app --path ./dist --key-v2

2. Enkripsi bundle:

   npx @capgo/cli@latest bundle encrypt ./com.example.app.zip CHECKSUM_FROM_STEP_1

3. Upload ke storage Anda (misalnya, S3) dan daftarkan di Capgo:

   # First upload the encrypted bundle to your storage (e.g., AWS S3)
   aws s3 cp ./encrypted-bundle.zip s3://your-bucket/encrypted-bundle.zip
   
   # Then register with Capgo using the external URL
   npx @capgo/cli@latest bundle upload --external https://your-storage.com/encrypted-bundle.zip --iv-session-key IV_SESSION_KEY_FROM_STEP_2

Manajemen Kunci

Penyimpanan Key yang Aman

Opsi Private Key:

1. Berdasarkan file (pengembangan lokal):

   # Key stored as .capgo_key_v2 file in project root
   npx @capgo/cli@latest bundle upload --key-v2

2. Variabel lingkungan (CI/CD):

   # Store in environment variable for CI
   export CAPGO_PRIVATE_KEY="$(cat .capgo_key_v2)"
   npx @capgo/cli@latest bundle upload --key-data-v2 "$CAPGO_PRIVATE_KEY"

Setup Public Key (Wajib):

# Must save public key to Capacitor config for mobile app
npx @capgo/cli@latest key save --key ./.capgo_key_v2.pub

Lingkungan Produksi:

• Simpan private key di layanan manajemen kunci yang aman (AWS KMS, Azure Key Vault, dll.)
• Gunakan secret management CI/CD untuk private key
• Jangan pernah commit private key ke version control

Penggunaan Key:

• Kunci Privat: Digunakan oleh CLI untuk enkripsi saat upload bundle (jaga kerahasiaannya)
• Kunci Publik: Disimpan di konfigurasi aplikasi untuk dekripsi di perangkat (aman untuk di-commit)

Rotasi setelah private key dikompromikan

Rotasikan pasangan kunci jika kunci privat diduga atau terkonfirmasi terkompromi. Rotasi rutin berdasarkan kalender tidak diperlukan. Ini adalah migrasi kunci native, bukan perubahan OTA saja.

1. Buat pasangan kunci pengganti:

   npx @capgo/cli@latest key create

2. Simpan kunci publik pengganti ke konfigurasi Capacitor Anda:

   npx @capgo/cli@latest key save --key ./.capgo_key_v2.pub

3. Sinkronkan dan rilis versi native: Jalankan npx cap sync, lalu distribusikan versi native app baru yang berisi public key pengganti.

4. Targetkan versi native baru: Perangkat yang masih menjalankan binary native lama tidak bisa mendekripsi update yang dienkripsi dengan key pengganti. Gunakan Targeting Versi untuk membatasi bundle key pengganti ke versi native baru saja, sementara perangkat lain update lewat store atau MDM.

5. Ganti upload secret Anda: Segera setelah rilis native tersebut live, ganti private key di CI dan upload hanya bundle yang ditargetkan ke versi native yang berisi public key pengganti.

Peringatan

Jika private key bocor, segera hentikan penggunaannya. Instalasi yang ada dengan public key lama perlu update dari native store atau MDM sebelum bisa menerima bundle yang dienkripsi dengan key pengganti.

Praktik Terbaik Keamanan

Keamanan Key

• Jangan pernah membagikan private key antar environment atau anggota tim
• Gunakan key yang berbeda untuk tiap environment (dev, staging, production)
• Rotasi setelah terjadi kebocoran: ganti pasangan kunci jika kunci privat dicurigai atau terkonfirmasi telah bocor; rotasi rutin secara berkala tidak diperlukan
• Simpan key dengan aman menggunakan sistem manajemen kunci yang tepat

Keamanan Bundle

• Selalu verifikasi integritas bundle setelah dekripsi
• Pantau untuk pola download atau kegagalan yang tidak biasa
• Gunakan HTTPS untuk semua URL bundle (wajib untuk aplikasi mobile)
• Terapkan penanganan error yang tepat untuk kegagalan dekripsi

Kontrol Akses

• Batasi akses ke kunci enkripsi hanya untuk personel berwenang
• Gunakan akses berbasis role untuk operasi manajemen kunci
• Audit penggunaan dan akses kunci secara rutin
• Terapkan prosedur backup dan recovery yang tepat

Troubleshooting enkripsi

Masalah Umum

Gagal dekripsi:

• Pastikan kunci privat cocok dengan kunci publik yang digunakan untuk enkripsi
• Periksa bahwa ivSessionKey benar
• Pastikan Anda menggunakan Encryption V2 (V1 tidak lagi didukung)

Error terkait kunci:

• Konfirmasi format kunci privat benar (format PEM)
• Pastikan kunci tidak rusak selama penyimpanan/transfer
• Periksa bahwa kunci memiliki izin yang tepat di konfigurasi aplikasi Anda

Masalah performa:

• Bundle besar mungkin butuh waktu lebih lama untuk dienkripsi/didekripsi
• Pertimbangkan penggunaan Delta updates untuk mengurangi ukuran bundle
• Pantau kinerja perangkat selama dekripsi

Perintah Debug

Periksa status enkripsi:

npx @capgo/cli@latest app debug

Uji alur kerja enkripsi/dekripsi:

# Test the complete workflow: zip → encrypt → decrypt → unzip
npx @capgo/cli@latest bundle zip com.example.app --key-v2
npx @capgo/cli@latest bundle encrypt ./com.example.app.zip CHECKSUM --json
npx @capgo/cli@latest bundle decrypt ./encrypted-bundle.zip IV_SESSION_KEY

Kepatuhan dan Standar

Implementasi enkripsi Capgo mengikuti standar industri:

• AES-256: Algoritma enkripsi yang disetujui FIPS 140-2
• RSA-4096: Enkripsi asimetris kuat untuk proteksi kunci
• Mode GCM: Menjamin kerahasiaan sekaligus autentisitas
• Secure Random: Pembangkitan angka acak yang aman secara kriptografi

Hal ini membuat Capgo cocok untuk aplikasi yang butuh kepatuhan terhadap:

• GDPR (General Data Protection Regulation)
• HIPAA (Health Insurance Portability and Accountability Act)
• SOC 2 (Service Organization Control 2)
• ISO 27001 (Manajemen Keamanan Informasi)

Pertimbangan Performa

Overhead Enkripsi

• Ukuran bundle: Bundle terenkripsi sedikit lebih besar (overhead ~1-2%)
• Waktu pemrosesan: Enkripsi/dekripsi menambah latensi minimal
• Penggunaan memori: Peningkatan sementara selama operasi enkripsi/dekripsi

Tips Optimasi

• Gunakan Delta updates untuk meminimalkan transfer data terenkripsi
• Optimalkan ukuran bundle Anda dengan mengonversi gambar ke format WebP
• Minify file JavaScript dan CSS sebelum bundling
• Hapus dependensi yang tidak terpakai dan code
• Pantau performa pada perangkat lama/lambat

Langkah Berikutnya

• Pelajari tentang Penyimpanan Kustom untuk menggunakan enkripsi dengan infrastruktur Anda sendiri
• Jelajahi Channel untuk mengelola bundle terenkripsi di berbagai environment
• Siapkan Integrasi CI/CD untuk mengotomatiskan deployment terenkripsi

Lanjutkan dari Encryption

Jika Anda menggunakan Enkripsi untuk merencanakan keamanan dan kepatuhan, hubungkan dengan Kepatuhan untuk detail implementasi pada Compliance, Capgo Pemindai Keamanan untuk alur kerja produk di Capgo Security Scanner, Keamanan Capgo untuk alur kerja produk di Capgo Security, Capgo Pusat Kepercayaan untuk alur kerja produk di Capgo Trust Center, dan Keamanan organisasi untuk detail implementasi di Organization Security.