Rotazione chiave

Robert Ferens

Demián Renzulli

Questo documento fornisce informazioni essenziali sulla procedura di rotazione delle chiavi per un'app web isolata (IWA), incluso quando è necessaria e i passaggi che gli sviluppatori devono seguire se una chiave viene smarrita o compromessa.

Rotazione delle chiavi per gli IWA

La rotazione delle chiavi è un meccanismo che consente di sostituire le chiavi private utilizzate per firmare la tua IWA in caso di fuga o smarrimento. Questo processo mantiene l'app funzionale e conserva un ID bundle e un'origine stabili, garantendo la continuità della distribuzione e degli aggiornamenti dell'app.

Il processo di rotazione delle chiavi non richiede modifiche da parte dell'amministratore o dell'utente e, se eseguito correttamente, non sarà percepibile. I canali di contatto attendibili stabiliti durante la procedura di inserimento nella lista consentita iniziale sono essenziali per attivare la rotazione delle chiavi.

La necessità di ruotare le chiavi

La rotazione delle chiavi è strettamente necessaria in due scenari principali:

• Perdita o compromissione della chiave: se la tua chiave di firma privata è compromessa o potenzialmente divulgata, devi avviare immediatamente la procedura di rotazione della chiave per proteggere la tua applicazione. Una chiave compromessa può essere utilizzata per impersonarti, causare danni agli utenti della tua app e mettere a rischio la reputazione della tua azienda.
• Perdita della chiave:se perdi l'accesso alla chiave di firma privata e non riesci a firmare i nuovi aggiornamenti, è necessaria la rotazione della chiave per ripristinare la tua capacità di distribuire l'applicazione.

Requisiti per gli sviluppatori

Prima di avviare una rotazione delle chiavi, devi soddisfare i seguenti criteri:

• App consentita:solo le app consentite possono essere soggette a una rotazione delle chiavi.
• Email attendibile:per richiedere una rotazione delle chiavi, devi utilizzare l'indirizzo email attendibile fornito durante la procedura di inserimento nella lista consentita.

Rifirma delle app ospitate e rilascio di nuove versioni

Dopo la rotazione di una chiave, tutte le istanze dell'app installate che non sono firmate con una chiave valida vengono bloccate. Per evitare interruzioni per i tuoi utenti, devi fornire un'app firmata con la nuova chiave (o con entrambe le chiavi). I dettagli tecnici della firma dei bundle sono disponibili nella sezione Come firmare un bundle con più chiavi. A seconda della tua situazione specifica, esistono diversi scenari:

Scenario A: la chiave non è persa (ad esempio, rotazione proattiva o perdita)

Devi firmare l'app con entrambe le chiavi (quella vecchia e quella nuova) e consegnarle agli utenti in uno dei seguenti modi:

• Rilasciando una nuova versione dell'app (aggiungendo la nuova versione ai manifest di aggiornamento) oppure
• Aggiornamento dei file .swbn ospitati (collegati nei manifest di aggiornamento) in modo che vengano firmati con entrambe le chiavi. Lo strumento CLI ti consente di aggiungere un'altra firma al bundle swbn esistente.

Questa operazione deve essere eseguita prima che la rotazione delle chiavi venga elaborata da Google per garantire che gli utenti non notino la modifica.

Nota :se l'amministratore utilizza un blocco della versione, deve aggiornare il bundle ospitato per questa versione o bloccare l'app alla versione firmata con entrambe le chiavi.

Scenario B: la chiave è stata smarrita

Poiché l'app non può essere firmata con la chiave smarrita, questa richiesta è più complessa. Richiedi la rotazione delle chiavi e chiedi al tuo contatto Google ulteriori passaggi. Potrebbe esserti chiesto di aggiungere le nuove firme ai tuoi bundle ospitati seguendo queste istruzioni.

Nota: se utilizzi il blocco delle versioni e rilasci una nuova versione dell'app per una rotazione delle chiavi, valuta la possibilità di modificare la versione bloccata.

Procedura di rotazione della chiave

La procedura di rotazione delle chiavi prevede i seguenti passaggi:

Passaggio	Azione	Dettagli	Responsabile
1	Richiedi la rotazione della chiave	Lo sviluppatore/partner contatta il proprio contatto Google (Partner Engineering o altro punto di contatto) tramite l'email attendibile fornita nella procedura di inserimento nella lista consentita e chiede le istruzioni per la rotazione delle chiavi spiegando il motivo. Nel caso di compromissione della chiave, consigliamo di allegare il manifest di aggiornamento con i bundle firmati con chiavi vecchie e nuove per velocizzare la procedura.	Sviluppatore / partner
2	Risposta al richiedente	Il contatto Google fornisce ulteriori istruzioni e domande al richiedente. Questo passaggio potrebbe richiedere alcuni scambi di email.	Contatto Google
3	Fornire dati	Lo sviluppatore/partner segue le istruzioni, che tra le altre cose possono prevedere: Rifirma i bundle con nuove chiavi. Aggiornamento o fornitura del manifest di aggiornamento con le app aggiornate. Fornire ulteriori informazioni. Ad esempio, dettagli della situazione, pericoli o dettagli tecnici come il ciclo di rilascio dell'app di un partner. Conferma della disponibilità per la rotazione: ti consigliamo di farlo almeno tre giorni dopo l'aggiornamento delle app client e dopo aver verificato che siano state aggiornate.	Sviluppatore / partner
4	Elaborazione della richiesta e fornitura di feedback	Google esamina la richiesta di rotazione delle chiavi e risponde entro una settimana lavorativa, approvandola, rifiutandola o contattando lo sviluppatore per ulteriori domande. Una volta approvata, Google ruota la chiave e fornisce un feedback.	Contatto Google

