Rotasi kunci

Robert Ferens

Demián Renzulli

Dokumen ini memberikan informasi penting terkait proses rotasi kunci untuk Aplikasi Web Terisolasi (IWA), termasuk kapan rotasi kunci diperlukan dan langkah-langkah yang harus diikuti developer jika kunci hilang atau disusupi.

Rotasi kunci untuk IWA

Rotasi kunci adalah mekanisme yang memungkinkan kunci pribadi yang digunakan untuk menandatangani IWA Anda diganti jika terjadi kebocoran atau kehilangan. Proses ini membuat aplikasi tetap berfungsi dan mempertahankan ID paket dan asal yang stabil, sehingga memastikan kontinuitas distribusi dan update aplikasi Anda.

Proses rotasi kunci tidak memerlukan perubahan administrator atau pengguna, dan jika dilakukan dengan benar, tidak akan terlihat oleh mereka. Saluran kontak tepercaya yang dibuat selama proses pemberian izin awal sangat penting untuk mengaktifkan rotasi kunci.

Kebutuhan akan rotasi kunci

Rotasi kunci sangat diperlukan dalam dua skenario utama:

• Kunci bocor atau disusupi: Jika kunci penandatanganan pribadi Anda disusupi atau berpotensi bocor, Anda harus segera memulai proses rotasi kunci untuk mengamankan aplikasi Anda. Kunci yang bocor dapat digunakan untuk meniru identitas Anda, menyebabkan kerugian bagi pengguna aplikasi Anda, dan membahayakan reputasi perusahaan Anda.
• Kehilangan kunci: Jika Anda kehilangan akses ke kunci penandatanganan pribadi dan tidak dapat menandatangani update baru, rotasi kunci diperlukan untuk memulihkan kemampuan Anda mendistribusikan aplikasi.

Persyaratan developer

Sebelum memulai rotasi kunci, Anda harus memenuhi kriteria berikut:

• Aplikasi yang diizinkan: Hanya aplikasi yang diizinkan yang dapat tunduk pada rotasi kunci.
• Email tepercaya: Anda harus menggunakan alamat email tepercaya yang diberikan selama proses masuk daftar yang diizinkan untuk meminta rotasi kunci.

Menandatangani ulang aplikasi yang dihosting dan merilis versi baru

Setelah merotasi kunci, semua instance aplikasi yang diinstal dan tidak ditandatangani dengan kunci yang valid akan diblokir. Untuk mencegah gangguan bagi pengguna, Anda harus mengirimkan aplikasi yang ditandatangani dengan kunci baru (atau kedua kunci). Detail teknis terkait penandatanganan ulang paket dapat ditemukan di bagian Cara menandatangani paket dengan beberapa kunci. Bergantung pada situasi spesifik Anda, ada berbagai skenario:

Skenario A: Kunci tidak hilang (misalnya, rotasi proaktif atau kebocoran)

Anda harus menandatangani aplikasi dengan kedua kunci (yang lama dan yang baru) dan mengirimkannya kepada pengguna dengan salah satu cara berikut:

• Merilis versi aplikasi baru (menambahkan versi baru ke manifes update), atau
• Memperbarui file .swbn yang dihosting (ditautkan dalam manifes update) agar ditandatangani dengan kedua kunci. Alat CLI memungkinkan Anda menambahkan tanda tangan lain ke bundle swbn yang ada.

Tindakan ini harus dilakukan sebelum rotasi kunci diproses oleh Google untuk memastikan pengguna Anda tidak akan menyadari perubahan tersebut.

Skenario B: Kunci hilang

Karena aplikasi tidak dapat ditandatangani dengan kunci yang hilang, kasus ini menjadi lebih rumit. Minta rotasi kunci dan hubungi kontak Google Anda untuk mengetahui langkah-langkah selanjutnya. Anda mungkin diminta untuk menambahkan tanda tangan baru ke paket yang dihosting dengan mengikuti petunjuk ini.

Proses rotasi kunci

Proses rotasi kunci melibatkan langkah-langkah berikut:

Memperbarui penyematan channel dan versi

Administrator terkadang menggunakan saluran update kustom atau penyematan versi, yang memungkinkan mereka mengelola versi aplikasi di perangkat klien. Setelah rotasi kunci, semua aplikasi yang diinstal dengan kunci yang tidak valid akan menjadi tidak valid dan diblokir. Untuk mencegahnya, aplikasi versi sebelumnya yang dihosting di bawah link yang disediakan di update_manifest.json juga harus diupdate dan ditandatangani dengan dua tanda tangan sebelum rotasi kunci. Jika kunci lama Anda hilang dan aplikasi tidak dapat ditandatangani dengan dua kunci, segera beri tahu kontak Google Anda. Kami akan bekerja sama dengan Anda untuk mengatasi situasi ini sehingga aplikasi dapat diupdate tanpa mengganggu alur kerja pengguna Anda.

Cara menandatangani paket dengan beberapa kunci

Bagian ini menjelaskan cara menandatangani paket web Anda dengan satu atau dua kunci melalui alat CLI, atau konfigurasi plugin Webpack/Rollup/Vite. Alat CLI juga memungkinkan penambahan satu tanda tangan lagi ke paket swbn yang ada, yang mungkin berguna dalam kasus kunci hilang atau memperbarui paket yang dihosting sebelumnya.

Alat CLI

Pertama, pastikan Anda telah menginstal paket wbn-sign dengan npm:

$ npm i wbn-sign

