如何使用 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. 打开开发者工具的 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（例如 /webpkg/cert/-0QmE0gvoedn92gtwI3s7On9zPevJGm5pn2RYhpZxgY）上提供 SXG 证书。如需生成 $CERT_HASH，请运行以下命令：shell openssl base64 -in cert.pem -d | openssl dgst -sha256 -binary | base64 | tr /+ _- | tr -d =