Jak skonfigurować Signed Exchange przy użyciu programu Web Packager

Dowiedz się, jak wyświetlać strony w technologii Signed Exchange (SXG) za pomocą systemu zarządzania pakietami internetowymi.

Katie Hempenius
Katie Hempenius

Signed Exchange (SXG) to mechanizm dostarczania, który umożliwia uwierzytelnianie pochodzenia zasobu niezależnie od sposobu jego dostarczenia. Z tych instrukcji dowiesz się, jak skonfigurować strony w technologii Signed Exchange za pomocą Web Packager. Zawiera on instrukcje dotyczące zarówno certyfikatów podpisanych samodzielnie, jak i CanSignHttpExchanges.

Wyświetlanie SXG za pomocą certyfikatu podpisanego samodzielnie

Korzystanie z certyfikatu z podpisem własnym do obsługi SXG jest używane głównie do celów demonstracyjnych i testowania. SXG podpisane samodzielnie wygenerują komunikaty o błędach w przeglądarce, gdy będą używane poza środowiskami testowymi, i nie powinny być wyświetlane robotom.

Wymagania wstępne

Aby wykonać te instrukcje, musisz mieć zainstalowane w środowisku programistycznym narzędzia opensslGo.

Generowanie samodzielnie podpisanego certyfikatu

Z tej sekcji dowiesz się, jak wygenerować samopodpisany certyfikat, który można używać z wymianami podpisanymi.

Instrukcje

  1. Wygeneruj klucz prywatny.

    openssl ecparam -out priv.key -name prime256v1 -genkey
    

    Klucz prywatny zostanie zapisany jako plik o nazwie priv.key.

  2. Utwórz żądanie podpisania certyfikatu (CSR).

    openssl req -new -sha256 -key priv.key -out cert.csr -subj '/O=Web Packager Demo/CN=example.com'
    

    Żądanie podpisania certyfikatu to blok zakodowanego tekstu, który zawiera informacje potrzebne do wysłania prośby o certyfikat do urzędu certyfikacji(CA). Chociaż nie będziesz prosić urzędu certyfikacji o certyfikat, musisz utworzyć żądanie podpisania certyfikatu.

    Powyższe polecenie tworzy żądanie podpisania certyfikatu dla organizacji o nazwie Web Packager Demo, która ma wspólną nazwę example.com. Wspólna nazwa powinna być pełną i jednoznaczną nazwą domeny witryny zawierającej treści, które chcesz spakować jako SXG.

    W produkcyjnej konfiguracji SXG jest to witryna, która należy do Ciebie. Jednak w środowisku testowym, takim jak opisane w tych instrukcjach, może to być dowolna witryna.

  3. Utwórz certyfikat z rozszerzeniem CanSignHttpExchanges.

    openssl x509 -req -days 90 -in cert.csr -signkey priv.key -out cert.pem -extfile <(echo -e "1.3.6.1.4.1.11129.2.1.22 = ASN1:NULL\nsubjectAltName=DNS:example.com")
    

    To polecenie używa klucza prywatnego i żądania podpisania certyfikatu (CSR) utworzonego w kroku 1 i 2, aby utworzyć plik certyfikatu cert.pem. Flaga -extfile łączy certyfikat z rozszerzeniem certyfikatu CanSignHttpExchanges (1.3.6.1.4.1.11129.2.1.22 to identyfikator obiektu rozszerzenia CanSignHttpExchanges). Flaga -extfile definiuje również example.com jako nazwa alternatywna podmiotu.

    Jeśli chcesz sprawdzić zawartość pliku cert.pem, możesz to zrobić za pomocą tego polecenia:

    openssl x509 -in cert.pem -noout -text
    

    Utworzono klucze prywatne i certyfikaty. W następnej sekcji będziesz potrzebować plików priv.keycert.pem.

Konfigurowanie serwera Web Packager na potrzeby testowania

