如何使用 Web Packager 设置 Signed Exchange

了解如何使用 Web Packager 投放 Signed Exchange (SXG)。

Katie Hempenius
Katie Hempenius
X

Signed Exchange (SXG) 是一种提交机制，可让您验证资源的来源，而无需考虑其提交方式。以下说明介绍了如何使用 Web Packager 设置 Signed Exchange。其中包含有关自签名证书和 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'

    证书签名请求是一块编码文本，用于传达从证书授权机构(CA) 请求证书所需的信息。虽然您不会向 CA 请求证书，但仍需要创建证书签名请求。

    上述命令会为名为 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")

    此命令使用第 1 步和第 2 步中创建的私钥和 CSR 创建证书文件 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 打包工具服务器以进行测试

前提条件

  1. 安装 Web 打包工具。

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

  2. 构建 webpkgserver。

    cd webpackager/cmd/webpkgserver
go build .

    webpkgserver 是 Web 打包工具项目中的特定二进制文件。

  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 证书的服务位置。此信息用于在 SXG 的 Signature 标头中设置 cert-url 参数。在生产环境中，CertURLBase 的使用方式如下：CertURLBase = 'https://mysite.com/'。不过，对于本地测试，CertURLBase = 'data:' 可用于指示 webpkgserver 使用数据网址将证书内嵌到 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"> 标记替换为以 SXG 格式提取此内容所需的等效 <link> 标记。这样一来，webpkgserver 会根据需要设置 allowed-alt-sxg 和 header-integrity 指令，HTML 作者无需手动添加这些指令。如需替换此行为并保留现有的非 SXG 预加载项，请将 #KeepNonSXGPreloads (default = false) 更改为 KeepNonSXGPreloads = true。请注意，启用此选项可能会导致 SXG 不符合这些要求，无法使用 Google SXG 缓存。

  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 时会显示错误 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 的 Network（网络）标签页，然后访问以下网址：http://localhost:8080/priv/doc/https://example.com。

    这会向 http://localhost:8080 上运行的 webpackager 实例发出请求，请求包含 https://example.com 内容的 SXG。/priv/doc/ 是 webpackager 使用的默认 API 端点。

    开发者工具“Network”（网络）标签页的屏幕截图，其中显示了 SXG 及其证书。

    Network 标签页中列出了以下资源：

    • 类型为 signed-exchange 的资源。这是 SXG。
    • 类型为 cert-chain+cbor 的资源。这是 SXG 证书。SXG 证书必须采用 application/cert-chain+cbor 格式。
    • 类型为 document 的资源。这是通过 SXG 传送的内容。

    如果您没有看到这些资源，请尝试清除浏览器缓存，然后重新加载 http://localhost:8080/priv/doc/https://example.com。

    点击预览标签页，详细了解已签名交换及其签名。

    显示 SXG 的“预览”标签页的屏幕截图

使用 CanSignHttpExchanges 证书提供已签名广告交易

本部分中的说明介绍了如何使用 CanSignHttpExchanges 证书分发 SXG。在生产环境中使用 SXG 需要 CanSignHttpExchanges 证书。

为简洁起见，以下说明假定您了解使用自签名证书设置已签名交换部分中讨论的概念。

前提条件

  • 您拥有 CanSignHttpExchanges 证书。此页面列出了提供此类证书的 CA。

  • 如果您没有证书，可以将 webpkgserver 配置为自动从 CA 检索证书。您可以按照此页面中关于如何填充 webpkgserver.toml 的说明操作。

  • 虽然这不是强制性要求，但我们强烈建议您在边缘服务器后面运行 webpkgserver。如果您不使用边缘服务器，则需要在 webpkgserver.toml 中配置 TLS.PEMFile 和 TLS.KeyFile 选项。默认情况下，webpkgserver 通过 HTTP 运行。不过，浏览器必须通过 HTTPS 提供 SXG 证书，才能被视为有效。配置 TLS.PEMFile 和 TLS.KeyFile 后，webpkgserver 便可使用 HTTPS，从而直接向浏览器提供 SXG 证书。

操作说明

  1. 通过将您网站的 SXG 证书与您网站的 CA 证书串联起来，创建一个 PEM 文件。如需了解详情，请点击此处。

    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 每 90 天（对于 Google 为 45 天）自动续订 SXG 证书，请在 webpkgserver.toml 的 [SXG.ACME] 部分中配置选项。此选项仅适用于已设置 DigiCert 或 Google ACME 账号的网站。

  4. 配置边缘服务器以将流量转发到 webpkgserver 实例。

    webpkgserver 处理的主要请求有两种：SXG 请求（由 /priv/doc/ 端点提供）和 SXG 证书请求（由 /webpkg/cert/ 端点提供）。每种请求类型的网址重写规则略有不同。如需了解详情，请参阅在前端边缘服务器后面运行。

    注意：

    默认情况下，webpkgserver 会在 /webpkg/cert/$CERT_HASH 上提供 SXG 证书，例如 /webpkg/cert/-0QmE0gvoedn92gtwI3s7On9zPevJGm5pn2RYhpZxgY。如需生成 $CERT_HASH，请运行以下命令：shell openssl base64 -in cert.pem -d | openssl dgst -sha256 -binary | base64 | tr /+ _- | tr -d =