ウェブ パッケージャを使用して 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 からの証明書はリクエストしませんが、証明書署名リクエストを作成する必要があります。

    上記のコマンドは、共通名 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 拡張のオブジェクト識別子です）。また、-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:' を使用して、データ 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 キャッシュの対象外になる可能性があります。

  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 を再読み込みしてみてください。

    [プレビュー] タブをクリックして、Signed Exchange とその署名の詳細を表示します。

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

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 証明書をブラウザに直接提供できます。

手順

  1. サイトの SXG 証明書とサイトの CA 証明書を連結して、PEM ファイルを作成します。詳細については、こちらをご覧ください。

    PEM は、複数の証明書を保存するための「コンテナ」として一般的に使用されるファイル形式です。

  2. サンプルをコピーして、新しい webpkgsever.toml ファイルを作成します。

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

  3. 任意のエディタで 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 の アカウントが設定されているサイトにのみ適用されます

  4. トラフィックを 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 =