Wymagania wstępne

  1. Zainstaluj Web Packager.

    git clone https://github.com/google/webpackager.git
    
  2. Kompilacja webpkgserver.

    cd webpackager/cmd/webpkgserver
    go build .
    

    webpkgserver to konkretny plik binarny w projekcie Web Packager.

  3. Sprawdź, czy aplikacja webpkgserver została prawidłowo zainstalowana.

    ./webpkgserver --help
    

    To polecenie powinno zwrócić informacje o użyciu webpkgserver. Jeśli to nie zadziała, pierwszym krokiem w rozwiązywaniu problemów jest sprawdzenie, czy GOPATH jest prawidłowo skonfigurowany.

Instrukcje

  1. Przejdź do katalogu webpkgserver (być może jesteś już w tym katalogu).

    cd /path/to/cmd/webpkgserver
    
  2. Utwórz plik webpkgsever.toml, kopiując przykład.

    cp ./webpkgserver.example.toml ./webpkgserver.toml
    

    Ten plik zawiera opcje konfiguracji webpkgserver.

  3. Otwórz plik webpkgserver.toml w dowolnym edytorze i wprowadź te zmiany:

    • Zmień linię #AllowTestCert = false na AllowTestCert = true.
    • Zmień wiersz PEMFile = 'path/to/your.pem', aby odzwierciedlał ścieżkę do utworzonego przez Ciebie certyfikatu PEM cert.pem. Nie zmieniaj wiersza zawierającego TLS.PEMFile – to inna opcja konfiguracji.
    • Zmień linię KeyFile = 'priv.key', aby odzwierciedlała ścieżkę utworzonego przez Ciebie klucza prywatnego priv.key. Nie zmieniaj wiersza z wartością TLS.KeyFile – to inna opcja konfiguracji.
    • Zmień linię #CertURLBase = '/webpkg/cert' na CertURLBase = 'data:'. CertURLBase wskazuje lokalizację wyświetlania certyfikatu SXG. Te informacje służą do ustawienia parametru cert-url w nagłówku Signature pliku SXG. W środowiskach produkcyjnych CertURLBase jest używany w ten sposób: CertURLBase = 'https://mysite.com/'. Jednak na potrzeby testowania lokalnego można użyć elementu CertURLBase = 'data:', aby polecić elementowi webpkgserver użycie adresu URL danych w celu umieszczenia certyfikatu w polu cert-url. W przypadku testów lokalnych jest to najwygodniejszy sposób udostępniania certyfikatu SXG.
    • Zmień wiersz Domain = 'example.org', aby odzwierciedlał domenę, dla której został utworzony certyfikat. Jeśli instrukcje w tym artykule zostały wykonane dokładnie, wartość ta powinna zostać zmieniona na example.com. webpkgserver pobiera tylko treści z domeny wskazanej przez webpkgserver.toml. Jeśli spróbujesz pobrać strony z innej domeny bez aktualizowania pliku webpkgserver.toml, w logach webpkgserver pojawi się komunikat o błędzie URL doesn't match the fetch targets.

    Opcjonalny

    Jeśli chcesz włączyć lub wyłączyć wstępne pobieranie zasobów podrzędnych, możesz użyć tych opcji konfiguracji webpkgserver.toml:

    • Aby webpkgserver wstawiała dyrektywy dotyczące wstępnego wczytania szablonu i podzasobów skryptu jako SXG, zmień wiersz #PreloadCSS = false na PreloadCSS = true. Dodatkowo zmień wiersz #PreloadJS = false na PreloadJS = true.

      Zamiast tej opcji konfiguracji możesz ręcznie dodać nagłówki Link: rel="preload" i tagi <link rel="preload"> do kodu HTML strony.

    • Domyślnie tag webpkgserver zastępuje istniejące tagi <link rel="preload"> równoważnymi tagami <link>, które są potrzebne do pobierania tych treści w formacie SXG. W tym celu webpkgserver ustawia dyrektywy allowed-alt-sxgheader-integrity odpowiednio do potrzeb. Autorzy kodu HTML nie muszą dodawać ich ręcznie. Aby zignorować to zachowanie i zachować istniejące wstępnie załadowane pliki, które nie są w formacie SXG, zmień wartość parametru #KeepNonSXGPreloads (default = false) na KeepNonSXGPreloads = true. Pamiętaj, że włączenie tej opcji może spowodować, że SXG nie będzie kwalifikować się do umieszczenia w pamięci podręcznej Google SXG zgodnie z tymi wymaganiami.

  4. Rozpocznij webpkgserver.

    ./webpkgserver
    

    Jeśli serwer został uruchomiony, powinieneś zobaczyć te komunikaty w dzienniku: shell Listening at 127.0.0.1:8080 Successfully retrieved valid OCSP. Writing to cache in /private/tmp/webpkg

    Komunikaty logowania mogą wyglądać nieco inaczej. W szczególności katalog, którego webpkgserver używa do przechowywania w pamięci podręcznej certyfikatów, różni się w zależności od systemu operacyjnego.

    Jeśli nie widzisz tych komunikatów, pierwszym krokiem rozwiązywania problemów jest ponowne sprawdzenie webpkgserver.toml.

    Jeśli zaktualizujesz webpkgserver.toml, musisz ponownie uruchomić webpkgserver.

  5. Uruchom Chrome za pomocą tego polecenia: shell /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \ --user-data-dir=/tmp/udd \ --ignore-certificate-errors-spki-list=`openssl x509 -noout -pubkey -in cert.pem | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | base64`

    To polecenie instruuje Chrome, aby zignorował błędy certyfikatu związane z cert.pem. Umożliwia to testowanie SXG za pomocą certyfikatu testowego. Jeśli Chrome zostanie uruchomiony bez tego polecenia, podczas sprawdzania SXG w Narzędziach deweloperskich pojawi się błąd Certificate verification error: ERR_CERT_INVALID.

    Uwaga:

    Może być konieczne dostosowanie tego polecenia, aby odzwierciedlało lokalizację Chrome na Twoim komputerze, a także lokalizację cert.pem. Jeśli wszystko się uda, pod paskiem adresu powinno pojawić się ostrzeżenie. Ostrzeżenie powinno wyglądać tak: You are using an unsupported command-line flag: --ignore-certificate-errors-spki-list=9uxADcgc6/ho0mJLRMBcOjfBaN21k0sOInoMchr9CMY=.

    Jeśli ostrzeżenie nie zawiera ciągu haszowania, nieprawidłowo wskazano lokalizację certyfikatu SXG.

  6. Otwórz kartę Sieć w Narzędziach deweloperskich, a następnie otwórz adres URL http://localhost:8080/priv/doc/https://example.com.

    Wysyła żądanie do instancji webpackager uruchomionej pod adresem http://localhost:8080 w celu pobrania SXG zawierającego zawartość https://example.com. /priv/doc/ to domyślny punkt końcowy interfejsu API używany przez webpackager.

    Zrzut ekranu przedstawiający kartę Sieć w Narzędziach deweloperskich z pokazem SXG i jego certyfikatu

    Na karcie Sieć znajdziesz te zasoby:

    • Zasób typu signed-exchange. To jest SXG.
    • Zasób typu cert-chain+cbor. To jest certyfikat SXG. Certyfikaty SXG muszą mieć format application/cert-chain+cbor.
    • Zasób typu document. To są treści dostarczone za pomocą SXG.

    Jeśli nie widzisz tych zasobów, wyczyść pamięć podręczną przeglądarki, a następnie przeładuj http://localhost:8080/priv/doc/https://example.com.

    Aby wyświetlić więcej informacji o podpisanym wymianie i jej podpisie, kliknij kartę Podgląd.

    Zrzut ekranu karty Podgląd z wyświetlonym SXG

