金鑰輪替

Robert Ferens
Robert Ferens
Demián Renzulli
Demián Renzulli
X GitHub

本文提供有關獨立網頁應用程式 (IWA) 金鑰輪替程序的必要資訊，包括何時需要輪替金鑰，以及金鑰遺失或遭盜用時，開發人員必須採取的步驟。

IWA 的金鑰輪替

金鑰輪替機制可讓您在私密金鑰外洩或遺失時，替換用於簽署 IWA 的私密金鑰。這個程序可確保應用程式正常運作，並維持穩定的套件組合 ID 和來源，確保應用程式的發布和更新作業持續進行。

金鑰輪替程序不需要管理員或使用者進行任何變更，而且如果執行正確，他們不會察覺到任何異狀。在初始許可清單程序中建立的信任聯絡人管道，對於啟用金鑰輪替至關重要。

金鑰輪替的必要性

在下列兩種主要情況下，您必須變更金鑰：

  • 金鑰外洩或遭駭：如果私密簽署金鑰遭駭或可能外洩，請立即啟動金鑰變更程序，確保應用程式安全無虞。如果金鑰外洩，他人就能冒用您的身分、危害應用程式使用者，並損害貴公司的聲譽。
  • 金鑰遺失：如果您無法存取私密簽署金鑰，且無法簽署新版更新，就必須進行金鑰輪替，才能重新發布應用程式。

開發人員規定

發起金鑰輪替前，請務必符合下列條件：

  • 已加入許可清單的應用程式：只有已加入許可清單的應用程式才能進行金鑰輪替。
  • 信任的電子郵件地址：您必須使用在許可清單程序中提供的信任電子郵件地址，才能要求金鑰輪替。

重新簽署代管應用程式並發布新版本

變更金鑰後，系統會封鎖所有未以有效金鑰簽署的已安裝應用程式例項。為避免使用者受到影響，您必須提供以新金鑰 (或新舊金鑰) 簽署的應用程式。如要瞭解重新簽署套件的技術細節，請參閱「如何使用多個金鑰簽署套件」一節。視具體情況而定，有以下幾種情況：

情境 A：金鑰未遺失 (例如主動輪替或洩漏)

您必須使用新舊金鑰簽署應用程式，並透過下列任一方式發布給使用者：

  • 發布新版應用程式 (將新版本新增至更新資訊清單)，或
  • 更新代管的 .swbn 檔案 (連結於更新資訊清單中)，並使用這兩個金鑰簽署。您可以使用 CLI 工具，在現有的 swbn 套件中新增簽章。

請務必在 Google 處理金鑰輪替作業前完成這項操作，確保使用者不會注意到這項變更。

情境 B：遺失金鑰

由於應用程式無法使用遺失的金鑰簽署，這個案件較為複雜。 要求輪替金鑰，並向 Google 聯絡人詢問後續步驟。系統可能會要求您按照這些操作說明，將新簽章新增至代管套件。

金鑰輪替程序

金鑰輪替程序包含下列步驟：

步驟 動作 詳細資料 負責人
1 要求變更金鑰 開發人員/合作夥伴透過允許清單程序 中提供的信任電子郵件，與 Google 聯絡人 (合作夥伴工程或其他聯絡窗口) 聯絡，並要求提供金鑰輪替說明，說明原因。如果金鑰遭盜用，建議您附上更新資訊清單，並使用新舊金鑰簽署套件，加快處理速度。 開發人員 / 合作夥伴
2 回覆要求者 Google 聯絡人會向要求者提供進一步的操作說明和問題。這個步驟可能需要來回幾次。 Google 聯絡人
3 提供資料 開發人員/合作夥伴按照操作說明進行，可能包括：
  • 使用新金鑰重新簽署套件。
  • 更新或提供更新資訊清單，其中包含更新後的應用程式。
  • 提供更多資訊。例如情況詳細資料、危險或技術詳細資料 (如合作夥伴的應用程式發布週期)。
  • 確認輪替準備就緒：建議您在更新用戶端應用程式後至少三天再執行這項操作，確保應用程式已更新。
 開發人員 / 合作夥伴
