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 からの証明書はリクエストしませんが、証明書署名リクエストを作成する必要があります。
上記のコマンドは、共通名
example.com
のWeb Packager Demo
という名前の組織の証明書署名リクエストを作成します。共通名は、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
拡張のオブジェクト識別子です)。また、-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:'
を使用して、データ URL を使用してcert-url
フィールドに証明書をインライン化するようwebpkgserver
に指示できます。ローカルテストでは、これが SXG 証明書を提供する最も便利な方法です。 - 証明書を作成したドメインを反映するように、行
Domain = 'example.org'
を変更します。この記事の手順にそのまま従っている場合は、これをexample.com
に変更する必要があります。webpkgserver
は、webpkgserver.toml
で指定されたドメインからコンテンツのみを取得します。webpkgserver.toml
を更新せずに別のドメインからページを取得しようとすると、webpkgserver
ログにエラー メッセージURL doesn't match the fetch targets
が表示されます。
任意
サブリソースのプリロードを有効または無効にする場合は、次の
webpkgserver.toml
構成オプションが関連します。スタイルシートとスクリプトのサブリソースを SXG としてプリロードするディレクティブを
webpkgserver
に挿入するには、行#PreloadCSS = false
をPreloadCSS = true
に変更します。さらに、行#PreloadJS = false
をPreloadJS = true
に変更します。この構成オプションを使用する代わりに、
Link: rel="preload"
ヘッダーと<link rel="preload">
タグを手動でページの HTML に追加できます。デフォルトでは、
webpkgserver
は既存の<link rel="preload">
タグを、このコンテンツを SXG として取得するために必要な同等の<link>
タグに置き換えます。これにより、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`
このコマンドは、
cert.pem
に関連する証明書エラーを無視するように Chrome に指示します。これにより、テスト証明書を使用して SXG をテストできます。このコマンドを使用せずに Chrome を起動した場合、DevTools で 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 証明書の場所が正しく指定されていません。
DevTools の [ネットワーク] タブを開き、URL
http://localhost:8080/priv/doc/https://example.com
にアクセスします。これにより、
http://localhost:8080
で実行されているwebpackager
インスタンスに、https://example.com
のコンテンツを含む SXG のリクエストを送信します。/priv/doc/
は、webpackager
で使用されるデフォルトの API エンドポイントです。[ネットワーク] タブに次のリソースが表示されます。
signed-exchange
型のリソース。これが SXG です。cert-chain+cbor
タイプのリソース。これが SXG 証明書です。SXG 証明書はapplication/cert-chain+cbor
形式を使用する必要があります。document
型のリソース。SXG 経由で配信されたコンテンツです。
これらのリソースが表示されない場合は、ブラウザのキャッシュを消去してから、
http://localhost:8080/priv/doc/https://example.com
を再読み込みしてみてください。[プレビュー] タブをクリックして、Signed Exchange とその署名の詳細を表示します。
CanSignHttpExchanges
証明書を使用して Signed Exchange を配信する
このセクションでは、CanSignHttpExchanges
証明書を使用して SXG を提供する方法について説明します。本番環境で SXG を使用するには、CanSignHttpExchanges
証明書が必要です。
わかりやすくするため、以下の手順は、自己署名証明書を使用して Signed Exchange を設定するセクションで説明したコンセプトを理解していることを前提としています。
前提条件
CanSignHttpExchanges
の証明書があります。こちらのページには、このタイプの証明書を提供する CA の一覧が記載されています。証明書がない場合は、CA から証明書を自動的に取得するように webpkgserver を構成できます。
webpkgserver.toml
での内容については、こちらのページをご覧ください。必須ではありませんが、エッジサーバーの背後で
webpkgserver
を実行することを強くおすすめします。エッジサーバーを使用しない場合は、webpkgserver.toml
でTLS.PEMFile
オプションとTLS.KeyFile
オプションを構成する必要があります。デフォルトでは、webpkgserver
は HTTP 経由で実行されます。ただし、SXG 証明書がブラウザで有効と見なされるには、HTTPS 経由で配信する必要があります。TLS.PEMFile
とTLS.KeyFile
を構成すると、webpkgserver
で HTTPS を使用できるため、SXG 証明書をブラウザに直接提供できます。
手順
サイトの SXG 証明書とサイトの CA 証明書を連結して、PEM ファイルを作成します。詳細については、こちらをご覧ください。
PEM は、複数の証明書を保存するための「コンテナ」として一般的に使用されるファイル形式です。
サンプルをコピーして、新しい
webpkgsever.toml
ファイルを作成します。cp ./webpkgserver.example.toml ./webpkgserver.toml
任意のエディタで
webpkgserver.toml
を開き、次の変更を行います。- 完全な証明書チェーンを含む PEM ファイルの場所を反映するように、
PEMFile = cert.pem
行を変更します。 - PEM ファイルに対応する秘密鍵の場所を反映するように、行
KeyFile = 'priv.key'
を変更します。 - サイトを表すように
Domain = 'example.org'
行を変更します。 - (省略可)
webpkgserver
が 90 日(Google の場合は 45 日)ごとに SXG 証明書を自動更新するには、webpkgserver.toml
の[SXG.ACME]
セクションでオプションを構成します。このオプションは DigiCert または Google ACME の アカウントが設定されているサイトにのみ適用されます
- 完全な証明書チェーンを含む PEM ファイルの場所を反映するように、
トラフィックを
webpkgserver
インスタンスに転送するようにエッジサーバーを構成します。webpkgserver
によって処理されるリクエストには、主に 2 つのタイプがあります。SXG のリクエスト(/priv/doc/
エンドポイントによって処理される)と SXG 証明書のリクエスト(/webpkg/cert/
エンドポイントによって処理される)です。リクエスト タイプごとに URL 書き換えルールは若干異なります。詳細については、フロントエンド エッジサーバーの背後で実行をご覧ください。注:
デフォルトでは、
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 =