Rotacja kluczy

Robert Ferens

Demián Renzulli

Ten dokument zawiera najważniejsze informacje o procesie rotacji kluczy w izolowanej aplikacji internetowej, w tym o tym, kiedy jest on konieczny, oraz o krokach, które deweloperzy muszą wykonać w przypadku utraty lub naruszenia bezpieczeństwa klucza.

Rotacja kluczy w przypadku tożsamości roboczych

Rotacja kluczy to mechanizm, który umożliwia zastąpienie kluczy prywatnych używanych do podpisywania IWA w przypadku ich wycieku lub utraty. Dzięki temu aplikacja zachowuje funkcjonalność, a identyfikator pakietu i źródło pozostają stabilne, co zapewnia ciągłość dystrybucji i aktualizacji aplikacji.

Proces rotacji kluczy nie wymaga żadnych zmian ze strony administratora ani użytkownika, a jeśli zostanie przeprowadzony prawidłowo, nie będzie dla nich zauważalny. Kanały zaufanych kontaktów utworzone podczas początkowego procesu dodawania do listy dozwolonych są niezbędne do włączenia rotacji kluczy.

Konieczność zmiany klucza

Zmiana klucza jest bezwzględnie konieczna w 2 głównych przypadkach:

• Wyciek lub naruszenie bezpieczeństwa klucza: jeśli Twój prywatny klucz podpisywania został naruszony lub potencjalnie wyciekł, musisz natychmiast rozpocząć proces zmiany klucza, aby zabezpieczyć aplikację. Wyciek klucza może zostać wykorzystany do podszywania się pod Ciebie, wyrządzenia szkody użytkownikom aplikacji i zagrożenia reputacji Twojej firmy.
• Utrata klucza: jeśli utracisz dostęp do prywatnego klucza podpisywania i nie możesz podpisywać nowych aktualizacji, konieczna jest rotacja klucza, aby przywrócić możliwość rozpowszechniania aplikacji.

Wymagania dotyczące deweloperów

Zanim rozpoczniesz rotację klucza, musisz spełnić te kryteria:

• Aplikacja z białej listy: zmiana klucza może dotyczyć tylko aplikacji z białej listy.
• Zaufany adres e-mail: aby poprosić o rotację klucza, musisz użyć zaufanego adresu e-mail podanego podczas procesu dodawania do listy dozwolonych.

Ponowne podpisywanie aplikacji hostowanych i publikowanie nowych wersji

Po zmianie klucza wszystkie zainstalowane instancje aplikacji, które nie są podpisane prawidłowym kluczem, zostaną zablokowane. Aby zapobiec przerwom w działaniu aplikacji u użytkowników, musisz dostarczyć aplikację podpisaną nowym kluczem (lub obydwoma kluczami). Szczegóły techniczne dotyczące ponownego podpisywania pakietów znajdziesz w sekcji Podpisywanie pakietu za pomocą wielu kluczy. W zależności od konkretnej sytuacji możliwe są różne scenariusze:

Scenariusz A: klucz nie został utracony (np. w wyniku proaktywnej rotacji lub wycieku)

Musisz podpisać aplikację obydwoma kluczami (starym i nowym) i udostępnić ją użytkownikom w jeden z tych sposobów:

• opublikowanie nowej wersji aplikacji (dodanie jej do manifestów aktualizacji);
• Aktualizowanie hostowanych plików .swbn (połączonych w plikach manifestu aktualizacji), aby były podpisane obydwoma kluczami. Narzędzie CLI umożliwia dodanie kolejnego podpisu do istniejącego pakietu swbn.

Musisz to zrobić, zanim Google przetworzy rotację klucza, aby użytkownicy nie zauważyli zmiany.

Przykład B: klucz został zgubiony

Ponieważ nie można podpisać aplikacji utraconym kluczem, sprawa jest bardziej skomplikowana. Poproś o rotację klucza i skontaktuj się z przedstawicielem Google, aby poznać dalsze kroki. Możemy poprosić Cię o dodanie nowych podpisów do hostowanych pakietów zgodnie z tymi instrukcjami.

Proces rotacji kluczy

Proces rotacji kluczy obejmuje te kroki:

Aktualizowanie kanału i przypinanie wersji

Administratorzy czasami używają niestandardowych kanałów aktualizacji lub przypinania wersji, co pozwala im zarządzać wersjami aplikacji na urządzeniach klienckich. Po rotacji klucza wszystkie aplikacje zainstalowane przy użyciu nieprawidłowych kluczy stają się nieprawidłowe i są blokowane. Aby temu zapobiec, starsze wersje aplikacji hostowanych pod linkami podanymi w update_manifest.json muszą zostać zaktualizowane i podpisane dwoma podpisami przed rotacją klucza. Jeśli stary klucz zostanie utracony i aplikacji nie można podpisać 2 kluczami, natychmiast powiadom o tym osobę kontaktową w Google. Pomożemy Ci rozwiązać ten problem, aby można było zaktualizować aplikację bez zakłócania pracy użytkowników.

