Schlüsselrotation

Robert Ferens

Demián Renzulli

Dieses Dokument enthält wichtige Informationen zum Prozess der Schlüsselrotation für eine Isolated Web App (IWA), einschließlich der Frage, wann sie erforderlich ist, und der Schritte, die Entwickler ausführen müssen, wenn ein Schlüssel verloren geht oder manipuliert wird.

Schlüsselrotation für integrierte Web-Apps

Die Schlüsselrotation ist ein Mechanismus, mit dem die privaten Schlüssel, die zum Signieren Ihrer IWA verwendet werden, im Falle eines Lecks oder Verlusts ersetzt werden können. So bleibt die App funktionsfähig und die Bundle-ID und der Ursprung bleiben stabil. Dadurch wird die Kontinuität der Bereitstellung und der Updates Ihrer App gewährleistet.

Für die Schlüsselrotation sind keine Änderungen durch Administratoren oder Nutzer erforderlich. Wenn sie korrekt durchgeführt wird, ist sie für sie nicht wahrnehmbar. Die während des ersten Zulassungsprozesses eingerichteten Kanäle für vertrauenswürdige Kontakte sind für die Aktivierung der Schlüsselrotation unerlässlich.

Notwendigkeit der Schlüsselrotation

Eine Schlüsselrotation ist in zwei Hauptszenarien unbedingt erforderlich:

• Schlüsselverlust oder ‑manipulation:Wenn Ihr privater Signaturschlüssel manipuliert wurde oder möglicherweise verloren gegangen ist, müssen Sie sofort den Schlüsselwechselprozess starten, um Ihre App zu schützen. Ein gehackter Schlüssel kann verwendet werden, um sich als Sie auszugeben, Ihren App-Nutzern zu schaden und den Ruf Ihres Unternehmens zu gefährden.
• Schlüsselverlust:Wenn Sie den Zugriff auf Ihren privaten Signaturschlüssel verlieren und keine neuen Updates signieren können, ist eine Schlüsselrotation erforderlich, damit Sie Ihre Anwendung wieder verteilen können.

Anforderungen an Entwickler

Bevor Sie eine Schlüsselrotation starten, müssen die folgenden Kriterien erfüllt sein:

• App auf der Zulassungsliste:Nur Apps auf der Zulassungsliste können einer Schlüsselrotation unterzogen werden.
• Vertrauenswürdige E‑Mail-Adresse:Sie müssen die während des Allowlisting-Prozesses angegebene vertrauenswürdige E‑Mail-Adresse verwenden, um eine Schlüsselrotation anzufordern.

Gehostete Apps neu signieren und neue Versionen veröffentlichen

Nach dem Rotieren eines Schlüssels werden alle installierten App-Instanzen blockiert, die nicht mit einem gültigen Schlüssel signiert sind. Um Störungen für Ihre Nutzer zu vermeiden, müssen Sie eine App bereitstellen, die mit dem neuen Schlüssel (oder beiden Schlüsseln) signiert ist. Die technischen Details zum erneuten Signieren von App-Bundles finden Sie im Abschnitt App-Bundle mit mehreren Schlüsseln signieren. Je nach Ihrer Situation gibt es verschiedene Szenarien:

Szenario A: Der Schlüssel ist nicht verloren (z. B. proaktive Rotation oder Datenleck)

Sie müssen die App mit beiden Schlüsseln (dem alten und dem neuen) signieren und sie den Nutzern auf eine der folgenden Arten zur Verfügung stellen:

• Sie veröffentlichen eine neue App-Version (indem Sie die neue Version in Ihre Update-Manifeste aufnehmen) oder
• Aktualisieren Sie Ihre gehosteten .swbn-Dateien (die in Ihren Aktualisierungsmanifesten verlinkt sind), sodass sie mit beiden Schlüsseln signiert sind. Mit dem CLI-Tool können Sie dem vorhandenen swbn-Bundle eine weitere Signatur hinzufügen.

Das muss erfolgen, bevor die Schlüsselrotation von Google verarbeitet wird, damit Ihre Nutzer die Änderung nicht bemerken.

Hinweis :Wenn der Administrator die Versionsfixierung verwendet, muss er das gehostete Bundle für diese Version aktualisieren oder die App an die Version anpinnen, die mit beiden Schlüsseln signiert ist.

