Как настроить подписанные обмены с помощью Web Packager

Узнайте, как обслуживать подписанные обмены (SXG) с помощью Web Packager.

Кэти Хемпениус
Katie Hempenius
X

Подписанный обмен (SXG) — это механизм доставки, который позволяет аутентифицировать происхождение ресурса независимо от того, как он был доставлен. Следующие инструкции объясняют, как настроить подписанные обмены с помощью Web Packager . Инструкции включены как для самозаверяющих сертификатов, так и для сертификатов CanSignHttpExchanges .

Обслуживание SXG с использованием самозаверяющего сертификата

Использование самозаверяющего сертификата для обслуживания SXG в основном используется в целях демонстрации и тестирования. SXG, подписанные самозаверяющим сертификатом, будут генерировать сообщения об ошибках в браузере при использовании вне сред тестирования и не должны передаваться сканерам.

Предварительные условия

Чтобы следовать этим инструкциям, вам необходимо, чтобы в вашей среде разработки были установлены openssl и Go .

Создать самозаверяющий сертификат

В этом разделе объясняется, как создать самозаверяющий сертификат, который можно использовать с подписанными обменами.

Инструкции

  1. Сгенерируйте закрытый ключ.

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

    Закрытый ключ будет сохранен в виде файла с именем priv.key .

  2. Создайте запрос на подпись сертификата (CSR).

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

    Запрос на подпись сертификата — это блок закодированного текста, который передает информацию, необходимую для запроса сертификата у центра сертификации (ЦС) . Хотя вы не будете запрашивать сертификат у центра сертификации, создать запрос на подпись сертификата все равно необходимо.

    Приведенная выше команда создает запрос на подпись сертификата для организации с именем Web Packager Demo с общим именем example.com . Общее имя должно представлять собой полное доменное имя сайта, содержащего контент, который вы хотите упаковать как SXG.

    В производственной настройке SXG это будет принадлежащий вам сайт. Однако в среде тестирования, подобной той, которая описана в этих инструкциях, это может быть любой сайт.

  3. Создайте сертификат с расширением 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")

    Эта команда использует закрытый ключ и CSR, созданный на шагах 1 и 2, для создания файла сертификата cert.pem . Флаг -extfile связывает сертификат с расширением сертификата CanSignHttpExchanges ( 1.3.6.1.4.1.11129.2.1.22 — это идентификатор объекта для расширения CanSignHttpExchanges ). Кроме того, флаг -extfile также определяет example.com как альтернативное имя субъекта .

    Если вам интересно содержимое cert.pem , вы можете просмотреть его с помощью следующей команды:

    openssl x509 -in cert.pem -noout -text

    Вы закончили создание закрытых ключей и сертификатов. В следующем разделе вам понадобятся файлы priv.key и cert.pem .

Настройте сервер Web Packager для тестирования.

Предварительные условия

  1. Установите веб-упаковщик .

    git clone https://github.com/google/webpackager.git

  2. Создайте webpkgserver .

    cd webpackager/cmd/webpkgserver
go build .

    webpkgserver — это специальный двоичный файл в проекте Web Packager.

  3. Убедитесь, что webpkgserver установлен правильно.

    ./webpkgserver --help

    Эта команда должна возвращать информацию об использовании webpkgserver . Если это не сработает, первым шагом для устранения неполадок будет проверка правильности настройки GOPATH .

