777.txt

* 仕様書

[REFS[
- [5] [CITE@en[RFC 7469 - Public Key Pinning Extension for HTTP]] ([TIME[2015-05-05 21:00:37 +09:00]] 版) <https://tools.ietf.org/html/rfc7469>
]REFS]

* 呼称

[8] [CODE(HTTP)@en[[[Public-Key-Pins]]]] [[ヘッダー]]と
[CODE(HTTP)@en[[[Public-Key-Pins-Report-Only]]]] [[ヘッダー]]は、それぞれ
[DFN[[[PKP]]]]、[DFN[[[PKP-RO]]]] と省略されます [SRC[>>5]]。 

* 意味

[9] [[PKP]] と [[PKP-RO]] は、[[サーバー]]が[[利用者エージェント]]に対して当該[[ホスト]]について
[[Pin Validation]] を行うべきことを示し、そのために必要な情報を提供するものです [SRC[>>5]]。

[17] [[PKP]] と [[PKP-RO]] はそれぞれ別個に処理されるものです [SRC[>>5]]。

* 構文

[7] [[PKP]] と [[PKP-RO]] は、どちらも[[指令]]の1つ[[以上]]の列を値としなければ[['''なりません''']]。
[[指令]]間は [CODE(HTTP)[[[;]]]] で区切ります。 [CODE(HTTP)[[[;]]]]
の前後には [[OWS]] を挿入できます。 [SRC[>>5]]

[FIG(railroad)[
= [[指令]]
= *
== [[OWS]]
== [CODE(HTTP)[[[;]]]]
== [[OWS]]
== [[指令]]
]FIG]

[10] [[指令]]は、名前と値で構成されますが、値は省略できます。
値が存在する場合は、間に [CODE(HTTP)[[[=]]]] を置きます。 [SRC[>>5]]

[11] [[指令]]の名前は[[字句]]です。[[大文字・小文字不区別]]です。 [SRC[>>5]]

[12] [[指令]]の値は[[字句]]または[[引用文字列]]です。 [SRC[>>5]]

;; [23] 両構文の意味の違いや用法の制限があるのかどうかは不透明です。
[CODE(HTTP)@en[[[pin-*]]]] の構文では[[引用文字列]]であることが要求されており、
[CODE(HTTP)@en[[[max-age]]]] の規定ではどちらも等価である旨の規定があります。

[FIG(railroad)[
= [[字句]]
= ?
== [CODE(HTTP)[[[=]]]]
== |
=== [[字句]]
=== [[引用文字列]]
]FIG]

[13] [[指令]]の順序は意味を持ちません [SRC[>>5]]。

[19] 同名の[[指令]]が複数現れては[['''なりません''']] [SRC[>>5]]

* 文脈

[15] [[サーバー]]が指定できます [SRC[>>5]]。

[25] [[Pinned Host]] は、[[保安輸送路]]上の [[HTTP要求]]に対する[[応答]]では、
[[PKP]] [[ヘッダー]]をちょうど1つか、
[[PKP-RO]] [[ヘッダー]]をちょうど1つか、
その両方を含める[['''べきです''']] [SRC[>>5]]。

[26] [[Pinned Host]] は、非[[保安輸送路]]上の [[HTTP要求]]に対する[[応答]]で
[[PKP]] [[ヘッダー]]を含める[['''べきではありません''']] [SRC[>>5]]。

* 処理

[57] [[既知ピン付きホスト]]は、[[ドメイン名]]により識別します。
[[IPアドレス]]は使いません。 [SRC[>>5]]

[58] [[対象URL]]の[[ホスト]]が [[IPアドレス]]なら、
[[利用者エージェント]]はその[[ホスト]]を[[既知ピン付きホスト]]として記録しては[['''なりません''']] [SRC[>>5]]。

