如何使用 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。

生成自签名证书

本部分介绍如何生成可与 Signed Exchange 搭配使用的自签名证书。

操作说明

  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 Packager 服务器以进行测试

前提条件

  1. 安装 Web Packager。

    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 证书的服务位置。此信息可用于在 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 端点。

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

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

    • 类型为 signed-exchange 的资源。我们就是 SXG。
    • 类型为 cert-chain+cbor 的资源。这是 SXG 证书。SXG 证书必须使用 application/cert-chain+cbor 格式。
    • 类型为 document 的资源。这是通过 SXG 提交的内容。

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

    点击预览标签页，以详细了解 Signed Exchange 及其签名。

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

使用 CanSignHttpExchanges 证书提供 Signed Exchange 服务

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

为简洁起见，在编写这些说明时，我们假设您了解使用自签名证书设置 Signed Exchange 部分中介绍的概念。

前提条件

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

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

  • 虽然不是强制性要求，但我们强烈建议您在边缘服务器后面运行 webpkgserver。如果您不使用边缘服务器，则需要在 webpkgserver.toml 中配置 TLS.PEMFile 和 TLS.KeyFile 选项。默认情况下，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 每 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 =