如何使用 Web Packager 設定 Signed Exchange

瞭解如何使用 Web Packager 放送 Signed Exchange (SXG)。

Katie Hempenius
Katie Hempenius
X

已簽署的交換 (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 擴充功能的物件 ID)。此外，-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 會以擷取此內容為 SXG 所需的對等 <link> 標記取代現有的 <link rel="preload"> 標記。如此一來，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. 開啟開發人員工具的「網路」分頁，然後前往下列網址：http://localhost:8080/priv/doc/https://example.com。

    這會向在 http://localhost:8080 執行的 webpackager 執行個體提出要求，為包含 https://example.com 內容的 SXG 發出要求。/priv/doc/ 是 webpackager 使用的預設 API 端點。

    「DevTools 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。

    按一下「Preview」分頁標籤，即可進一步瞭解已簽署的 Exchange 和其簽章。

    顯示 SXG 的「預覽」分頁螢幕截圖

使用 CanSignHttpExchanges 憑證放送已簽署的交換機制

本節的操作說明說明如何使用 CanSignHttpExchanges 憑證放送 SXG。如要將 SXG 用於正式版，就必須取得 CanSignHttpExchanges 憑證。

為求簡潔，我們撰寫這些操作說明時，假設您已瞭解「使用自行簽署的憑證設定簽署的 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. 將網站的 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 =