;; [59] [[RFC]] では [[Request-URI]] としています [SRC[>>5]] が、[[Request-URI]]
に[[ホスト]]を指定したとは限りませんから、[[対象URL]] ([[実効要求URL]])
のものを使うべきと思われます。また [[RFC]] は [[RFC 3986]] [[URI]]
を使っているので [CODE(ABNF)@en[[[IP-literal]]]] または [CODE(ABNF)@en[[[IPv4address]]]]
といっています [SRC[>>5]] が、実際の [[URL]] はそれ以外の構文で 
[[IPアドレス]]が指定されるかもしれず、その場合でも[[既知ピン付きホスト]]とするのは不適当と思われます。

[28] [[利用者エージェント]]は、[[ドメイン名]]の [[IDNA]] [[正準化]]を行わなければ[['''なりません''']] [SRC[>>5]]。

;; [29] [[RFC]] は [[HSTS]] の [[RFC]] の方法を参照しています。 [[IDNA]]
参照。

[60] [[ドメイン名]]は、[[既知HSTSドメイン名一致]]により比較します [SRC[>>5]]。

[54] [RUBYB[既知ピン付きホスト]@en[Known Pinned Host]]の[[キャッシュ]]は、次の状態を持ちます。
[FIG(list members)[
:[[ドメイン名]]:[RUBYB[ピン付きホスト]@en[Pinned Host]]の[[ドメイン名]]です [SRC[>>5]]。
:[RUBYB[実効ピン日付]@en[Effective Pin Date]]:
[[利用者エージェント]]が[[ホスト]]に関する[RUBYB[妥当なピン付けヘッダー]@en[Valid Pinning Header]]を観測した[[時刻]]です [SRC[>>5]]。
:[RUBYB[実効満期日付]@en[Effective Expiration Date]]:
[[実効ピン日付]]に [CODE(HTTP)@en[[[max-age]]]] を足したものです [SRC[>>5]]。
:[CODE(HTTP)@en[[[includeSubDomains]]]]:[CODE(HTTP)@en[[[includeSubDomains]]]]
[[指令]]が指定されたかどうかです [SRC[>>5]]。
:[CODE(HTTP)@en[[[report-uri]]]]:[CODE(HTTP)@en[[[report-uri]]]]
[[指令]]が指定された場合、その値です [SRC[>>5]]。
]FIG]

[55] [[既知ピン付きホスト]]が[RUBYB[満期]@en[expired]]であるとは、
[[実効満期日付]]が[[過去]]の[[日付]]であることをいいます [SRC[>>5]]。

[61] [[利用者エージェント]]は [CODE(HTTP)@en[[[max-age]]]] 値に上限を設けても構いません。
上限を超える値が指定された場合は、上限が指定されたものとして扱って構いません。 [SRC[>>5]]

[56] [[利用者エージェント]]は、[[キャッシュ]]中の[[満期]]の[[既知ピン付きホスト]]を無視しなければ[['''なりません''']] [SRC[>>5]]。

[62] [[超ドメイン一致]]する[[既知ピン付きホスト]]のキャッシュを編集しては[['''なりません''']] [SRC[>>5]]。

[63] [[PKP-RO]] [[ヘッダー]]の情報を[[キャッシュ]]しては[['''なりません''']] [SRC[>>5]]。



