Rotation des clés

Robert Ferens

Demián Renzulli

Ce document fournit des informations essentielles sur le processus de rotation des clés pour une application Web isolée (IWA), y compris quand il est nécessaire et les étapes que les développeurs doivent suivre si une clé est perdue ou compromise.

Rotation des clés pour les IWA

La rotation des clés est un mécanisme qui permet de remplacer les clés privées utilisées pour signer votre PWA en cas de fuite ou de perte. Ce processus permet de conserver la fonctionnalité de l'application et de maintenir un ID de bundle et une origine stables, ce qui assure la continuité de la distribution et des mises à jour de votre application.

Le processus de rotation des clés ne nécessite aucune modification de la part des administrateurs ou des utilisateurs. S'il est effectué correctement, il ne sera pas perceptible pour eux. Les canaux de contact de confiance établis lors du processus d'ajout à la liste d'autorisation initial sont essentiels pour activer la rotation des clés.

Nécessité de la rotation des clés

La rotation des clés est strictement nécessaire dans deux scénarios principaux :

• Fuite ou piratage de clé : si votre clé de signature privée est piratée ou potentiellement divulguée, vous devez immédiatement lancer le processus de rotation des clés pour sécuriser votre application. Une clé divulguée peut être utilisée pour usurper votre identité, nuire aux utilisateurs de votre application et mettre en danger la réputation de votre entreprise.
• Perte de clé : si vous perdez l'accès à votre clé de signature privée et que vous ne pouvez pas signer de nouvelles mises à jour, vous devez effectuer une rotation des clés pour pouvoir à nouveau distribuer votre application.

Exigences pour les développeurs

Avant de lancer une rotation de clés, vous devez remplir les critères suivants :

• Application ajoutée à la liste d'autorisation : seule une application ajoutée à la liste d'autorisation peut faire l'objet d'une rotation des clés.
• Adresse e-mail de confiance : vous devez utiliser l'adresse e-mail de confiance fournie lors du processus d'ajout à la liste d'autorisation pour demander une rotation de clé.

Resigner des applications hébergées et publier de nouvelles versions

Après la rotation d'une clé, toutes les instances d'application installées qui ne sont pas signées avec une clé valide sont bloquées. Pour éviter toute interruption pour vos utilisateurs, vous devez fournir une application signée avec la nouvelle clé (ou les deux clés). Vous trouverez les détails techniques sur la resignation des bundles dans la section Signer un bundle avec plusieurs clés. Selon votre situation spécifique, différents scénarios sont possibles :

Scénario A : La clé n'est pas perdue (par exemple, rotation proactive ou fuite)

Vous devez signer l'application avec les deux clés (l'ancienne et la nouvelle) et la distribuer aux utilisateurs de l'une des manières suivantes :

• Publier une nouvelle version de l'application (en l'ajoutant à vos fichiers manifestes de mise à jour)
• Mettez à jour vos fichiers .swbn hébergés (associés à vos fichiers manifestes de mise à jour) pour qu'ils soient signés avec les deux clés. L'outil CLI vous permet d'ajouter une autre signature au bundle swbn existant.

Cette opération doit être effectuée avant que Google ne traite la rotation des clés pour s'assurer que vos utilisateurs ne remarquent pas le changement.

Scénario B : La clé est perdue

Comme l'application ne peut pas être signée avec la clé perdue, ce cas est plus complexe. Demandez la rotation des clés et contactez votre représentant Google pour connaître la marche à suivre. Il est possible que vous soyez invité à ajouter les nouvelles signatures à vos bundles hébergés en suivant ces instructions.

Processus de rotation des clés

Le processus de rotation des clés comprend les étapes suivantes :

Mettre à jour le canal et le blocage de version