Szenario B: Der Schlüssel ist verloren gegangen

Da die App nicht mit dem verlorenen Schlüssel signiert werden kann, ist dieser Fall komplexer. Fordern Sie die Schlüsselrotation an und bitten Sie Ihren Google-Ansprechpartner um weitere Informationen. Möglicherweise werden Sie aufgefordert, die neuen Signaturen gemäß dieser Anleitung zu Ihren gehosteten App-Bundles hinzuzufügen.

Hinweis :Wenn Sie die Versionsfixierung verwenden und eine neue App-Version für eine Schlüsselrotation veröffentlichen, sollten Sie die fixierte Version ändern.

Schlüsselrotationsprozess

Der Prozess für die Schlüsselrotation umfasst die folgenden Schritte:

Schritt	Aktion	Details	Verantwortlich
1	Schlüsselwechsel anfordern	Der Entwickler/Partner wendet sich über die vertrauenswürdige E-Mail-Adresse , die im Zulassungsverfahren angegeben ist, an seinen Google-Kontakt (Partner Engineering oder einen anderen Ansprechpartner) und bittet um eine Anleitung zur Schlüsselrotation, in der der Grund erläutert wird. Wenn ein Schlüssel kompromittiert wurde, empfehlen wir, das Update-Manifest mit Bundles anzuhängen, die mit alten und neuen Schlüsseln signiert sind, um den Prozess zu beschleunigen.	Entwickler / Partner
2	Antwort an den Anfragenden	Der Google-Kontakt gibt dem Antragsteller weitere Anweisungen und stellt ihm Fragen. Dieser Schritt kann einige Rückfragen umfassen.	Google-Kontakt
3	Daten bereitstellen	Der Entwickler/Partner befolgt die Anleitung, die unter anderem Folgendes umfassen kann: Pakete mit neuen Schlüsseln neu signieren. Aktualisieren oder Bereitstellen Ihres Update-Manifests mit aktualisierten Apps. Weitere Informationen angeben Dazu gehören beispielsweise Details zur Situation, Gefahren oder technische Details wie der App-Release-Zyklus eines Partners. Bereitschaft für die Rotation bestätigen: Wir empfehlen, dies frühestens drei Tage nach der Aktualisierung der Client-Apps zu tun, um sicherzugehen, dass sie aktualisiert wurden.	Entwickler / Partner
4	Anfragebearbeitung und Feedback	Google prüft den Antrag auf Schlüsselrotation und antwortet innerhalb einer Arbeitswoche. Der Antrag wird entweder genehmigt oder abgelehnt oder der Entwickler wird mit weiteren Fragen kontaktiert. Nach der Genehmigung rotiert Google den Schlüssel und gibt Feedback.	Google-Kontakt

Channel und Versionsfixierung aktualisieren

Administratoren verwenden manchmal benutzerdefinierte Update-Channels oder Version Pinning, um App-Versionen auf ihren Clientgeräten zu verwalten. Nach einer Schlüsselrotation werden alle mit ungültigen Schlüsseln installierten Apps ungültig und blockiert. Um dies zu verhindern, müssen auch frühere Versionen von Apps, die unter den in update_manifest.json angegebenen Links gehostet werden, vor der Schlüsselrotation aktualisiert und mit zwei Signaturen signiert werden. Wenn Ihr alter Schlüssel verloren gegangen ist und die App nicht mit zwei Schlüsseln signiert werden kann, benachrichtigen Sie sofort Ihren Google-Ansprechpartner. Wir arbeiten mit Ihnen zusammen, um die Situation zu entschärfen, damit die App aktualisiert werden kann, ohne die Arbeitsabläufe Ihrer Nutzer zu stören.

Bundle mit mehreren Schlüsseln signieren

In diesem Abschnitt wird beschrieben, wie Sie Ihre Web-Bundles mit einem oder zwei Schlüsseln über CLI-Tools oder die Konfiguration von Webpack-/Rollup-/Vite-Plug-ins signieren können. Mit CLI-Tools kann auch eine weitere Signatur zu vorhandenen swbn-Bundles hinzugefügt werden. Das kann nützlich sein, wenn Schlüssel verloren gegangen sind oder wenn die zuvor gehosteten Bundles aktualisiert werden.

