瞭解如何使用 Web Packager 放送 Signed Exchange (SXG)。
「Signed Exchange (SXG)」是一種傳遞機制,能夠獨立驗證資源的來源,與驗證方式無關。以下操作說明說明如何使用 Web Packager 設定 Signed Exchange。自行簽署憑證和 CanSignHttpExchanges
憑證都包含操作說明。
使用自行簽署的憑證提供 SXG
使用自行簽署的憑證提供 SXG 主要用於示範和測試。使用自行簽署憑證簽署的 SXG 會在環境外使用時,在瀏覽器中產生錯誤訊息,而且不應提供給檢索器。
必要條件
如要按照這些操作說明進行,您必須在開發環境中安裝 openssl 和 Go。
產生自行簽署的憑證
本節說明如何產生自行簽署的憑證,可與 Signed Exchange 搭配使用。
操作說明
產生私密金鑰。
openssl ecparam -out priv.key -name prime256v1 -genkey
私密金鑰會儲存為
priv.key
檔案。建立憑證簽署要求 (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 設定中,這是指您擁有的網站。不過,在測試環境中如本操作說明所述,這類環境可以是任何網站。
建立具有
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 伺服器
必要條件
安裝 Web Packager。
git clone https://github.com/google/webpackager.git
建構
webpkgserver
。cd webpackager/cmd/webpkgserver go build .
webpkgserver
是 Web Packager 專案中的特定二進位檔。確認
webpkgserver
已正確安裝。./webpkgserver --help
這個指令應傳回
webpkgserver
使用情形的相關資訊。如果這個方法無效,建議您先確認 GOPATH 設定正確。
操作說明
前往
webpkgserver
目錄 (您可能已在這個目錄中)。cd /path/to/cmd/webpkgserver
複製範例來建立
webpkgsever.toml
檔案。cp ./webpkgserver.example.toml ./webpkgserver.toml
這個檔案包含
webpkgserver
的設定選項。請以您選擇的編輯器開啟
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 快取。
- 將
啟動
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
。使用下列指令啟動 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 憑證的位置。
開啟開發人員工具的「Network」分頁,然後造訪下列網址:
http://localhost:8080/priv/doc/https://example.com
。這會向
http://localhost:8080
執行的webpackager
執行個體發出要求,以取得包含https://example.com
內容的 SXG。/priv/doc/
是webpackager
使用的預設 API 端點。「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 及其簽名的詳細資訊。
- 類型為
使用 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 憑證提供給瀏覽器。
操作說明
建立 PEM 檔案,方法是串連網站的 SXG 憑證,然後加上網站的 CA 憑證。如需詳細操作說明,請參閱這篇文章。
PEM 是一種檔案格式,通常是用來儲存多個憑證的「容器」。
複製範例,建立新的
webpkgsever.toml
檔案。cp ./webpkgserver.example.toml ./webpkgserver.toml
請使用您選擇的編輯器開啟
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 帳戶設定的網站。
- 變更
設定邊緣伺服器,將流量轉送至
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 =