Sleutelrotatie

Robert Ferens

Demián Renzulli

Dit document bevat essentiële informatie over het proces van sleutelrotatie voor een Isolated Web App (IWA) , inclusief wanneer dit nodig is en welke stappen ontwikkelaars moeten volgen als een sleutel verloren gaat of gecompromitteerd raakt.

Belangrijke rotatie voor IWA's

Sleutelrotatie is een mechanisme waarmee de privésleutels die gebruikt worden om uw IWA te ondertekenen, vervangen kunnen worden in geval van een lek of verlies. Dit proces zorgt ervoor dat de app functioneel blijft en een stabiele bundel-ID en oorsprong behoudt, waardoor de continuïteit van de distributie en updates van uw app gewaarborgd is.

Het sleutelrotatieproces vereist geen wijzigingen voor beheerders of gebruikers en zal, indien correct uitgevoerd, voor hen niet merkbaar zijn. De vertrouwde contactkanalen die tijdens het initiële whitelistingproces zijn vastgesteld, zijn essentieel voor het mogelijk maken van sleutelrotatie.

De noodzaak van sleutelrotatie

Sleutelrotatie is in twee belangrijke scenario's absoluut noodzakelijk:

• Sleutellek of -compromittering: Als uw privésleutel voor ondertekening is gecompromitteerd of mogelijk is gelekt, moet u onmiddellijk het sleutelrotatieproces starten om uw applicatie te beveiligen. Een gelekte sleutel kan worden gebruikt om zich voor te doen als u, schade toe te brengen aan uw app-gebruikers en de reputatie van uw bedrijf in gevaar te brengen.
• Sleutelverlies: Als u de toegang tot uw privésleutel voor het ondertekenen van documenten verliest en geen nieuwe updates meer kunt ondertekenen, is sleutelrotatie vereist om uw applicatie opnieuw te kunnen distribueren.

Ontwikkelaarsvereisten

Voordat u een sleutelrotatie start, moet u aan de volgende criteria voldoen:

• Toegestane apps: Alleen apps die op de toegestane lijst staan, kunnen worden onderworpen aan sleutelrotatie.
• Vertrouwd e-mailadres: U moet het vertrouwde e-mailadres dat u tijdens het whitelistingproces hebt opgegeven gebruiken om een ​​sleutelrotatie aan te vragen.

Het opnieuw ondertekenen van gehoste apps en het uitbrengen van nieuwe versies

Na het roteren van een sleutel worden alle geïnstalleerde app-instanties die niet met een geldige sleutel zijn ondertekend, geblokkeerd. Om verstoringen voor uw gebruikers te voorkomen, moet u een app leveren die is ondertekend met de nieuwe sleutel (of beide sleutels). De technische details van het opnieuw ondertekenen van bundels vindt u in de sectie ' Een bundel ondertekenen met meerdere sleutels' . Afhankelijk van uw specifieke situatie zijn er verschillende scenario's:

Scenario A: De sleutel is niet verloren (bijvoorbeeld door proactieve rotatie of een lek).

U moet de app ondertekenen met beide sleutels (de oude en de nieuwe) en deze op een van de volgende manieren aan gebruikers verstrekken:

• Een nieuwe app-versie uitbrengen (de nieuwe versie toevoegen aan uw updatemanifesten), of
• Uw gehoste .swbn bestanden (gekoppeld in uw updatemanifesten) worden bijgewerkt zodat ze met beide sleutels worden ondertekend. Met de CLI-tool kunt u een extra handtekening toevoegen aan de bestaande swbn bundel.

Dit moet gebeuren voordat Google de sleutelrotatie verwerkt, zodat uw gebruikers de verandering niet merken.

Scenario B: De sleutel is kwijtgeraakt

Omdat de app niet kan worden ondertekend met de verloren sleutel, is deze zaak complexer. Vraag om sleutelrotatie en neem contact op met uw Google-contactpersoon voor verdere instructies. Mogelijk wordt u gevraagd de nieuwe handtekeningen toe te voegen aan uw gehoste bundels volgens deze instructies .

Sleutelrotatieproces

Het proces voor sleutelrotatie omvat de volgende stappen:

Kanaal en versie vastzetten bijwerken

