如何使用 Web Packager 設定 Signed Exchange

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

Katie Hempenius
Katie Hempenius
X

Signed Exchange (SXG) 是一種傳送機制，可讓 驗證資源來源，獨立驗證資源傳送方式。 下列操作說明會說明如何設定「Signed Exchange」 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 為 物件 ID 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 如下所示：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 無法在 各個元件所需的 requirements。

  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。

    這會向在下列位置執行的 webpackager 執行個體發出要求： http://localhost:8080 代表 SXG，其中包含 https://example.com。/priv/doc/ 是 Cloud Shell 中所用的預設 API 端點 webpackager。

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

    按一下「預覽」分頁標籤，進一步瞭解 Signed Exchange 與其簽章

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

使用 CanSignHttpExchanges 憑證提供 Signed Exchange

本節將說明如何使用 CanSignHttpExchanges 憑證。實作 SXG 需要有 CanSignHttpExchanges 憑證。

為求簡潔，這些指示是以假設 熟悉設定 Signed Exchanges 機制中 使用自行簽署的 認證 專區。

必要條件

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

  • 如果您沒有憑證，可以將 webpkgserver 設定為 自動從 CA 擷取憑證。您可以按照 顯示webpkgserver.toml前方的路程 頁面。

  • 雖然這並非硬性規定 webpkgserver。如果您不使用邊緣伺服器， 您必須在TLS.PEMFileTLS.KeyFile webpkgserver.toml。根據預設，webpkgserver 會透過 HTTP 執行。不過，SXG 憑證必須透過 HTTPS 提供，瀏覽器才能認定為有效憑證。 設定 TLS.PEMFile 和 TLS.KeyFile 後，webpkgserver 就能使用 HTTPS，因此直接提供 SXG 憑證給瀏覽器。

操作說明

  1. 串連網站的 SXG 憑證，然後建立 PEM 檔案，並在後面加上 網站的 CA 憑證如需更多有關這種情況的指示，請參閱 請按這裡。

    PEM 是 檔案格式通常做為「容器」儲存多個 憑證

  2. 複製範例，建立新的 webpkgsever.toml 檔案。

    cp ./webpkgserver.example.toml ./webpkgserver.toml

  3. 使用您選擇的編輯器開啟 webpkgserver.toml，然後 進行的變更：

    • 根據 PEM 的位置變更 PEMFile = cert.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 =