HTTP Public Key Pinning (HPKP)

サイトでこの機能を有効化するには、サイトに HTTPS でアクセスされたとに、 HTTP の Public-Key-Pins ヘッダーを返す必要があります。

Public-Key-Pins: pin-sha256="base64=="; max-age=expireTime [; includeSubDomains][; report-uri="reportURI"]

pin-sha256

二重引用符で囲まれた文字列で、 Base64 符号化された Subject Public Key Information (SPKI) のフィンガープリントです。異なる公開鍵に対する複数のピンを指定することが出来ます。将来のブラウザーでは SHA-256 以外のハッシュアルゴリズムが許容されるかもしれません。証明書や鍵ファイルからこの情報を抽出する方法は次の項で説明します。

max-age

このサイトへのアクセス時に必要となる（唯一ピン留めされた）鍵について、この鍵をブラウザーが記憶するべき時間を指定します。この値は秒単位で表現します。

includeSubDomains 省略可

このパラメータは省略可能です。サイトにおけるすべてのサブドメインにもこのルールが適用されます。

report-uri 省略可

このパラメータは省略可能です。ピンの検証に失敗した際に、失敗した旨を報告する URL を指定します。

まずは証明書や鍵ファイルから公開鍵情報を抽出し、それを Base64 でエンコードする必要があります。

次に示す便利なコマンドで、鍵ファイルや証明書署名要求 (CSR)、または証明書から Base64 エンコードされた情報を抽出できます。

openssl rsa -in my-rsa-key-file.key -outform der -pubout | openssl dgst -sha256 -binary | openssl enc -base64

openssl ec -in my-ecc-key-file.key -outform der -pubout | openssl dgst -sha256 -binary | openssl enc -base64

openssl req -in my-signing-request.csr -pubkey -noout | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | openssl enc -base64

openssl x509 -in my-certificate.crt -pubkey -noout | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | openssl enc -base64

以下のコマンドを用いると、ウェブサイト向けに情報を抽出することができます。

openssl s_client -servername www.example.com -connect www.example.com:443 | openssl x509 -pubkey -noout | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | openssl enc -base64

Public-Key-Pins:
  pin-sha256="cUPcTAZWKaASuYWhhneDttWpY3oBAkE3h2+soZS7sWs=";
  pin-sha256="M8HztCzM3elUxkcjR2S5P4hhyBNf6lHkmjAHKhpGPWE=";
  max-age=5184000; includeSubDomains;
  report-uri="https://www.example.org/hpkp-report"

この例では、 pin-sha256="cUPcTAZWKaASuYWhhneDttWpY3oBAkE3h2+soZS7sWs=" で本番系で使用されるサーバーの公開鍵をピン止めします。２番目のピン宣言である pin-sha256="M8HztCzM3elUxkcjR2S5P4hhyBNf6lHkmjAHKhpGPWE=" も、バックアップキーをピン止めします。 max-age=5184000 はクライアントにこの情報を２か月間保存するように伝え、これは IETF RFC によれば合理的な期間です。このキーのピン止めは、 includeSubDomains 宣言で指示されているように、すべてのサブドメインでも有効です。最後に、 report-uri="https://www.example.net/hpkp-report" はピンの検証の失敗を報告する場所を説明します。

Public-Key-Pins ヘッダーを用いる代わりに、 Public-Key-Pins-Report-Only ヘッダーを利用することも可能です。このヘッダーを用いた場合、ピン留めの認証に失敗した場合でも指定した report-uri にレポートが送信されるのみで、ブラウザーがウェブサーバーへ接続することは可能となります。

HPKP ヘッダーを送信するのに必要な具体的な手順はウェブサーバーによって異なります。

Apache

次のような行をウェブサーバーの config に追加すると Apache で HPKP が有効になります。 mod_headers モジュールがインストールされている必要があります。

Header always set Public-Key-Pins "pin-sha256=\"base64+primary==\"; pin-sha256=\"base64+backup==\"; max-age=5184000; includeSubDomains"

Nginx

次のような行を追加し、適切な pin-sha256="..." の値を設定すると nginx で HPKP が有効になります。 ngx_http_headers_module がインストールされている必要があります。

add_header Public-Key-Pins 'pin-sha256="base64+primary=="; pin-sha256="base64+backup=="; max-age=5184000; includeSubDomains' always;

Lighttpd

鍵に関する次のような情報 (pin-sha256="..." フィールド) を含む行を追加すると、 lighttpd で HPKP が有効になります。

setenv.add-response-header  = ( "Public-Key-Pins" => "pin-sha256=\"base64+primary==\"; pin-sha256=\"base64+backup==\"; max-age=5184000; includeSubDomains")

注: 以下のように server.module で mod_setenv をあらかじめ読み込んでおく必要があります。

server.modules += ( "mod_setenv" )

IIS

IIS から Public-Key-Pins ヘッダーを送信するには、以下のような数行を Web.config ファイルに追加してください。

<system.webServer>
  ...

  <httpProtocol>
    <customHeaders>
      <add name="Public-Key-Pins" value="pin-sha256=&quot;base64+primary==&quot;; pin-sha256=&quot;base64+backup==&quot;; max-age=5184000; includeSubDomains" />
    </customHeaders>
  </httpProtocol>

  ...
</system.webServer>

• Public-Key-Pins
• Public-Key-Pins-Report-Only
• Browser test site: HSTS and HPKP test
• Expect-CT