Aggiornamento del blocco del canale e della versione

A volte gli amministratori utilizzano canali di aggiornamento personalizzati o il blocco delle versioni, che consente loro di gestire le versioni delle app sui dispositivi client. Dopo la rotazione di una chiave, tutte le app installate con chiavi non valide diventano non valide e vengono bloccate. Per evitare questo problema, anche le versioni precedenti delle app ospitate nei link forniti in update_manifest.json devono essere aggiornate e firmate con due firme prima della rotazione delle chiavi. Se la vecchia chiave viene persa e l'app non può essere firmata con due chiavi, avvisa immediatamente il tuo contatto Google. Collaboreremo con te per risolvere la situazione in modo che l'app possa essere aggiornata senza interrompere i flussi di lavoro degli utenti.

Come firmare un bundle con più chiavi

Questa sezione descrive come firmare i bundle web con una o due chiavi tramite gli strumenti CLI o la configurazione dei plug-in Webpack/Rollup/Vite. Gli strumenti CLI consentono anche di aggiungere un'altra firma ai bundle swbn esistenti, il che potrebbe essere utile in caso di smarrimento della chiave o per aggiornare i bundle ospitati precedenti.

Strumenti CLI

Innanzitutto, assicurati di aver installato il pacchetto wbn-sign con npm:

$ npm i wbn-sign

Aggiungi -g per installare il pacchetto a livello globale anziché solo nella cartella corrente.

Firma con una chiave

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

Firma con due chiavi

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

L'argomento --web-bundle-id <id> può essere ignorato se old_key è la prima chiave con cui è stata firmata la versione iniziale dell'app, quindi l'ID bundle verrà derivato dalla chiave. Puoi verificare l'ID bundle con il comando wbn-sign info signed.swbn.

Aggiunta di una firma al bundle esistente

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

Utilizza -o se non vuoi eseguire l'override del bundle, ma creare un nuovo bundle con doppia firma.

Scopri di più sullo strumento CLI

Per saperne di più sull'utilizzo dello strumento CLI, consulta la pagina npm wbn-sign. In alternativa, utilizza: wnb-sign help.

Plug-in Webpack

Firma con una chiave

Per configurare il plug-in Webpack in modo che firmi la tua IWA utilizzando una singola chiave privata:

• Configura WebBundlePlugin per derivare automaticamente l'URL di base richiesto direttamente da questa chiave.
• Utilizza un singolo NodeCryptoSigningStrategy per produrre il file .swbn firmato.

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

Firma con due chiavi

Quando devi firmare due volte la tua applicazione durante una rotazione della chiave:

• Definisci webBundleId e URL di base in base all'originale (old_key) per assicurarti che l'identità dell'app rimanga stabile per i tuoi utenti.
• Utilizza una serie di strategie di firma per applicare sia le chiavi private vecchie che quelle nuove.

// 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 Rollup o Vite

Firma con una chiave

Per utilizzare il plug-in Rollup o Vite per firmare l'applicazione con una singola chiave privata, in modo simile alla configurazione di Webpack, il plug-in utilizza una singola strategia di firma e gestisce la derivazione dell'URL di base dalla chiave fornita per generare l'output firmato.

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

Firma con due chiavi

Per firmare due volte l'applicazione utilizzando Rollup o Vite, devi configurare il plug-in in modo che accetti più chiavi. Questo snippet applica sia le chiavi private precedenti che quelle nuove utilizzando l'array di strategie. Garantisce una transizione senza interruzioni mantenendo esplicitamente l'URL di base e webBundleId derivato dalla chiave originale esistente.

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

Conclusione

La gestione corretta della rotazione delle chiavi per la tua IWA è fondamentale per mantenere la sicurezza e la continuità della distribuzione della tua applicazione. Indipendentemente dalla tua situazione specifica (ad esempio, se la chiave è stata smarrita o meno), seguire i passaggi descritti garantisce che i tuoi utenti subiscano interruzioni minime. Utilizzando gli strumenti CLI o le configurazioni dei plug-in forniti per Webpack, Rollup o Vite, puoi gestire in modo efficiente le firme della tua app e navigare senza problemi nel processo di rotazione delle chiavi. In situazioni di emergenza, ricorda di comunicare tempestivamente con il tuo contatto Google tramite l'email attendibile designata.