Wyświetlanie wymian podpisanych za pomocą certyfikatu CanSignHttpExchanges

Z instrukcji w tej sekcji dowiesz się, jak wyświetlać pliki SXG przy użyciu certyfikatu CanSignHttpExchanges. Korzystanie z SXG w produkcji wymaga posiadania certyfikatu CanSignHttpExchanges.

Aby skrócić te instrukcje, zakładamy, że rozumiesz pojęcia omówione w sekcji Konfigurowanie Signed Exchange za pomocą samodzielnie podpisanego certyfikatu.

Wymagania wstępne

  • Masz certyfikat CanSignHttpExchanges. Na tej stronie znajdziesz listę urzędów certyfikacji, które oferują ten typ certyfikatu.

  • Jeśli nie masz certyfikatu, możesz skonfigurować serwer webpkgserver tak, aby automatycznie pobierał certyfikaty z urzędu certyfikacji. Możesz postępować zgodnie z instrukcjami dotyczącymi tego, co należy umieścić w sekcji webpkgserver.toml, podanymi na tej stronie.

  • Chociaż nie jest to wymagane, zdecydowanie zalecamy uruchamianie webpkgserver za pomocą serwera peryferyjnego. Jeśli nie używasz serwera brzegowego, musisz skonfigurować opcje TLS.PEMFile i TLS.KeyFile w webpkgserver.toml. Domyślnie webpkgserver działa przez HTTP. Aby przeglądarka uznała certyfikaty SXG za ważne, muszą one być jednak udostępniane przez protokół HTTPS. Konfiguracja TLS.PEMFile i TLS.KeyFile umożliwia webpkgserver korzystanie z HTTPS, a tym samym dostarczanie certyfikatu SXG bezpośrednio do przeglądarki.

