IWA の鍵のローテーション
鍵のローテーションは、IWA の署名に使用される秘密鍵が漏洩または紛失した場合に、その秘密鍵を置き換えることができるメカニズムです。このプロセスにより、アプリの機能が維持され、バンドル ID とオリジンが安定した状態に保たれるため、アプリの配信とアップデートを継続できます。
鍵のローテーション プロセスでは、管理者やユーザーによる変更は必要ありません。正しく実行すれば、管理者やユーザーが気づくことはありません。最初の許可リスト登録プロセスで確立された信頼できる連絡先 チャネルは、 鍵のローテーションを有効にするために不可欠です。
鍵のローテーションが必要な場合
鍵のローテーションは、主に次の 2 つのシナリオで厳密に必要となります。
- 鍵の漏洩または不正使用: 秘密署名鍵が不正使用された場合や、漏洩した可能性がある場合は、アプリを保護するために鍵のローテーション プロセスを直ちに開始する必要があります。鍵が漏洩すると、なりすましに使用されたり、アプリのユーザーに危害を加えたり、企業の評判を損なう可能性があります。
- 鍵の紛失: 秘密署名鍵にアクセスできなくなり、新しいアップデートに署名できなくなった場合は、アプリを配信できるようにするために鍵のローテーションが必要になります。
デベロッパーの要件
鍵のローテーションを開始する前に、次の条件を満たす必要があります。
- 許可リストに登録されたアプリ: 鍵のローテーションの対象となるのは、許可リストに登録されたアプリのみです。
- 信頼できるメールアドレス: 鍵のローテーションをリクエストするには、許可リスト登録プロセスで提供された信頼できるメールアドレスを使用する必要があります。
ホストされているアプリの再署名と新しいバージョンのリリース
鍵をローテーションすると、有効な鍵で署名されていないインストール済みのアプリ インスタンスはすべてブロックされます。ユーザーへの影響を避けるため、新しい鍵（または両方の鍵）で署名されたアプリを配信する必要があります。バンドルの再署名の技術的な詳細については、 セクション 複数の鍵でバンドルに署名する方法をご覧ください。 状況に応じて、次のようなシナリオが考えられます。
シナリオ A: 鍵が紛失していない場合（プロアクティブなローテーションや漏洩など）
アプリに両方の鍵（古い鍵と新しい鍵）で署名し、次のいずれかの方法でユーザーに配信する必要があります。
- 新しいアプリ バージョンをリリースする（アップデート マニフェストに新しいバージョンを追加する）。
- 両方の鍵で署名されるように、ホストされている
.swbnファイル（アップデート マニフェストにリンクされている）を更新する。CLI ツールを使用すると、既存のswbnバンドルに別の署名を追加できます。
ユーザーが変更に気づかないようにするには、Google が鍵のローテーションを処理する前にこれを行う必要があります。
シナリオ B: 鍵が紛失した場合
紛失した鍵でアプリに署名できないため、このケースはより複雑になります。 鍵のローテーションをリクエストし、Google の担当者に次の手順についてお問い合わせください。次 の手順に沿って、ホストされているバンドルに新しい署名を追加するよう求められる場合 があります。
鍵のローテーション プロセス
鍵のローテーション プロセスには、次の手順が含まれます。
| ステップ | アクション | 詳細 | 実行責任者 |
|---|---|---|---|
| 1 | 鍵のローテーションをリクエストする | デベロッパーまたはパートナーは、許可リスト登録プロセスで提供された信頼できるメールアドレス を使用して Google の担当者（パートナー エンジニアまたはその他の担当者）に連絡し、理由を説明して鍵のローテーションの手順を問い合わせます。鍵が不正使用された場合は、プロセスを迅速化するために、古い鍵と新しい鍵で署名されたバンドルを含むアップデート マニフェストを添付することをおすすめします。 | デベロッパー / パートナー |
| 2 | リクエスト元への返信 | Google の担当者が、リクエスト元に詳細な手順と質問を提供します。このステップでは、何度かやり取りが必要になる場合があります。 | Google 連絡先 |
| 3 | データを提供する | デベロッパーまたはパートナーは、手順に沿って操作します。これには、次のような操作が含まれる場合があります。
|
デベロッパー / パートナー |
| 4 | リクエストの処理と フィードバックの提供 |
Google は鍵のローテーション リクエストを確認し、1 営業日以内に承認または拒否の返信を行うか、デベロッパーに問い合わせます。承認されると、Google が鍵をローテーションし、フィードバックを提供します。 | Google 連絡先 |
アップデート チャンネルとバージョン固定
管理者は、カスタム アップデート チャンネルやバージョン固定を使用して、クライアント デバイス上のアプリ バージョンを管理することがあります。鍵のローテーション後、無効な鍵でインストールされたアプリはすべて無効になり、ブロックされます。これを防ぐため、update_manifest.json に記載されているリンクでホストされているアプリの以前のバージョンも更新し、鍵のローテーションの前に 2 つの署名で署名する必要があります。古い鍵が紛失し、アプリに 2 つの鍵で署名できない場合は、Google の担当者に直ちに通知してください。ユーザーのワークフローを妨げることなくアプリを更新できるように、状況を緩和するための対応を行います。
複数の鍵でバンドルに署名する方法
このセクションでは、CLI ツールまたは Webpack/Rollup/Vite プラグイン構成を使用して、1 つまたは 2 つの鍵でウェブバンドルに署名する方法について説明します。CLI ツールを使用すると、既存の swbn バンドルに署名を追加することもできます。これは、鍵が紛失した場合や、以前にホストされたバンドルを更新する場合に便利です。
CLI ツール
まず、npm で wbn-sign パッケージがインストールされていることを確認します。
$ npm i wbn-sign
現在のフォルダでのみインストールするのではなく、パッケージをグローバルにインストールするには、-g を追加します。
1 つの鍵で署名する
$ wbn-sign -i unsigned.wbn -o signed.swbn -k private.pem
2 つの鍵で署名する
$ wbn-sign sign webbundle.wbn old_key.pem new_key.pem -o signed.swbn --web-bundle-id <your-id-from-old-private>
--web-bundle-id <id> 引数は省略できます。old_key がアプリの最初のバージョンの署名に使用された最初の鍵である場合、バンドル ID は鍵から派生します。バンドル ID は、wbn-sign info signed.swbn コマンドで確認できます。
既存のバンドルに署名を追加する
$ wbn-sign add-signature signed.swbn key3.pem --in-place
バンドルをオーバーライドせずに、新しい二重署名を作成する場合は、-o を使用します。
CLI ツールについて
CLI ツールの使用の詳細については、npm wbn-sign
ページをご覧ください。または、wnb-sign
help. を使用します。
Webpack プラグイン
1 つの鍵で署名する
単一の秘密鍵を使用して IWA に署名するように Webpack プラグインを構成するには:
WebBundlePluginを設定して、必要なベース URL をこの鍵から直接自動的に派生させます。- 単一の
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)
}
})
)
2 つの鍵で署名する
鍵のローテーション中にアプリに二重署名する必要がある場合:
- 元の鍵（
old_key）に基づいてwebBundleIdとベース URL を定義し、アプリの ID がユーザーに対して安定した状態を維持できるようにします。 - 署名戦略の配列を使用して、古い秘密鍵と新しい秘密鍵の両方を適用します。
// 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 プラグイン
1 つの鍵で署名する
Webpack の設定と同様に、Rollup または Vite プラグインを使用して単一の秘密鍵でアプリに署名するには、プラグインで単一の署名戦略を使用し、提供された鍵からベース 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'
})
2 つの鍵で署名する
Rollup または Vite を使用してアプリに二重署名するには、複数の鍵を受け入れるようにプラグインを構成する必要があります。このスニペットでは、strategies 配列を使用して、古い秘密鍵と新しい秘密鍵の両方を適用します。元の既存の鍵から派生したベース URL と 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 の担当者に速やかに連絡してください。