Beheerders gebruiken soms aangepaste updatekanalen of versiebeheer, waarmee ze app-versies op hun clientapparaten kunnen beheren. Na een sleutelrotatie worden alle apps die met ongeldige sleutels zijn geïnstalleerd ongeldig en geblokkeerd. Om dit te voorkomen, moeten eerdere versies van apps die worden gehost via links in het update_manifest.json ook worden bijgewerkt en ondertekend met twee handtekeningen vóór de sleutelrotatie. Als u uw oude sleutel kwijt bent en de app niet met twee sleutels kan worden ondertekend, neem dan onmiddellijk contact op met uw Google-contactpersoon. We zullen samen met u naar een oplossing zoeken, zodat de app kan worden bijgewerkt zonder de workflows van uw gebruikers te verstoren.

Hoe onderteken je een bundel met meerdere sleutels?

In dit gedeelte wordt beschreven hoe u uw webbundels kunt ondertekenen met één of twee sleutels via CLI-tools of via de configuratie van Webpack/Rollup/Vite-plugins. Met CLI-tools kunt u ook een extra handtekening toevoegen aan bestaande swbn bundels, wat handig kan zijn in geval van sleutelverlies of bij het bijwerken van eerder gehoste bundels.

CLI-tools

Zorg er eerst voor dat je het wbn-sign pakket hebt geïnstalleerd met npm :

$ npm i wbn-sign

Voeg -g toe om het pakket globaal te installeren in plaats van alleen in de huidige map.

Ondertekenen met één sleutel

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

Ondertekenen met twee sleutels

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

Het argument --web-bundle-id <id> kan worden weggelaten als old_key de eerste sleutel is waarmee de initiële versie van de app is ondertekend. In dat geval wordt de bundel-ID afgeleid van die sleutel. U kunt de bundel-ID controleren met het commando wbn-sign info signed.swbn .

Een handtekening toevoegen aan het bestaande pakket

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

Gebruik -o als je de bundel niet wilt overschrijven, maar een nieuwe dubbelondertekende versie wilt aanmaken.

Meer informatie over de CLI-tool

Voor meer informatie over het gebruik van de CLI-tool kunt u de npm wbn-sign-pagina raadplegen. U kunt ook wnb-sign help.

Webpack-plugin

Ondertekenen met één sleutel

Om de Webpack-plugin te configureren zodat uw IWA met één enkele privésleutel wordt ondertekend:

• Stel de WebBundlePlugin zo in dat de vereiste basis-URL automatisch rechtstreeks uit deze sleutel wordt afgeleid.
• Gebruik één enkele NodeCryptoSigningStrategy om uw ondertekende .swbn bestand te genereren.

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

Ondertekenen met twee sleutels

Wanneer moet u uw aanvraag dubbel ondertekenen tijdens een sleutelwisseling?

• Definieer de webBundleId en Base URL op basis van uw oorspronkelijke ( old_key ) om ervoor te zorgen dat de identiteit van de app stabiel blijft voor uw gebruikers.
• Gebruik verschillende ondertekeningsstrategieën om zowel uw oude als nieuwe privésleutels toe te passen.

// 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- of Vite-plug-in

Ondertekenen met één sleutel

Om de Rollup- of Vite-plugin te gebruiken om je applicatie te ondertekenen met één enkele privésleutel, vergelijkbaar met de Webpack-configuratie, gebruikt de plugin één enkele ondertekeningsstrategie en zorgt ervoor dat de basis-URL wordt afgeleid van de verstrekte sleutel om je ondertekende output te genereren.

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

Ondertekenen met twee sleutels

Om uw applicatie dubbel te ondertekenen met Rollup of Vite, moet u de plugin configureren om meerdere sleutels te accepteren. Dit codefragment gebruikt zowel de oude als de nieuwe privésleutel met behulp van de strategies-array. Het zorgt voor een naadloze overgang door expliciet de Base URL en webBundleId te behouden die zijn afgeleid van uw oorspronkelijke, bestaande sleutel.

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

Conclusie

Het succesvol beheren van de sleutelrotatie voor uw IWA is cruciaal voor het waarborgen van de veiligheid en continuïteit van de distributie van uw applicatie. Ongeacht uw specifieke situatie (bijvoorbeeld of de sleutel verloren is of niet), zorgt het volgen van de beschreven stappen ervoor dat uw gebruikers minimale hinder ondervinden. Door gebruik te maken van de beschikbare CLI-tools of pluginconfiguraties voor Webpack, Rollup of Vite, kunt u de handtekeningen van uw app efficiënt beheren en het sleutelrotatieproces soepel laten verlopen. In noodsituaties dient u direct contact op te nemen met uw Google-contactpersoon via uw aangewezen vertrouwde e-mailadres.