Tambahkan -g untuk menginstal paket secara global, bukan hanya di folder saat ini.

Menandatangani dengan satu kunci

$ wbn-sign -i unsigned.wbn -o signed.swbn -k private.pem

Menandatangani dengan dua kunci

$ wbn-sign sign webbundle.wbn old_key.pem new_key.pem -o signed.swbn --web-bundle-id <your-id-from-old-private>

Argumen --web-bundle-id <id> dapat dilewati, jika old_key adalah kunci pertama yang digunakan untuk menandatangani versi awal aplikasi, maka ID bundle akan berasal dari kunci tersebut. Anda dapat memverifikasi ID paket dengan perintah wbn-sign info signed.swbn.

Menambahkan tanda tangan ke paket yang ada

$ wbn-sign add-signature signed.swbn key3.pem --in-place

Gunakan -o jika Anda tidak ingin mengganti paket, tetapi membuat penandatanganan ganda baru.

Informasi selengkapnya tentang Alat CLI

Untuk mengetahui informasi selengkapnya tentang penggunaan alat CLI, lihat halaman npm wbn-sign. Atau, gunakan: wnb-sign help.

Plugin Webpack

Menandatangani dengan satu kunci

Untuk mengonfigurasi plugin Webpack agar menandatangani IWA Anda menggunakan satu kunci pribadi:

• Siapkan WebBundlePlugin untuk mendapatkan URL Dasar yang diperlukan secara otomatis langsung dari kunci ini.
• Gunakan satu NodeCryptoSigningStrategy untuk menghasilkan file .swbn yang ditandatangani.

// key is parsePemKey(private.pem)

plugins.push(
  new WebBundlePlugin({
    baseURL: new WebBundleId(key).serializeWithIsolatedWebAppOrigin(),
    static: { dir: 'public' },
    output: 'signed.swbn',
    integrityBlockSign: {
      strategy: new NodeCryptoSigningStrategy(key)
    }
  })
)

Menandatangani dengan dua kunci

Saat Anda perlu menandatangani aplikasi dua kali selama rotasi kunci:

• Tentukan webBundleId dan URL Dasar berdasarkan URL asli (old_key) untuk memastikan identitas aplikasi tetap stabil bagi pengguna Anda.
• Gunakan berbagai strategi penandatanganan untuk menerapkan kunci pribadi lama dan baru Anda.

// old_key is parsePemKey(old_private.pem)
// new_key is parsePemKey(new_private.pem)

plugins.push(
  new WebBundlePlugin({
    baseURL: new WebBundleId(old_key).serializeWithIsolatedWebAppOrigin(),
    static: { dir: 'public') },
    output: 'signed.swbn',
    integrityBlockSign: {
      strategies: [
        new NodeCryptoSigningStrategy(old_key),
        new NodeCryptoSigningStrategy(new_key)
      ],
      webBundleId: new WebBundleId(old_key).serialize()
    }
  })
)

Plugin Rollup atau Vite

Menandatangani dengan satu kunci

Untuk menggunakan plugin Rollup atau Vite guna menandatangani aplikasi Anda dengan satu kunci pribadi, mirip dengan penyiapan Webpack, plugin ini menggunakan satu strategi penandatanganan dan menangani pengambilan URL Dasar dari kunci yang diberikan untuk membuat output yang ditandatangani.

// key is parsePemKey(private.pem)

plugins.push({
  ...wbn({
    baseURL: new WebBundleId(key).serializeWithIsolatedWebAppOrigin(),
    static: { dir: 'public' },
    output: 'signed.swbn',
    integrityBlockSign: {
      strategy: new NodeCryptoSigningStrategy(key)
    }
  }),
  enforce: 'post'
})

Menandatangani dengan dua kunci

Untuk menandatangani aplikasi Anda dua kali menggunakan Rollup atau Vite, Anda harus mengonfigurasi plugin agar menerima beberapa kunci. Cuplikan ini menerapkan kunci pribadi lama dan baru menggunakan array strategi. Hal ini memastikan transisi yang lancar dengan mempertahankan URL Dasar dan webBundleId yang berasal dari kunci asli yang sudah ada.

// old_key is parsePemKey(old_private.pem)
// new_key is parsePemKey(new_private.pem)

plugins.push({
  ...wbn({
    baseURL: new WebBundleId(old_key).serializeWithIsolatedWebAppOrigin(),
    static: { dir: 'public' },
    output: 'signed.swbn',
    integrityBlockSign: {
      strategies: [
        new NodeCryptoSigningStrategy(old_key),
        new NodeCryptoSigningStrategy(new_key)
      ],
      webBundleId: new WebBundleId(old_key).serialize()
    }
  }),
  enforce: 'post'
})

Kesimpulan

Pengelolaan rotasi kunci yang berhasil untuk IWA Anda sangat penting untuk menjaga keamanan dan kelangsungan distribusi aplikasi Anda. Terlepas dari situasi spesifik Anda (misalnya, apakah kunci hilang atau tidak), mengikuti langkah-langkah yang diuraikan akan memastikan pengguna Anda mengalami gangguan minimal. Dengan menggunakan alat CLI atau konfigurasi plugin yang disediakan untuk Webpack, Rollup, atau Vite, Anda dapat mengelola tanda tangan aplikasi secara efisien dan menjalankan proses rotasi kunci dengan lancar. Dalam skenario darurat, ingatlah untuk berkomunikasi dengan cepat dengan kontak Google Anda melalui email tepercaya yang telah ditentukan.