Este documento fornece informações essenciais sobre o processo de rotação de chaves para um app da Web isolado (IWA, na sigla em inglês), incluindo quando ele é necessário e as etapas que os desenvolvedores precisam seguir se uma chave for perdida ou comprometida.
Rotação de chaves para IWAs
A rotação de chaves é um mecanismo que permite que as chaves privadas usadas para assinar seu IWA sejam substituídas em caso de vazamento ou perda. Esse processo mantém o app funcional e mantém um ID e uma origem de pacote estáveis, garantindo a continuidade da distribuição e das atualizações do app.
O processo de rotação de chaves não exige mudanças de administrador ou usuário e, se realizado corretamente, não será perceptível para eles. Os canais de contato confiáveis estabelecidos durante o processo inicial de lista de permissões são essenciais para ativar a rotação de chaves.
A necessidade de rotação de chaves
A rotação de chaves é estritamente necessária em dois cenários principais:
- Vazamento ou comprometimento de chaves:se a chave de assinatura privada for comprometida ou potencialmente vazada, inicie imediatamente o processo de rotação de chaves para proteger seu aplicativo. Uma chave vazada pode ser usada para se passar por você, causar danos aos usuários do app e colocar em risco a reputação da sua empresa.
- Perda de chaves:se você perder o acesso à chave de assinatura privada e não puder assinar novas atualizações, a rotação de chaves será necessária para restabelecer sua capacidade de distribuir o aplicativo.
Requisitos do desenvolvedor
Antes de iniciar uma rotação de chaves, você precisa atender aos seguintes critérios:
- App na lista de permissões:somente apps na lista de permissões podem estar sujeitos a uma rotação de chaves.
- E-mail confiável:use o endereço de e-mail confiável fornecido durante o processo de lista de permissões para solicitar uma rotação de chaves.
Como assinar novamente apps hospedados e lançar novas versões
Depois de girar uma chave, todas as instâncias de app instaladas que não estão assinadas com uma chave válida são bloqueadas. Para evitar interrupções para os usuários, você precisa entregar um app assinado com a nova chave (ou ambas as chaves). Os detalhes técnicos de assinatura de pacotes podem ser encontrados na seção Como assinar um pacote com várias chaves. Dependendo da sua situação específica, há diferentes cenários:
Cenário A: a chave não está perdida (por exemplo, rotação proativa ou vazamento)
Você precisa assinar o app com as duas chaves (a antiga e a nova) e entregá-las aos usuários de uma das seguintes maneiras:
- Lançando uma nova versão do app (adicionando a nova versão aos seus manifestos de atualização) ou
- Atualizando os arquivos
.swbnhospedados (vinculados nos manifestos de atualização) para serem assinados com as duas chaves. A ferramenta da CLI permite adicionar outra assinatura ao pacoteswbnatual.
Isso precisa ser feito antes que a rotação de chaves seja processada pelo Google para garantir que os usuários não percebam a mudança.
Cenário B: a chave está perdida
Como o app não pode ser assinado com a chave perdida, esse caso é mais complexo. Solicite a rotação de chaves e peça mais etapas ao seu contato do Google. Talvez seja necessário adicionar as novas assinaturas aos pacotes hospedados seguindo estas instruções.
Processo de rotação de chaves
O processo de rotação de chaves envolve as seguintes etapas:
| Etapa | Ação | Detalhes | Responsável |
|---|---|---|---|
| 1 | Solicitar alteração da chave | O desenvolvedor/parceiro entra em contato com o contato do Google (engenharia de parceiros ou outro ponto de contato) pelo e-mail confiável fornecido no processo de lista de permissões e pede as instruções de rotação de chaves explicando o motivo. No caso de chaves comprometidas, recomendamos anexar o manifesto de atualização com pacotes assinados com chaves antigas e novas para acelerar o processo. | Desenvolvedor / Parceiro |
| 2 | Resposta ao solicitante | O contato do Google fornece mais instruções e perguntas ao solicitante. Essa etapa pode envolver algumas trocas de mensagens. | Contato do Google |
| 3 | Fornecer dados | O desenvolvedor/parceiro segue as instruções, que, entre outras, podem envolver:
|
Desenvolvedor / Parceiro |
| 4 | Processamento de solicitações e fornecimento de feedback |
O Google analisa a solicitação de rotação de chaves e responde em até uma semana útil, aprovando ou negando ou entrando em contato com o desenvolvedor para mais perguntas. Após a aprovação, o Google gira a chave e fornece feedback. | Contato do Google |
Atualizar canal e fixação de versão
Os administradores às vezes usam canais de atualização personalizados ou fixação de versão, o que permite gerenciar versões de apps em dispositivos clientes. Após uma rotação de chaves, todos os apps instalados com chaves inválidas se tornam inválidos e são bloqueados. Para evitar isso, as versões anteriores de apps hospedados em links fornecidos no update_manifest.json também precisam ser atualizadas e assinadas com duas assinaturas antes da rotação de chaves. Se a chave antiga for perdida e o app não puder ser assinado com duas chaves, notifique seu contato do Google imediatamente. Vamos trabalhar com você para atenuar a situação para que o app possa ser atualizado sem perturbar os fluxos de trabalho dos usuários.
Como assinar um pacote com várias chaves
Esta seção descreve como assinar pacotes da Web com uma ou duas chaves usando ferramentas da CLI ou configuração de plug-ins do Webpack/Rollup/Vite. As ferramentas da CLI também permitem adicionar mais uma assinatura aos pacotes swbn atuais, o que pode ser útil em casos de chaves perdidas ou para atualizar os pacotes hospedados anteriores.
Ferramentas da CLI
Primeiro, verifique se você tem o pacote wbn-sign instalado com npm:
$ npm i wbn-sign
Adicione -g para instalar o pacote globalmente em vez de fazer isso apenas na pasta atual.
Assinatura com uma chave
$ wbn-sign -i unsigned.wbn -o signed.swbn -k private.pem
Assinatura com duas chaves
$ wbn-sign sign webbundle.wbn old_key.pem new_key.pem -o signed.swbn --web-bundle-id <your-id-from-old-private>
O argumento --web-bundle-id <id> pode ser ignorado. Se old_key for a primeira chave
a versão inicial do app foi assinada com, o ID do pacote será
derivado da chave. Você pode verificar o ID do pacote com o comando wbn-sign info signed.swbn.
Como adicionar uma assinatura ao pacote atual
$ wbn-sign add-signature signed.swbn key3.pem --in-place
Use -o se não quiser substituir o pacote, mas criar um novo com assinatura dupla.
Mais informações sobre a ferramenta da CLI
Para mais informações sobre como usar a ferramenta da CLI, consulte a página
npm wbn-sign. Como alternativa, use: wnb-sign
help.
Plug-in do Webpack
Assinatura com uma chave
Para configurar o plug-in do Webpack para assinar seu IWA usando uma única chave privada:
- Configure o
WebBundlePluginpara derivar automaticamente o URL base necessário diretamente dessa chave. - Use um único
NodeCryptoSigningStrategypara produzir o arquivo.swbnassinado.
// 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)
}
})
)
Assinatura com duas chaves
Quando você precisar assinar seu aplicativo duas vezes durante uma rotação de chaves:
- Defina o
webBundleIde o URL base com base no original (old_key) para garantir que a identidade do app permaneça estável para os usuários. - Use uma matriz de estratégias de assinatura para aplicar as chaves privadas antigas e novas.
// 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()
}
})
)
Plug-in do Rollup ou Vite
Assinatura com uma chave
Para usar o plug-in do Rollup ou Vite para assinar seu aplicativo com uma única chave privada, semelhante à configuração do Webpack, o plug-in usa uma única estratégia de assinatura e processa a derivação do URL base da chave fornecida para gerar a saída assinada.
// 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'
})
Assinatura com duas chaves
Para assinar seu aplicativo duas vezes usando o Rollup ou o Vite, configure o plug-in para aceitar várias chaves. Esse snippet aplica as chaves privadas antigas e novas usando a matriz de estratégias. Ele garante uma transição perfeita, mantendo explicitamente o URL base e o webBundleId derivados da chave original.
// 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'
})
Conclusão
Gerenciar a rotação de chaves do seu IWA é fundamental para manter a segurança e a continuidade da distribuição do aplicativo. Independentemente da sua situação específica (por exemplo, se a chave foi perdida ou não), seguir as etapas descritas garante que os usuários tenham o mínimo de interrupção. Ao usar as ferramentas da CLI ou as configurações de plug-ins fornecidas para Webpack, Rollup ou Vite, você pode gerenciar com eficiência as assinaturas do app e navegar pelo processo de rotação de chaves sem problemas. Em cenários de emergência, lembre-se de se comunicar imediatamente com seu contato do Google pelo e-mail confiável designado.