Инструкции

  1. Перейдите в каталог webpkgserver (возможно, вы уже находитесь в этом каталоге).

    cd /path/to/cmd/webpkgserver

  2. Создайте файл webpkgsever.toml , скопировав пример.

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

    Этот файл содержит параметры конфигурации для webpkgserver .

  3. Откройте webpkgserver.toml в любом редакторе и внесите следующие изменения:

    • Измените строку #AllowTestCert = false на AllowTestCert = true .
    • Измените строку PEMFile = 'path/to/your.pem' чтобы она отражала путь к созданному вами сертификату PEM cert.pem . Не меняйте строку, в которой упоминается TLS.PEMFile — это другой вариант конфигурации.
    • Измените строку KeyFile = 'priv.key' , чтобы она отражала путь к созданному вами закрытому ключу priv.key . Не меняйте строку, в которой упоминается TLS.KeyFile — это другой вариант конфигурации.
    • Измените строку #CertURLBase = '/webpkg/cert' на CertURLBase = 'data:' . CertURLBase указывает место обслуживания сертификата SXG. Эта информация используется для установки параметра cert-url в заголовке Signature SXG. В производственных средах CertURLBase используется следующим образом: CertURLBase = 'https://mysite.com/' . Однако для локального тестирования можно использовать CertURLBase = 'data:' чтобы указать webpkgserver использовать URL-адрес данных для встраивания сертификата в поле cert-url . Для локального тестирования это наиболее удобный способ предоставления сертификата SXG.
    • Измените строку Domain = 'example.org' , чтобы она отражала домен, для которого вы создали сертификат. Если вы дословно следовали инструкциям этой статьи, его следует изменить на example.com . webpkgserver будет получать контент только из домена, указанного в webpkgserver.toml . Если вы попытаетесь получить страницы из другого домена без обновления webpkgserver.toml , журналы webpkgserver покажут, что URL doesn't match the fetch targets .

    Необязательный

    Если вы хотите включить или отключить предварительную загрузку подресурсов , актуальны следующие параметры конфигурации webpkgserver.toml :

    • Чтобы иметь директивы вставки webpkgserver для предварительной загрузки подресурсов таблицы стилей и скриптов в виде SXG, измените строку #PreloadCSS = false на PreloadCSS = true . Кроме того, измените строку #PreloadJS = false на PreloadJS = true .

      В качестве альтернативы использованию этого параметра конфигурации вы можете вручную добавить заголовки Link: rel="preload" и теги <link rel="preload"> в HTML-код страницы.

    • По умолчанию webpkgserver заменяет существующие теги <link rel="preload"> эквивалентными тегами <link> , необходимыми для получения этого контента в формате SXG. При этом webpkgserver при необходимости установит директивыallow allowed-alt-sxg и header-integrity — авторам HTML не нужно добавлять их вручную. Чтобы переопределить это поведение и сохранить существующие предварительные загрузки, отличные от SXG, измените #KeepNonSXGPreloads (default = false) на KeepNonSXGPreloads = true . Имейте в виду, что включение этой опции может сделать SXG неприемлемым для кэша SXG Google в соответствии с этими требованиями .

  4. Запустите webpkgserver . 

    ./webpkgserver

    Если сервер запустился успешно, вы должны увидеть следующие сообщения журнала: shell Listening at 127.0.0.1:8080 Successfully retrieved valid OCSP. Writing to cache in /private/tmp/webpkg

    Сообщения вашего журнала могут выглядеть немного иначе. В частности, каталог, который webpkgserver использует для кэширования сертификатов, зависит от операционной системы.

    Если вы не видите этих сообщений, первым делом для устранения неполадок следует дважды проверить webpkgserver.toml .

    Если вы обновляете webpkgserver.toml вам следует перезапустить webpkgserver .

  5. Запустите Chrome с помощью следующей команды: 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`

    Эта команда указывает Chrome игнорировать ошибки сертификата, связанные с cert.pem . Это позволяет тестировать SXG с использованием сертификата испытаний. Если Chrome запускается без этой команды, проверка SXG в DevTools отобразит Certificate verification error: ERR_CERT_INVALID .

    Примечание:

    Возможно, вам придется настроить эту команду, чтобы она отражала расположение Chrome на вашем компьютере, а также расположение cert.pem . Если вы все сделали правильно, под адресной строкой должно появиться предупреждение. Предупреждение должно быть примерно таким: You are using an unsupported command-line flag: --ignore-certificate-errors-spki-list=9uxADcgc6/ho0mJLRMBcOjfBaN21k0sOInoMchr9CMY=.

    Если предупреждение не содержит хэш-строки, вы неправильно указали местоположение сертификата SXG.

  6. Откройте вкладку «Сеть DevTools», затем перейдите по следующему URL-адресу: http://localhost:8080/priv/doc/https://example.com .

    Это делает запрос к экземпляру webpackager работающему по адресу http://localhost:8080 , для SXG, содержащего содержимое https://example.com . /priv/doc/ — это конечная точка API по умолчанию, используемая webpackager .

    Снимок экрана: вкладка DevTools Network, на которой показан SXG и его сертификат.

    На вкладке «Сеть» перечислены следующие ресурсы:

    • Ресурс типа signed-exchange . Это SXG.
    • Ресурс типа cert-chain+cbor . Это сертификат SXG. Сертификаты SXG должны использовать формат application/cert-chain+cbor .
    • Ресурс типа document . Это контент, который был доставлен через SXG.

    Если вы не видите эти ресурсы, попробуйте очистить кеш браузера, а затем перезагрузить http://localhost:8080/priv/doc/https://example.com .

    Нажмите вкладку «Предварительный просмотр» , чтобы просмотреть дополнительную информацию о подписанном обмене и его подписи.

    Снимок экрана: вкладка «Предварительный просмотр» с изображением SXG.

Обслуживание подписанных обменов с использованием сертификата CanSignHttpExchanges

Инструкции в этом разделе объясняют, как обслуживать SXG с помощью сертификата CanSignHttpExchanges . Для производственного использования SXG требуется сертификат CanSignHttpExchanges .

Для краткости эти инструкции написаны с учетом того, что вы понимаете концепции, обсуждаемые в разделе «Настройка подписанных обменов с использованием самозаверяющего сертификата» .

Предварительные условия

  • У вас есть сертификат CanSignHttpExchanges . На этой странице перечислены центры сертификации, предлагающие этот тип сертификата.

  • Если у вас нет сертификата, вы можете настроить свой webpkgserver на автоматическое получение сертификатов из вашего центра сертификации. Вы можете следовать инструкциям о том, что происходит в webpkgserver.toml на этой странице .

  • Хотя это и не является обязательным требованием, настоятельно рекомендуется запускать webpkgserver на пограничном сервере. Если вы не используете пограничный сервер, вам необходимо настроить параметры TLS.PEMFile и TLS.KeyFile в webpkgserver.toml . По умолчанию webpkgserver работает через HTTP. Однако сертификаты SXG должны предоставляться через HTTPS, чтобы браузер считал их действительными. Настройка TLS.PEMFile и TLS.KeyFile позволяет webpkgserver использовать HTTPS и, следовательно, передавать сертификат SXG непосредственно в браузер.

Инструкции

  1. Создайте файл PEM, объединив сертификат SXG вашего сайта и сертификат CA вашего сайта. Дополнительные инструкции по этому поводу можно найти здесь .

    PEM — это формат файла, который обычно используется в качестве «контейнера» для хранения нескольких сертификатов.

  2. Создайте новый файл webpkgsever.toml , скопировав пример. 

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

  3. Откройте webpkgserver.toml в любом редакторе и внесите следующие изменения:

    • Измените строку PEMFile = cert.pem чтобы она отражала расположение файла PEM, содержащего полную цепочку сертификатов.
    • Измените строку KeyFile = 'priv.key' чтобы отразить расположение закрытого ключа, соответствующего вашему PEM-файлу.
    • Измените строку Domain = 'example.org' , чтобы она отражала ваш сайт.
    • (Необязательно) Чтобы webpkgserver автоматически обновлял сертификат SXG каждые 90 дней (45 дней для Google), настройте параметры в разделе [SXG.ACME] файла webpkgserver.toml . Этот параметр применим только к сайтам с настроенной учетной записью DigiCert или Google ACME.

  4. Настройте свой пограничный сервер для пересылки трафика на экземпляр webpkgserver .

    Существует два основных типа запросов, обрабатываемых webpkgserver : запросы на SXG (которые обслуживаются конечной точкой /priv/doc/ ) и запросы на сертификат SXG (которые обслуживаются конечной точкой /webpkg/cert/ ). Правила перезаписи URL-адресов для каждого из этих типов запросов незначительно различаются. Дополнительные сведения см. в разделе Работа за интерфейсным пограничным сервером .

    Примечание:

    По умолчанию webpkgserver обслуживает сертификат SXG по адресу /webpkg/cert/$CERT_HASH — например, /webpkg/cert/-0QmE0gvoedn92gtwI3s7On9zPevJGm5pn2RYhpZxgY . Чтобы сгенерировать $CERT_HASH , выполните следующую команду: shell openssl base64 -in cert.pem -d | openssl dgst -sha256 -binary | base64 | tr /+ _- | tr -d =