Jak podpisać pakiet za pomocą wielu kluczy

Z tej sekcji dowiesz się, jak podpisywać pakiety internetowe za pomocą 1 lub 2 kluczy za pomocą narzędzi interfejsu wiersza poleceń lub konfiguracji wtyczek Webpack/Rollup/Vite. Narzędzia CLI umożliwiają też dodanie kolejnego podpisu do istniejących swbn pakietów, co może być przydatne w przypadku utraty klucza lub aktualizacji poprzednich pakietów hostowanych.

Narzędzia CLI

Najpierw sprawdź, czy masz zainstalowany pakiet wbn-sign za pomocą polecenia npm:

$ npm i wbn-sign

Dodaj -g, aby zainstalować pakiet globalnie, a nie tylko w bieżącym folderze.

Podpisywanie za pomocą jednego klucza

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

Podpisywanie za pomocą 2 kluczy

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

Argumentu --web-bundle-id <id> można pominąć, jeśli old_key jest pierwszym kluczem, którym podpisano początkową wersję aplikacji. Wtedy identyfikator pakietu zostanie wygenerowany na podstawie klucza. Identyfikator pakietu możesz sprawdzić za pomocą polecenia wbn-sign info signed.swbn.

Dodawanie podpisu do istniejącego pakietu

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

Użyj kodu -o, jeśli nie chcesz zastępować pakietu, ale chcesz utworzyć nowy pakiet z podwójnym podpisem.

Więcej informacji o narzędziu CLI

Więcej informacji o korzystaniu z narzędzia CLI znajdziesz na stronie npm wbn-sign. Możesz też użyć: wnb-sign help.

Wtyczka Webpack

Podpisywanie za pomocą jednego klucza

Aby skonfigurować wtyczkę Webpack do podpisywania aplikacji IWA za pomocą jednego klucza prywatnego:

• Skonfiguruj parametr WebBundlePlugin, aby automatycznie uzyskiwać wymagany podstawowy adres URL bezpośrednio z tego klucza.
• Użyj pojedynczego znaku NodeCryptoSigningStrategy, aby utworzyć podpisany plik .swbn.

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

Podpisywanie za pomocą 2 kluczy

Gdy podczas zmiany klucza musisz dwukrotnie podpisać aplikację:

• Określ webBundleId i adres URL na podstawie pierwotnego adresu URL (old_key), aby tożsamość aplikacji pozostała stabilna dla użytkowników.
• Użyj szeregu strategii podpisywania, aby zastosować zarówno stary, jak i nowy klucz prywatny.

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

wtyczka Rollup lub Vite,

Podpisywanie za pomocą jednego klucza

Aby użyć wtyczki Rollup lub Vite do podpisania aplikacji za pomocą jednego klucza prywatnego, podobnie jak w przypadku konfiguracji Webpack, wtyczka używa jednej strategii podpisywania i wyznacza adres URL na podstawie podanego klucza, aby wygenerować podpisane dane wyjściowe.

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

Podpisywanie za pomocą 2 kluczy

Aby podwójnie podpisać aplikację za pomocą Rollup lub Vite, musisz skonfigurować wtyczkę tak, aby akceptowała wiele kluczy. Ten fragment kodu stosuje zarówno stary, jak i nowy klucz prywatny za pomocą tablicy strategii. Zapewnia to bezproblemowe przejście dzięki wyraźnemu zachowaniu adresu URL i webBundleId pochodzącego z oryginalnego, istniejącego klucza.

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

Podsumowanie

Skuteczne zarządzanie zmianą klucza w przypadku IWA ma kluczowe znaczenie dla zachowania bezpieczeństwa i ciągłości dystrybucji aplikacji. Niezależnie od konkretnej sytuacji (np. czy klucz został utracony), wykonanie opisanych poniżej czynności zapewni użytkownikom minimalne zakłócenia. Korzystając z narzędzi CLI lub konfiguracji wtyczek do Webpacka, Rollupa lub Vite, możesz skutecznie zarządzać podpisami aplikacji i płynnie przechodzić przez proces rotacji kluczy. W sytuacjach awaryjnych pamiętaj, aby niezwłocznie skontaktować się z osobą kontaktową w Google za pomocą wyznaczonego zaufanego adresu e-mail.