[30] [[利用者エージェント]]は、[[応答]]を次のように処理しなければ[['''なりません''']]。
[FIG(steps)[
= [27] 非[[保安輸送路]]上なら、停止します [SRC[>>5]]。
= [33] [[保安輸送路]]のエラーや警告があれば、停止します [SRC[>>5]]。
= [31] [[応答]]に [[PKP]] [[ヘッダー]]があれば、その最初のものを次の通り処理します [SRC[>>5]]。
== [14] 構文的に正しければ [SRC[>>5]]、
=== [32] 構文解析して[[指令]]のリストを得ます。
=== [16] 認識できない[[指令]]を除去します [SRC[>>5]]。
=== [38] [CODE(HTTP)@en[[[max-age]]]] に 0 が指定されているなら、
==== [39] [[Pinning Policy]] があれば、削除します [SRC[>>5]]。
=== [40] それ以外で、当該[[ホスト]]が[[Known Pinned Host]]でなければ、
==== [36] [[既知ピン付きホスト]]のキャッシュに本ホストを追加します。 [SRC[>>5]]
=== [35] それ以外なら、
==== [37] [CODE(HTTP)@en[[[max-age]]]], [CODE(HTTP)@en[[[includeSubDomains]]]],
[CODE(HTTP)@en[[[report-uri]]]] が既存の情報と異なっていれば、更新します。 [SRC[>>5]]
= [41] [[応答]]に [[PKP-RO]] [[ヘッダー]]があれば、その最初のものを次の通り処理する[['''べきです''']] [SRC[>>5]]。
== [45] 構文的に正しければ [SRC[>>5]]、
=== [42] 構文解析して[[指令]]のリストを得ます。
=== [43] 認識できない[[指令]]を除去します [SRC[>>5]]。
=== [44] [CODE(HTTP)@en[[[report-uri]]]] がなければ、無視して次へ進んで構いません [SRC[>>5]]。
==== [47] [[Pin]] と [CODE(HTTP)@en[[[max-age]]]] 以外の[[指令]]を記録に残す[['''べきです''']] [SRC[>>5]]。
]FIG]

[FIG(steps)[
= [51] [[PKP]] の記録があれば、
== [34] [[Pin Validation]] を実行します [SRC[>>5]]。
== [52] 失敗なら、
=== [53] [CODE(HTTP)@en[[[report-uri]]]] があれば、報告を [[POST]] する[['''べきです''']] [SRC[>>5]]。
= [48] [[PKP-RO]] の記録があれば、
== [49] [[Pin Validation]] を実行する[['''べきです''']] [SRC[>>5]]。
== [50] 失敗なら、
=== [46] [CODE(HTTP)@en[[[report-uri]]]] があれば、報告を [[POST]] する[['''べきです''']] [SRC[>>5]]。
]FIG]

[18] [[接続]]がその時点で当該[[ホスト]]について[[利用者エージェント]]の記録している [[Pin]]
を使った [[Pin Validation]] を通過する場合、その[[ホスト]]は[[known Pinned Host]]
となります。 [SRC[>>5]]

[21] [[利用者エージェント]]は、 [[PKP-RO]] をキャッシュしては[['''なりません''']] [SRC[>>5]]。

;; [22] ここでいう[[キャッシュ]]は [[HTTPキャッシュ]]のことではなく、
[[PKP]] としての処理のことと思われます。

[24] 報告送信については、 [CODE(HTTP)@en[[[report-uri]]]] を参照。

* 指令

[20] 次の[[指令]]があります。
[FIG(short list)[
- [CODE(HTTP)@en[[[includeSubDomains]]]]
- [CODE(HTTP)@en[[[max-age]]]]
- [CODE(HTTP)@en[[[pin-sha256]]]]
- [CODE(HTTP)@en[[[report-uri]]]]
]FIG]

* 歴史

[1] [CITE@en[draft-ietf-websec-key-pinning-11 - Public Key Pinning Extension for HTTP]]
( ([TIME[2014-02-08 10:53:37 +09:00]] 版))
<http://tools.ietf.org/html/draft-ietf-websec-key-pinning-11>

[2] [CITE@en[draft-ietf-websec-key-pinning-15 - Public Key Pinning Extension for HTTP]]
( ([TIME[2014-06-17 09:04:18 +09:00]] 版))
<http://tools.ietf.org/html/draft-ietf-websec-key-pinning-15>

[3] [CITE@en[Re: CSP: Problems with referrer and reflected-xss]]
( ([[Chris Palmer]] 著, [TIME[2014-06-17 03:33:33 +09:00]] 版))
<http://lists.w3.org/Archives/Public/public-webappsec/2014Jun/0177.html>

[4] [CITE@en[draft-ietf-websec-key-pinning-20 - Public Key Pinning Extension for HTTP]]
( ([TIME[2014-08-08 08:13:32 +09:00]] 版))
<https://tools.ietf.org/html/draft-ietf-websec-key-pinning-20>

* 関連

[6] [[HSTS]] との併用が想定されていますが、単独でも使えます [SRC[>>5]]。