如何使用 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 擴充功能的物件 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。

      除了使用這項設定選項之外，您還可以在網頁的 HTML 中手動新增 Link: rel="preload" 標頭和 <link rel="preload"> 標記。

    • 根據預設，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 相關聯的憑證錯誤。這樣就能使用測試憑證來測試 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 端點。

    「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」(預覽) 分頁標籤，查看 Signed Exchange 及其簽名的詳細資訊。

    「Preview」分頁的螢幕截圖，其中顯示 SXG

使用 CanSignHttpExchanges 憑證提供 Signed Exchange

本節的操作說明，說明如何使用 CanSignHttpExchanges 憑證提供 SXG。實際工作環境的 SXG 需要 CanSignHttpExchanges 憑證。

為求簡潔，這些操作說明的編寫為假設您已瞭解「使用自行簽署憑證設定 Signed Exchange」一節所述的概念。

必要條件

  • 您有 CanSignHttpExchanges 組憑證。這個頁面列出了提供這類憑證的 CA。

  • 如果您沒有憑證，可以將 webpkgserver 設為自動從 CA 擷取憑證。您可以在這個頁面中遵循 webpkgserver.toml 所含內容的指示。

  • 雖然這並非必要事項，但我們強烈建議您在邊緣伺服器後方執行 webpkgserver。如果您不使用邊緣伺服器，就必須在 webpkgserver.toml 中設定 TLS.PEMFile 和 TLS.KeyFile 選項。根據預設，webpkgserver 會透過 HTTP 執行。不過，必須透過 HTTPS 提供 SXG 憑證，才會將憑證視為有效的瀏覽器。設定 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 =