Befehlszeilentools

Prüfen Sie zuerst, ob das wbn-sign-Paket mit npm installiert ist:

$ npm i wbn-sign

Fügen Sie -g hinzu, um das Paket global zu installieren, anstatt nur im aktuellen Ordner.

Signieren mit einem Schlüssel

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

Mit zwei Schlüsseln signieren

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

Das Argument --web-bundle-id <id> kann übersprungen werden, wenn „old_key“ der erste Schlüssel ist, mit dem die ursprüngliche Version der App signiert wurde. In diesem Fall wird die Bundle-ID aus dem Schlüssel abgeleitet. Sie können die Bundle-ID mit dem Befehl wbn-sign info signed.swbn prüfen.

Dem vorhandenen Bundle eine Signatur hinzufügen

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

Verwenden Sie -o, wenn Sie das Bundle nicht überschreiben, sondern ein neues mit doppelter Signatur erstellen möchten.

Weitere Informationen zum CLI-Tool

Weitere Informationen zur Verwendung des CLI-Tools finden Sie auf der npm-Seite zu wbn-sign. Alternativ können Sie auch die wnb-sign help. verwenden.

Webpack-Plug-in

Signieren mit einem Schlüssel

So konfigurieren Sie das Webpack-Plug-in, um Ihre IWA mit einem einzelnen privaten Schlüssel zu signieren:

• Richten Sie WebBundlePlugin so ein, dass die erforderliche Basis-URL automatisch aus diesem Schlüssel abgeleitet wird.
• Verwenden Sie ein einzelnes NodeCryptoSigningStrategy, um Ihre signierte .swbn-Datei zu erstellen.

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

Mit zwei Schlüsseln signieren

Wenn Sie Ihre Anwendung während eines Schlüsselwechsels doppelt signieren müssen:

• Definieren Sie die webBundleId und die Basis-URL basierend auf Ihrer ursprünglichen old_key, damit die Identität der App für Ihre Nutzer stabil bleibt.
• Verwenden Sie eine Reihe von Signierungsstrategien, um sowohl Ihren alten als auch Ihren neuen privaten Schlüssel anzuwenden.

// 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- oder Vite-Plug-in

Signieren mit einem Schlüssel

Wenn Sie das Rollup- oder Vite-Plugin verwenden möchten, um Ihre Anwendung mit einem einzelnen privaten Schlüssel zu signieren (ähnlich wie bei der Webpack-Einrichtung), verwendet das Plugin eine einzelne Signaturstrategie und leitet die Basis-URL aus dem bereitgestellten Schlüssel ab, um die signierte Ausgabe zu generieren.

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

Mit zwei Schlüsseln signieren

Wenn Sie Ihre Anwendung mit Rollup oder Vite doppelt signieren möchten, müssen Sie das Plug-in so konfigurieren, dass es mehrere Schlüssel akzeptiert. In diesem Snippet werden sowohl der alte als auch der neue privaten Schlüssel über das Strategie-Array angewendet. Sie sorgt für einen nahtlosen Übergang, da die Basis-URL und webBundleId aus Ihrem ursprünglichen, vorhandenen Schlüssel explizit beibehalten werden.

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

Fazit

Die erfolgreiche Verwaltung der Schlüsselrotation für Ihre IWA ist entscheidend, um die Sicherheit und Kontinuität der Verteilung Ihrer Anwendung aufrechtzuerhalten. Unabhängig von Ihrer spezifischen Situation (z. B. ob der Schlüssel verloren gegangen ist oder nicht) sorgen die folgenden Schritte dafür, dass Ihre Nutzer nur minimal beeinträchtigt werden. Mit den bereitgestellten CLI-Tools oder Plug-in-Konfigurationen für Webpack, Rollup oder Vite können Sie die Signaturen Ihrer App effizient verwalten und den Schlüsselrotationsprozess reibungslos durchlaufen. Denken Sie daran, in Notfallsituationen umgehend über Ihre angegebene vertrauenswürdige E‑Mail-Adresse mit Ihrem Google-Kontakt zu kommunizieren.