4 處理要求及提供意見回饋
 Google 會審查金鑰輪替要求，並在一週內回覆，核准或拒絕要求，或聯絡開發人員詢問其他問題。核准後，Google 會輪替金鑰並提供意見回饋。 Google 聯絡人

更新頻道和版本固定設定

管理員有時會使用自訂更新管道或版本鎖定功能，以便管理用戶端裝置上的應用程式版本。金鑰輪替後，所有使用無效金鑰安裝的應用程式都會失效並遭到封鎖。為避免發生這種情況，在金鑰輪替前，也必須更新並使用兩個簽章簽署 update_manifest.json 中連結所代管的舊版應用程式。如果舊金鑰遺失，且應用程式無法使用兩個金鑰簽署，請立即通知 Google 聯絡人。我們會與您合作解決問題，確保應用程式更新時不會干擾使用者的工作流程。

如何使用多個金鑰簽署套件

本節說明如何透過 CLI 工具，或 Webpack/Rollup/Vite 外掛程式設定，使用一或兩個金鑰簽署網頁套裝組合。您也可以使用 CLI 工具，在現有的 swbn 套裝組合中新增簽章，這在金鑰遺失或更新先前代管的套裝組合時可能很有用。

CLI 工具

首先，請確認您已使用 npm 安裝 wbn-sign 套件：

$ npm i wbn-sign

新增 -g，即可全域安裝套件，而不只是在目前資料夾中安裝。

使用單一金鑰簽署

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

使用兩個金鑰簽署

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

如果 old_key 是應用程式初始版本簽署時使用的第一個金鑰，則可以略過 --web-bundle-id <id> 引數，因為套件 ID 會從該金鑰衍生而來。您可以使用 wbn-sign info signed.swbn 指令驗證套件 ID。

為現有套件新增簽章

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

如果不想覆寫套件，但要建立新的雙重簽署套件，請使用 -o。

進一步瞭解 CLI 工具

如要進一步瞭解如何使用 CLI 工具，請參閱 npm wbn-sign 頁面。或者也可以使用 wnb-sign help.。

Webpack 外掛程式

使用單一金鑰簽署

如要設定 Webpack 外掛程式，使用單一私密金鑰簽署 IWA，請按照下列步驟操作：

  • 設定 WebBundlePlugin，自動直接從這個金鑰衍生所需的基本網址。
  • 使用單一 NodeCryptoSigningStrategy 產生已簽署的 .swbn 檔案。
// 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)
    }
  })
)

使用兩個金鑰簽署

在金鑰變更期間，如需對應用程式進行雙重簽署，請按照下列步驟操作：

  • 根據原始 (old_key) 定義 webBundleId 和 Base URL，確保應用程式的身分對使用者而言維持穩定。
  • 使用一系列簽署策略，同時套用新舊私密金鑰。
// 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()
    }
  })
)

Rollup 或 Vite 外掛程式

使用單一金鑰簽署

如要使用 Rollup 或 Vite 外掛程式，以單一私密金鑰簽署應用程式 (類似於 Webpack 設定)，外掛程式會使用單一簽署策略，並處理從提供的金鑰衍生 Base URL 的作業，以產生簽署的輸出內容。

// 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'
})

使用兩個金鑰簽署

如要使用 Rollup 或 Vite 雙重簽署應用程式，您必須設定外掛程式以接受多個金鑰。這個程式碼片段會使用策略陣列，同時套用新舊私密金鑰。明確保留從原始現有金鑰衍生的基準網址和 webBundleId，確保順利完成轉換。

// 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'
})

結論

成功管理 IWA 的金鑰輪替作業，對於維護應用程式發布作業的安全性與連續性至關重要。無論您的具體情況為何 (例如是否遺失金鑰)，按照上述步驟操作都能確保使用者體驗不受影響。您可以運用提供的 CLI 工具或 Webpack、Rollup 或 Vite 的外掛程式設定，有效管理應用程式的簽章，並順利完成金鑰輪替程序。發生緊急狀況時，請務必透過指定的信任電子郵件地址，及時與 Google 聯絡人溝通。