ウェブ パッケージャを使用して Signed Exchange を設定する方法

Web パッケージャを使用して署名付き交換（SXG）を提供する方法について学びます。

Katie Hempenius
Katie Hempenius
X

署名付き交換（SXG）は、リソースの配信方法に関係なくリソースの送信元を認証できる配信メカニズムです。次の手順では、Web パッケージャを使用して 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 から証明書をリクエストすることはありませんが、証明書署名リクエストを作成する必要があります。

    上記のコマンドは、共通名 example.com を持つ Web Packager Demo という名前の組織の証明書署名リクエストを作成します。共通名は、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 に変更します。
    • 作成した PEM 証明書 cert.pem のパスを表すように、PEMFile = 'path/to/your.pem' 行を変更します。TLS.PEMFile と記載されている行は変更しないでください。これは別の構成オプションです。
    • 作成した秘密鍵 priv.key のパスを反映するように、KeyFile = '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 構成オプションが関連します。

    • webpkgserver がスタイルシートとスクリプトのサブリソースを SXG としてプリロードするためのディレクティブを挿入するようにするには、行 #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 キャッシュの対象外になる可能性があります。

  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`

    このコマンドは、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 証明書の場所が正しく指定されていません。

  6. DevTools の [ネットワーク] タブを開き、次の URL にアクセスします。 http://localhost:8080/priv/doc/https://example.com

    これにより、http://localhost:8080 で実行されている webpackager インスタンスに、https://example.com の内容を含む SXG がリクエストされます。/priv/doc/ は、webpackager で使用されるデフォルトの API エンドポイントです。

    SXG とその証明書が表示されている DevTools の [Network] タブのスクリーンショット。

    [ネットワーク] タブには、次のリソースが表示されます。

    • signed-exchange 型のリソース。これは SXG です。
    • cert-chain+cbor 型のリソース。これは SXG 証明書です。SXG 証明書は application/cert-chain+cbor 形式を使用する必要があります。
    • document 型のリソース。これは SXG 経由で配信されたコンテンツです。

    これらのリソースが表示されない場合は、ブラウザのキャッシュを削除してから http://localhost:8080/priv/doc/https://example.com を再読み込みしてみてください。

    [プレビュー] タブをクリックすると、署名付き交換とその署名の詳細が表示されます。

    SXG を表示する [プレビュー] タブのスクリーンショット

CanSignHttpExchanges 証明書を使用して署名付き交換を提供する

このセクションの手順では、CanSignHttpExchanges 証明書を使用して SXG を提供する方法について説明します。SXG を本番環境で使用する場合は、CanSignHttpExchanges 証明書が必要です。

簡潔にするため、これらの手順は、自己署名証明書を使用して署名付き交換を設定するで説明されているコンセプトを理解していることを前提としています。

前提条件

  • CanSignHttpExchanges 証明書があります。このページでは、このタイプの証明書を提供する CA の一覧を示します。

  • 証明書がない場合は、CA から証明書を自動的に取得するように webpkgserver を構成できます。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 が SXG 証明書を 90 日ごとに自動更新（Google の場合は 45 日）するようにするには、webpkgserver.toml の [SXG.ACME] セクションでオプションを構成します。このオプションは、DigiCert または Google ACME アカウントが設定されているサイトにのみ適用されます。

  4. トラフィックを webpkgserver インスタンスに転送するようにエッジサーバーを構成します。

    webpkgserver によって処理されるリクエストには、SXG リクエスト（/priv/doc/ エンドポイントによって提供される）と SXG 証明書リクエスト（/webpkg/cert/ エンドポイントによって提供される）の 2 種類があります。これらのリクエスト タイプの 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 =