Les administrateurs utilisent parfois des canaux de mise à jour personnalisés ou l'épinglage de version, ce qui leur permet de gérer les versions des applications sur leurs appareils clients. Après une rotation des clés, toutes les applications installées avec des clés non valides le deviennent également et sont bloquées. Pour éviter cela, les versions antérieures des applications hébergées sous les liens fournis dans update_manifest.json doivent également être mises à jour et signées avec deux signatures avant la rotation des clés. Si vous avez perdu votre ancienne clé et que l'application ne peut pas être signée avec deux clés, contactez immédiatement votre contact Google. Nous collaborerons avec vous pour résoudre le problème afin que l'application puisse être mise à jour sans perturber les workflows de vos utilisateurs.

Signer un bundle avec plusieurs clés

Cette section explique comment signer vos bundles Web avec une ou deux clés à l'aide d'outils CLI ou de la configuration des plug-ins Webpack/Rollup/Vite. Les outils CLI permettent également d'ajouter une signature à des bundles swbn existants, ce qui peut être utile en cas de perte de clé ou pour mettre à jour les bundles hébergés précédents.

Outils CLI

Tout d'abord, assurez-vous que le package wbn-sign est installé avec npm :

$ npm i wbn-sign

Ajoutez -g pour installer le package de manière globale au lieu de le faire uniquement dans le dossier actuel.

Signature avec une seule clé

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

Signer avec deux clés

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

L'argument --web-bundle-id <id> peut être ignoré si old_key est la première clé avec laquelle la version initiale de l'application a été signée. L'ID du bundle sera alors dérivé de la clé. Vous pouvez vérifier l'ID du bundle avec la commande wbn-sign info signed.swbn.

Ajouter une signature au bundle existant

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

Utilisez -o si vous ne souhaitez pas remplacer le bundle, mais créer un nouveau bundle à double signature.

En savoir plus sur l'outil CLI

Pour en savoir plus sur l'utilisation de l'outil CLI, consultez la page npm wbn-sign. Vous pouvez également utiliser : wnb-sign help.

Plug-in Webpack

Signature avec une seule clé

Pour configurer le plug-in Webpack afin de signer votre IWA à l'aide d'une seule clé privée :

• Configurez WebBundlePlugin pour dériver automatiquement l'URL de base requise directement à partir de cette clé.
• Utilisez un seul NodeCryptoSigningStrategy pour générer votre fichier .swbn signé.

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

Signer avec deux clés

Lorsque vous devez doublement signer votre application lors d'une rotation de clé :

• Définissez le webBundleId et l'URL de base en fonction de votre old_key d'origine pour vous assurer que l'identité de l'application reste stable pour vos utilisateurs.
• Utilisez un éventail de stratégies de signature pour appliquer vos anciennes et nouvelles clés privées.

// 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 ou Vite

Signature avec une seule clé

Pour utiliser le plug-in Rollup ou Vite afin de signer votre application avec une seule clé privée, comme pour la configuration Webpack, le plug-in utilise une seule stratégie de signature et gère la dérivation de l'URL de base à partir de la clé fournie pour générer votre sortie signée.

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

Signer avec deux clés

Pour double-signer votre application à l'aide de Rollup ou Vite, vous devez configurer le plug-in pour qu'il accepte plusieurs clés. Cet extrait applique à la fois l'ancienne et la nouvelle clé privée à l'aide du tableau de stratégies. Elle assure une transition fluide en conservant explicitement l'URL de base et webBundleId dérivé de votre clé existante d'origine.

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

Conclusion

Il est essentiel de gérer correctement la rotation des clés pour votre IWA afin de préserver la sécurité et la continuité de la distribution de votre application. Quelle que soit votre situation spécifique (par exemple, si la clé est perdue ou non), suivre les étapes décrites vous permettra de minimiser les perturbations pour vos utilisateurs. En utilisant les outils CLI ou les configurations de plug-in fournis pour Webpack, Rollup ou Vite, vous pouvez gérer efficacement les signatures de votre application et effectuer la rotation des clés en toute simplicité. En cas d'urgence, n'oubliez pas de communiquer rapidement avec votre contact Google via votre adresse e-mail de confiance désignée.