JSON Web Key (JWK) Thumbprint

Abstract

本仕様は JSON Web Key (JWK) のハッシュ値を計算する方法を定める. これには, JWK のどのフィールドをハッシュ計算に使うかや, それらのフィールドの正規化, そして正規化された Unicode 文字列をハッシュ化したバイト列に変換する方法などが含まれる. 生成されたハッシュ値は, JWK の識別のために用いたり, 複数の JWK から適切な JWK を選択する際の手掛かりとして利用できる.

Status of this Memo

This is an Internet Standards Track document.

This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 5741.

Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at http://www.rfc-editor.org/info/rfc7638.

Copyright Notice

Copyright (c) 2015 IETF Trust and the persons identified as the document authors. All rights reserved.

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.

Table of Contents

1.  Introduction
    1.1.  Notational Conventions
2.  Terminology
3.  JSON Web Key (JWK) Thumbprint
    3.1.  Example JWK Thumbprint Computation
    3.2.  JWK Members Used in the Thumbprint Computation
        3.2.1.  JWK Thumbprint of a Private Key
        3.2.2.  Why Not Include Optional Members?
    3.3.  Order and Representation of Members in Hash Input
    3.4.  Selection of Hash Function
    3.5.  JWK Thumbprints of Keys Not in JWK Format
4.  Practical JSON and Unicode Considerations
5.  Relationship to Digests of X.509 Values
6.  IANA Considerations
7.  Security Considerations
8.  References
    8.1.  Normative References
    8.2.  Informative References
    8.3.  翻訳プロジェクト
Appendix A.  Acknowledgements
Appendix B.  翻訳者
§  Authors' Addresses

1.  Introduction

本仕様は JSON Web Key (JWK) [JWK] (Jones, M., “JSON Web Key (JWK),” May 2015.) のハッシュ値 (Digest) を計算する方法を定める. これには, JWK のどのフィールドをハッシュ計算に使うかや, それらのフィールドの正規化, そして正規化された Unicode 文字列をハッシュ化したバイト列に変換する方法などが含まれる. 生成されたハッシュ値は, JWK の識別のために用いたり, 複数の JWK から適切な JWK を選択する際の手掛かりとして利用できる. 具体的には base64url-encode した JWK Thumbprint を kid (key ID) として用いるなどの方法があげられる.

1.1.  Notational Conventions

本仕様で用いられる各キーワード「MUST (しなければならない)」, 「MUST NOT (してはならない)」, 「REQUIRED (必須である)」, 「SHALL (するものとする)」, 「SHALL NOT (しないものとする)」, 「SHOULD (すべきである)」, 「SHOULD NOT (すべきではない)」, 「RECOMMENDED (推奨される)」, 「MAY (してもよい)」, 「OPTIONAL (任意である)」は [RFC2119] (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.) で述べられている通りに解釈されるべきものである.

2.  Terminology

本仕様は "JSON Web Key (JWK)" [JWK] (Jones, M., “JSON Web Key (JWK),” May 2015.), "JSON Web Signature (JWS)" [JWS] (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature (JWS),” May 2015.), "JSON Web Algorithms (JWA)" [JWA] (Jones, M., “JSON Web Algorithms (JWA),” May 2015.) の各仕様の用語定義に従う.

また本仕様は以下の用語を定義する.

JWK Thumbprint

JWK の Digest 値.

3.  JSON Web Key (JWK) Thumbprint

JSON Web Key (JWK) の Thumbprint 値の計算方法は以下通りである.

1. 必須の JWK メンバ要素のみを含み, 各要素間に一切の空白および改行を含まず, 各要素をメンバ名の Unicode [UNICODE] (The Unicode Consortium, “The Unicode Standard,” .) コードポイントの辞書順に並べた JSON Object [RFC7159] (Bray, T., Ed., “The JavaScript Object Notation (JSON) Data Interchange Format,” March 2014.) を生成する. (この JSON Object 自体も JWK 表現として valid である)
2. 上記の JSON Object の UTF-8 オクテットのハッシュ値を, ハッシュ関数 H によって計算する. H には SHA-256 [SHS] (National Institute of Standards and Technology, “Secure Hash Standard (SHS),” March 2012.) などのハッシュアルゴリズムが入る. ハッシュ関数の選定については Section 3.4 (Selection of Hash Function) を参照のこと.

上記の通り計算された値を, 当該 JWK のハッシュ関数 H による JWK Thumbprint とする. より詳細な手順は後述する.

3.1.  Example JWK Thumbprint Computation