Instrukcje

  1. Utwórz plik PEM, łącząc certyfikat SXG witryny z certyfikatem CA witryny. Więcej instrukcji znajdziesz tutaj.

    PEM to format pliku, który jest często używany jako „kontener” do przechowywania wielu certyfikatów.

  2. Utwórz nowy plik webpkgsever.toml, kopiując przykład.

    cp ./webpkgserver.example.toml ./webpkgserver.toml
    
  3. Otwórz plik webpkgserver.toml w wybranym edytorze i wprowadź te zmiany:

    • Zmień wiersz PEMFile = cert.pem, aby odzwierciedlał lokalizację pliku PEM zawierającego pełny łańcuch certyfikatów.
    • Zmień wiersz KeyFile = 'priv.key', aby odpowiadał lokalizacji klucza prywatnego odpowiadającego plikowi PEM.
    • Zmień wiersz Domain = 'example.org', aby pasował do Twojej witryny.
    • (Opcjonalnie) Aby certyfikat SXG był automatycznie odnawiany co 90 dni (45 dni w przypadku Google), skonfiguruj opcje w sekcji [SXG.ACME] w webpkgserver.toml.webpkgserver Ta opcja dotyczy tylko witryn z ustawionym kontem DigiCert lub Google ACME.
  4. Skonfiguruj serwer brzegowy tak, aby przekierowywał ruch do instancji webpkgserver.

    webpkgserver obsługuje 2 główne typy żądań: żądania SXG (które są obsługiwane przez punkt końcowy /priv/doc/) i żądania certyfikatu SXG (które są obsługiwane przez punkt końcowy /webpkg/cert/). Reguły przekształcania adresów URL w przypadku poszczególnych typów żądań różnią się nieznacznie. Więcej informacji znajdziesz w artykule Uruchamianie usługi na serwerze front-endu.

    Uwaga:

    Domyślnie webpkgserver udostępnia certyfikat SXG pod adresem /webpkg/cert/$CERT_HASH, np. /webpkg/cert/-0QmE0gvoedn92gtwI3s7On9zPevJGm5pn2RYhpZxgY. Aby wygenerować $CERT_HASH, uruchom to polecenie:shell openssl base64 -in cert.pem -d | openssl dgst -sha256 -binary | base64 | tr /+ _- | tr -d =