如何使用 Web Packager 设置 Signed Exchange

了解如何使用 Web Packager 提供 Signed Exchange (SXG)。

Katie Hempenius

Signed Exchange (SXG) 是一种传送机制， 验证资源的来源，与提供资源的方式无关。 以下说明介绍了如何使用 Web Packager。相关说明包括 自签名证书和 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 的服务地点 证书。此信息用来设置 cert-url 参数， 该 Signature SXG 的头文件。在生产环境中，使用 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"> 标记 包含提取此内容所需的等效 <link> 标记， SXG。这样，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。这样，您就可以使用 证书。如果在没有此命令的情况下启动 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。

   这会向在以下位置运行的 webpackager 实例发出请求： http://localhost:8080，表示包含 https://example.com。/priv/doc/ 是以下 API 使用的默认 API 端点： webpackager。

   

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

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

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

   点击预览标签页，查看有关 Signed Exchange 的更多信息 及其签名。

   

使用 CanSignHttpExchanges 证书提供 Signed Exchange

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

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

前提条件

• 您有一个“CanSignHttpExchanges”证书。这个 页面 列出提供此类证书的 CA。

• 如果您没有证书，可以将 webpkgserver 配置为 自动从您的 CA 检索证书。您可以遵循 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 天（Google 为 45 天），请配置[SXG.ACME] webpkgserver.toml。此选项仅适用于具有 DigiCert 的网站 或 Google ACME 账号设置。

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

   webpkgserver 会处理两种主要类型的请求： SXG（由 /priv/doc/ 端点提供）和对 SXG 证书（由 /webpkg/cert/ 端点提供）。通过 上述每种请求类型的网址重写规则略有不同。对于 请参阅在前端边缘后面运行 服务器。

   注意：

   默认情况下，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 =