本 Section では以下の JWK の JWK Thumbprint を計算する手順を示す. (改行やスペースは掲載上の都合による)

  {
   "kty": "RSA",
   "n": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx4cbbfAAt
         VT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMstn6
         4tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FD
         W2QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n9
         1CbOpbISD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINH
         aQ-G_xBniIqbw0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw",
   "e": "AQAB",
   "alg": "RS256",
   "kid": "2011-04-29"
  }

"JSON Web Key (JWK)" [JWK] (Jones, M., “JSON Web Key (JWK),” May 2015.) および "JSON Web Algorithms (JWA)" [JWA] (Jones, M., “JSON Web Algorithms (JWA),” May 2015.) に定めるように, RSA 公開鍵の必須要素は以下のとおりである.

• kty
• n
• e

従って, これらが Thumbprint 計算に使われるメンバ要素となる.

これを Section 3.3 (Order and Representation of Members in Hash Input) に従い辞書順に並べると, 以下の通りとなる.

• e
• kty
• n

よってまず以下のような JSON Object を生成することとなる. (改行は掲載上の都合による)

  {"e":"AQAB","kty":"RSA","n":"0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2
  aiAFbWhM78LhWx4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCi
  FV4n3oknjhMstn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65Y
  GjQR0_FDW2QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n
  91CbOpbISD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_x
  BniIqbw0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw"}

上記の JSON Object を UTF-8 オクテット表現したものを以下に示す.

[123, 34, 101, 34, 58, 34, 65, 81, 65, 66, 34, 44, 34, 107, 116, 121, 34, 58, 34, 82, 83, 65, 34, 44, 34, 110, 34, 58, 34, 48, 118, 120, 55, 97, 103, 111, 101, 98, 71, 99, 81, 83, 117, 117, 80, 105, 76, 74, 88, 90, 112, 116, 78, 57, 110, 110, 100, 114, 81, 109, 98, 88, 69, 112, 115, 50, 97, 105, 65, 70, 98, 87, 104, 77, 55, 56, 76, 104, 87, 120, 52, 99, 98, 98, 102, 65, 65, 116, 86, 84, 56, 54, 122, 119, 117, 49, 82, 75, 55, 97, 80, 70, 70, 120, 117, 104, 68, 82, 49, 76, 54, 116, 83, 111, 99, 95, 66, 74, 69, 67, 80, 101, 98, 87, 75, 82, 88, 106, 66, 90, 67, 105, 70, 86, 52, 110, 51, 111, 107, 110, 106, 104, 77, 115, 116, 110, 54, 52, 116, 90, 95, 50, 87, 45, 53, 74, 115, 71, 89, 52, 72, 99, 53, 110, 57, 121, 66, 88, 65, 114, 119, 108, 57, 51, 108, 113, 116, 55, 95, 82, 78, 53, 119, 54, 67, 102, 48, 104, 52, 81, 121, 81, 53, 118, 45, 54, 53, 89, 71, 106, 81, 82, 48, 95, 70, 68, 87, 50, 81, 118, 122, 113, 89, 51, 54, 56, 81, 81, 77, 105, 99, 65, 116, 97, 83, 113, 122, 115, 56, 75, 74, 90, 103, 110, 89, 98, 57, 99, 55, 100, 48, 122, 103, 100, 65, 90, 72, 122, 117, 54, 113, 77, 81, 118, 82, 76, 53, 104, 97, 106, 114, 110, 49, 110, 57, 49, 67, 98, 79, 112, 98, 73, 83, 68, 48, 56, 113, 78, 76, 121, 114, 100, 107, 116, 45, 98, 70, 84, 87, 104, 65, 73, 52, 118, 77, 81, 70, 104, 54, 87, 101, 90, 117, 48, 102, 77, 52, 108, 70, 100, 50, 78, 99, 82, 119, 114, 51, 88, 80, 107, 115, 73, 78, 72, 97, 81, 45, 71, 95, 120, 66, 110, 105, 73, 113, 98, 119, 48, 76, 115, 49, 106, 70, 52, 52, 45, 99, 115, 70, 67, 117, 114, 45, 107, 69, 103, 85, 56, 97, 119, 97, 112, 74, 122, 75, 110, 113, 68, 75, 103, 119, 34, 125]

この入力に対して SHA-256 [SHS] (National Institute of Standards and Technology, “Secure Hash Standard (SHS),” March 2012.) をハッシュ関数 H を適用し, JWK SHA-256 Thumbprint 値を計算すると, 以下のようなオクテットとなる.

[55, 54, 203, 177, 120, 124, 184, 48, 156, 119, 238, 140, 55, 5, 197, 225, 111, 251, 158, 133, 151, 21, 144, 31, 30, 76, 89, 177, 17, 130, 245, 123]

この JWK SHA-256 Thumbprint の base64url encoding [JWS] (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature (JWS),” May 2015.) は以下の通りである. (この base64url encode 値は kid (key ID) などに用いられる)

  NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs

3.2.  JWK Members Used in the Thumbprint Computation

JWK Thumbprint の計算には各鍵の必須メンバ要素のみを用いる. "JSON Web Key (JWK)" [JWK] (Jones, M., “JSON Web Key (JWK),” May 2015.) および "JSON Web Algorithms (JWA)" [JWA] (Jones, M., “JSON Web Algorithms (JWA),” May 2015.) に定めるように, RFC 7518 [JWA] (Jones, M., “JSON Web Algorithms (JWA),” May 2015.) の Section 6.2.1.1 に定められた曲線に対する EC 公開鍵の必須メンバは, 辞書順にすると以下の通りである.

• crv
• kty
• x
• y

同様に RSA 鍵についての必須要素は辞書順に以下の通りである.

• e
• kty
• n

公開鍵についても以下の通りである.

• k
• kty

これ以外の kty (key type) を定義する場合は, その定義を行う仕様が kty の他にどのメンバ要素を必須とするかを定めるべきである.

3.2.1.  JWK Thumbprint of a Private Key

秘密鍵を表現する JWK の JWK Thumbprint は, その秘密鍵とペアとなる公開鍵を表現する JWK の JWK Thumbprint とする. これは意図的にペアとなる2つの鍵に同じ JWK Thumbprint を持たせ, それぞれの鍵を持つ2者が同じ JWK Thumbprint を計算できるようにということを狙ったものである. これにより, JWK Thumbprint はペアとなるどちらの鍵をも指し示すことができる. 当該鍵が公開鍵なのか秘密鍵なのかの判定は, Application のコンテキストによって行うこと.

本仕様は秘密鍵の JWK Thumbprint 計算方法を相互接続性を持つ形で定義した. よって異なる実装が同じ秘密鍵の JWK Thumbprint を導出できるはずである.

3.2.2.  Why Not Include Optional Members?

オプショナルなメンバ要素はあえて JWK Thumbprint 計算対象としていない. これはオプショナルなメンバ要素の有無で同じ鍵の JWK Thumbprint が変わることのないように意図したものである. JWK Thumbprint は JWK の必須メンバの Digest であり, その他の付加的メンバの Digest ではないのである.

オプショナルメンバが計算対象に含まれないことで, JWK Thumbprint はその鍵そのものの参照となる. アプリケーションコンテキストが変わり, オプショナルな属性が JWK に付与されたとしても, その鍵の JWK Thumbprint は不変である. これは鍵そのものを一意に識別するという目的のために役立つ.

ユースケースによっては, 付加的な JWK メンバの一部もしくは全部を含んだ異なる種類の Thumbprint が有用なこともある. そういった Thumbprint が必要になれば, 本仕様以外の仕様が定めることとする. 付加属性を暗号論的に鍵に紐付ける方法については, RFC 7517 [JWK] (Jones, M., “JSON Web Key (JWK),” May 2015.) の Section 9.1 を参照のこと.

3.3.  Order and Representation of Members in Hash Input

ハッシュ関数の入力値となる必須メンバは, メンバ名の Unicode コードポイントの辞書順に並べられる.

メンバ名およびメンバ値に含まれる文字列は, エスケープなしで表現されていなければならない (MUST). そのようなエスケープが必要な文字を含む JWK の Thumbprint については, 本仕様では定義しない. (JWK は Unicode のみで表現されると期待されることから, これは特に本仕様の有用性を下げるものではないと思われる) [RFC7159] (Bray, T., Ed., “The JavaScript Object Notation (JSON) Data Interchange Format,” March 2014.) Section 7 にあるように, エスケープが必要な文字は, クォーテーションマークやバックスラッシュ, U+0000 や U+001F などのコントロール文字などである.

もしメンバ値が JSON Object となるような Key Type が出てきた場合には, その JSON Object 内のメンバについても辞書順とすること (MUST). (本仕様執筆段階ではメンバ値が JSON Object となるような Key Type は存在しない)

もしメンバ値が JSON Number となるような Key Type が出てきた場合には, 値が Integer の場合には [RFC7159] (Bray, T., Ed., “The JavaScript Object Notation (JSON) Data Interchange Format,” March 2014.) Section 6 に従い, 少数部や指数部を持たない形で表現すること (MUST). 例えば 1.024e3 は 1024 と表記すること (MUST). また値が Integer 以外の場合については本仕様では定義しない. また "The I-JSON Message Format" [RFC7493] (Bray, T., Ed., “The I-JSON Message Format,” March 2015.) に述べられているように, 実装は絶対値が 9007199254740991 ([-(2**53)+1, (2**53)-1] の範囲外) の Integer をその値通りに扱えるとは期待できない. (本仕様執筆段階ではメンバ値が JSON Number となるような Key Type は存在しない)

ハッシュ入力の表現方法に関するより詳細な記述は Section 4 (Practical JSON and Unicode Considerations) を参照のこと.

3.4.  Selection of Hash Function

アプリケーションは特定のハッシュ関数を指定しなければならない. 候補としては SHA-256 [SHS] (National Institute of Standards and Technology, “Secure Hash Standard (SHS),” March 2012.) などがあげられる. SHA-256 は本仕様執筆段階ではデフォルトとして良い選択であるが, 将来に渡ってそうとは限らない.

多くの場合, 鍵生成を行う主体のみ, 利用すべきハッシュ関数を知る必要がある. kid (key ID) の生成などはその典型的な例である. 鍵生成者は kid の計算にハッシュ関数を知る必要があるが, 鍵を受け取る側にとっては kid は単なる opaque 値であり, ハッシュ関数を知る必要はない.

しかしながら, 複数の主体が JWK Thumbprint を計算する必要がある場合もある. その場合には両主体が同じハッシュ関数を使う必要がある.

3.5.  JWK Thumbprints of Keys Not in JWK Format

JWK Thumbprint の計算のために, JWK 表現された鍵を使う必要はない. 必要なのは, 当該鍵の JWK 表現方法が定義されていることと, JWK Thumbprint を計算する主体が必要な鍵要素を保持していることのみである. それが揃っていれば, Section 3.3 (Order and Representation of Members in Hash Input) にしたがって当該鍵の JWK 表現を生成しハッシュ入力とすることができる.

4.  Practical JSON and Unicode Considerations

ほとんどの場合, JWK のパースや JSON Object の生成などを行う際は, プラットフォームが提供する JSON ライブラリ等を利用することになるであろう. よって将来的に JWK メンバ名と値が異なるプラットフォーム上で異なる表現とならないよう, メンバ名と値の設計に考慮するべきである. 本仕様執筆時点では, 定義済 JWK メンバ名および値は印刷可能な ASCII 文字列に限定されており, 上記のような問題は起き得ない. しかしながら JSON.stringify() は JSON Object のメンバの辞書順ソートを保証しない. よってソート順の異なる出力が生成される可能性がある.

特に Unicode コードポイントの辞書順ソートオペレーションは注意深く定義されているが, 異なるプラットフォームのソート関数は非 ASCII 文字に対して異なる結果を出力しうる. もし将来の仕様策定者が新たな Key Type を定義する場合, メンバ名と値を印刷可能 ASCII 文字に限定できるのであれば, 相互接続性に役立つであろう.

しかしながら, もし非 ASCII 文字を含む新たな JWK メンバ名および値が定義された場合は, それらの仕様は厳密に Unicode コードポイントを使うよう指定すべきである. これは, Unicode 正規化によってある条件であるコードポイントが他の値に転換されるような場合に, 特に重要となる.

JWK Thumbprint の計算対象となる JWK の中では, エスケープ文字の利用は避けるべきである. 元の JWK から導出されるハッシュ入力となる JWK にエスケープ文字を含めることは禁止する.

Integer の自然表現は存在するが, 本仕様は Integer 以外の Numeric 値の標準表現形式は定めない. 通常 JWK の必須メンバは Integer のみになると思われるため, これは問題とならないであろう.

JWK Thumbprint の計算対象となる JWK の中では, 少数部や指数部を持つ数値表現の利用は避けるべきである.

上記のすべての実践的考慮点は, Jon Postel の原則である "Be liberal in what you accept, and conservative in what you send." による.

5.  Relationship to Digests of X.509 Values

JWK Thumbprint は JWK に含まれる全メンバに対してでなく, JWK の必須メンバに対して計算される. これは, X.509 証明書に対する [JWS] (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature (JWS),” May 2015.) の x5t (X.509 certificate SHA-1 thumbprint) よりも, [RFC5280] (Cooper, D., Santesson, S., Farrell, S., Boeyen, S., Housley, R., and W. Polk, “Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile,” May 2008.) Section 4.1.2.7 の X.509 Subject Public Key Info (SPKI) Digest 値に似ている. ただし ASN.1 表現に対して計算される SPKI と JSON 表現に対して計算される JWK Thumbprint は, 論理的には似ていても異なる値となる.

6.  IANA Considerations

本仕様は以下の IANA レジストリに Designated Experts 向け注記を追加する. これらはすべて "JSON Object Signing and Encryption (JOSE)" レジストリ内にある. [IANA.JOSE] (IANA, “JSON Object Signing and Encryption (JOSE),” .):

• JSON Web Key Types
• JSON Web Key Elliptic Curve
• JSON Web Key Parameters

IANA は上記レジストリの Reference Section に本仕様へのリンクを追加済である.

Section 4 (Practical JSON and Unicode Considerations) で述べたように, JSON と Unicode の実用上の注意点を考慮して, Designated Experts は以下のいずれかに従わなければならない.

(a) JWK メンバ名と値を, ダブルクォート ('"') とバックスラッシュ ('\') を除いた印刷可能 ASCII 文字に制限する. (Unicode コードポインタでいうと, U+0021, U+0023 から U+005B, および U+005D から U+007E)

(b) もし (a) 以外のコードポインタを利用する場合は, それらを表現する Unicode コードポイントを厳密に指定すること. さらに JSON 文字列中でエスケープされた文字としてしか表現できない Unicode コードポイントを利用するようなものは, レジストリへの登録を拒否されなければならない.

7.  Security Considerations

"JSON Web Signature (JWS)" [JWS] (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature (JWS),” May 2015.) Section 10.12 および 10.13 にある JSON Security Considerations および Unicode Comparison Security Considerations は本仕様にも該当する.

また Section 4 (Practical JSON and Unicode Considerations) で述べたように, 難解な文字やエスケープされた文字がメンバ名に利用されている場合, 実装によっては不正な結果を出力することもありうる. これはセキュリティ上は公開鍵の JWK Thumbprint にしか影響しないと思われる. 実装は意図した鍵を識別することができないかもしれないが, 情報漏洩などはないであろう. 公開鍵の各要素は, そもそも公開されているものである.

対象鍵のハッシュはその鍵値に関する情報を漏洩しうる. したがって対象鍵の JWK Thumbprint は対象鍵を所有する主体以外に対しては秘匿されるべきである. ただし, アプリケーションコンテキストによっては, SHA-256 のような暗号論的ハッシュ関数の利用によって鍵値漏洩に対する十分な保護が期待できる場合は, この限りでは無い.

JWK Thumbprint は明確に単一の JWK 表現方法が確立されている場合のみ, 特定の鍵をユニークに識別することができる. ("JSON Web Algorithms (JWA)" [JWA] (Jones, M., “JSON Web Algorithms (JWA),” May 2015.) が定める Key Type にはすべてそのような表現方法が定められている) 例えば, ある RSA 鍵が "e":"AQAB" ([1, 0, 1] を示す) ではなく "e":"AAEAAQ" ([0, 1, 0, 1] を示す) を用いる場合, 実際には等価な鍵に対して異なる Thumbprint が生成される. (受け取った JWK を厳密に Validate している実装では, 上記の問題が発生しないこともありうる) したがってある鍵の JWK Thumbprint がユニークであるという前提は, 実装がその鍵の正しい表現を Validate していることが前提である.

より狡猾な攻撃としては, 攻撃者が正規の鍵を異なる鍵と見せかけるよう変換することなどが考えられる. 例えば, 正規の RSA 鍵が modules N である時に, 攻撃者が modulus 3*N の鍵を送ってきたとしよう. すると後者の鍵は 1/3 程の時間は有効に働くが, 異なる鍵に見える. よって Thumbprint は正規の鍵を識別するには役に立つが, Thumbprint を比較したからといって特定の鍵を排除する (ブラックリストに入れる) ような目的には有用ではない.

8.  References

8.1. Normative References

8.2. Informative References

8.3. 翻訳プロジェクト

Appendix A.  Acknowledgements

James Manger and John Bradley participated in discussions that led to the creation of this specification. Thanks also to Joel Halpern, Barry Leiba, Adam Montville, Kathleen Moriarty, and Jim Schaad for their reviews of this specification.

Appendix B.  翻訳者

本仕様の翻訳は, OpenIDファウンデーションジャパン (OpenIDファウンデーションジャパン, “OpenIDファウンデーションジャパン,” .) [oidfj] 翻訳・教育ワーキンググループ (OpenIDファウンデーションジャパン, “翻訳・教育ワーキンググループ,” .) [oidfj‑trans]を主体として, 有志のメンバーによって行われました. 質問や修正依頼などについては, Githubレポジトリー (OpenIDファウンデーションジャパン, “Githubレポジトリー,” .) [oidfj‑github] にご連絡ください.

• Nov Matake (YAuth.jp)

Authors' Addresses