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

Dowiedz się, jak obsługiwać Signed Exchange (SXG) za pomocą narzędzia do pakietów internetowych.

Katie Hempenius
Katie Hempenius
X

Signed Exchange (SXG) to mechanizm dostarczania, który umożliwia uwierzytelnianie źródła zasobu niezależnie od sposobu jego dostarczenia. Poniżej znajdziesz instrukcje konfigurowania Signed Exchange za pomocą narzędzia Web Packager. Instrukcje są zawarte zarówno w przypadku certyfikatów podpisanych samodzielnie, jak i certyfikatów CanSignHttpExchanges.

Obsługa SXG z użyciem certyfikatu podpisanego samodzielnie

Używanie samodzielnie podpisanego certyfikatu 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 openssl i Go.

Generowanie samodzielnie podpisanego certyfikatu

Z tej sekcji dowiesz się, jak wygenerować samopodpisane certyfikaty, które 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.

    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 złożenia 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 o wspólnej nazwie 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. 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). Dodatkowo flaga -extfile definiuje example.com jako alternatywną nazwę podmiotu.

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

    openssl x509 -in cert.pem -noout -text

    To już koniec tworzenia kluczy prywatnych i certyfikatów. W następnej sekcji będą potrzebne pliki priv.key i cert.pem.

Konfigurowanie serwera Web Packager na potrzeby testowania

Wymagania wstępne

  1. Zainstaluj program pakietu internetowego.

    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 funkcji webpkgserver. Jeśli to nie zadziała, pierwszym krokiem w rozwiązywaniu problemu powinno być sprawdzenie, czy zmienna GOPATH jest prawidłowo skonfigurowana.

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 wybranym 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 certyfikatu PEM (cert.pem). Nie zmieniaj wiersza zawierającego TLS.PEMFile – to inna opcja konfiguracji.
    • Zmień wiersz KeyFile = 'priv.key', by odzwierciedlał ścieżkę utworzonego przez Ciebie klucza prywatnego (priv.key). Nie zmieniaj wiersza zawierającego TLS.KeyFile – to inna opcja konfiguracji.
    • Zmień linię #CertURLBase = '/webpkg/cert' na CertURLBase = 'data:'. CertURLBase wskazuje lokalizację udostępniania certyfikatu SXG. Te informacje służą do ustawienia parametru cert-url w nagłówku SXG (Signature). 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 być równa example.com. webpkgserver będzie pobierać treści tylko z domeny wskazanej przez webpkgserver.toml. Jeśli spróbujesz pobrać strony z innej domeny bez aktualizowania pliku webpkgserver.toml, w dziennikach 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 dodać dyrektywy wstawiania webpkgserver do wstępnego wczytywania arkusza stylów i zasobów podrzędnych 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 webpkgserver zastępuje istniejące tagi <link rel="preload"> równoważnymi tagami <link>, które są potrzebne do pobierania tych treści jako SXG. W tym celu webpkgserver ustawia dyrektywy allowed-alt-sxg i header-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. Uruchom 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 dziennika 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 komputerze oraz lokalizację cert.pem. Jeśli wszystko się uda, pod paskiem adresu powinno pojawić się ostrzeżenie. Ostrzeżenie powinno wyglądać mniej więcej 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.

    Spowoduje to wysłanie do instancji webpackager uruchomionej pod adresem http://localhost:8080 żądania 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

Udostępnianie podpisanej wymiany za pomocą certyfikatu CanSignHttpExchanges

Z instrukcji w tej sekcji dowiesz się, jak wyświetlać pliki SXG przy użyciu certyfikatu CanSignHttpExchanges. Użycie w środowisku produkcyjnym SXG wymaga 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 serwerem brzegowym. 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 jednak przeglądarka uznała certyfikaty SXG za ważne, muszą one być udostępniane przez protokół HTTPS. Jeśli skonfigurujesz TLS.PEMFile i TLS.KeyFile, webpkgserver będzie używać HTTPS i tym samym udostępniać certyfikat SXG bezpośrednio w przeglądarce.

Instrukcje

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

    PEM to format pliku powszechnie 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 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 usługa webpkgserver automatycznie odnawiała certyfikat SXG co 90 dni (45 dni w przypadku Google), skonfiguruj opcje w sekcji [SXG.ACME] w narzędziu webpkgserver.toml. 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 frontendu.

    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 =