如何使用 Web Packager 设置签名交换

了解如何使用 Web Packager 提供签名交换 (SXG)。

Katie Hempenius
Katie Hempenius
X - Web开发指南

签名交换 (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'

    证书签名请求是一个编码文本块，它传达从证书颁发机构 (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 使用 data 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"> 标记替换为将此内容作为 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 时没有此命令，则在 DevTools 中检查 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 选项卡，然后访问以下 URL：https://:8080/priv/doc/https://example.com。

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

    Screenshot of the DevTools Network tab showing a SXG and its certificate.

    以下资源列在 Network 选项卡中

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

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

    单击 Preview 选项卡以查看有关签名交换及其签名的更多信息。

    Screenshot of the Preview tab showing a SXG

使用 CanSignHttpExchanges 证书提供签名交换

本节中的说明解释了如何使用 CanSignHttpExchanges 证书提供 SXG。生产环境中使用 SXG 需要 CanSignHttpExchanges 证书。

为了简洁起见，这些说明的编写假设你理解使用自签名证书设置签名交换部分中讨论的概念。

前提条件

  • 你有一个 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. 通过连接你站点的 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/ 端点提供服务）。每种请求类型的 URL 重写规则略有不同。有关更多信息，请参见在前端边缘服务器后面运行。

    注意

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