如何使用 Web Packager 设置 Signed Exchange

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

Katie Hempenius
Katie Hempenius

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

使用自签名证书分发 SXG 主要用于演示和测试目的。使用自签名证书签名的 SXG 在测试环境之外使用时会在浏览器中生成错误消息,并且不应提供给抓取工具。

若要按照这些说明操作,您需要在开发环境中安装 opensslGo

生成自签名证书

本部分介绍了如何生成可与已签名交换使用且自签名的证书。

操作说明

  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.22CanSignHttpExchanges 扩展的对象标识符)。此外,-extfile 标志还将 example.com 定义为主体备用名称

    如果您想了解 cert.pem 的内容,可以使用以下命令查看:

    openssl x509 -in cert.pem -noout -text
    

    您已完成私钥和证书的创建。下一部分中将会用到 priv.keycert.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.comwebpkgserver 将仅从 webpkgserver.toml 指示的网域中提取内容。如果您尝试从其他网域提取网页,但未更新 webpkgserver.tomlwebpkgserver 日志将显示错误消息 URL doesn't match the fetch targets

    可选

    如果您想启用或停用子资源预加载,请使用以下 webpkgserver.toml 配置选项:

    • 如需让 webpkgserver 插入用于将样式表和脚本子资源预加载为 SXG 的指令,请将 #PreloadCSS = false 行更改为 PreloadCSS = true。此外,将 #PreloadJS = false 行更改为 PreloadJS = true

      除了使用此配置选项,您还可以手动向网页的 HTML 添加 Link: rel="preload" 标头和 <link rel="preload"> 标记。

    • 默认情况下,webpkgserver 会将现有的 <link rel="preload"> 标记替换为将此内容作为 SXG 提取所需的等效 <link> 标记。这样一来,webpkgserver 会根据需要设置 allowed-alt-sxgheader-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 及其证书的开发者工具 Network 标签页屏幕截图。

    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。只有 CanSignHttpExchanges 证书才能在生产环境中使用 SXG。

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

前提条件

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

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

  • 强烈建议您在边缘服务器后面运行 webpkgserver,不过这不是一项强制性要求。如果您不使用边缘服务器,则需要在 webpkgserver.toml 中配置 TLS.PEMFileTLS.KeyFile 选项。默认情况下,webpkgserver 通过 HTTP 运行。不过,浏览器必须通过 HTTPS 提供 SXG 证书,才能将其视为有效。配置 TLS.PEMFileTLS.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 =