idnits 2.17.1 draft-ietf-jose-jwk-thumbprint-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (February 19, 2015) is 3347 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '0' on line 384 -- Looks like a reference, but probably isn't: '1' on line 384 ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) -- Possible downref: Non-RFC (?) normative reference: ref. 'SHS' -- Possible downref: Non-RFC (?) normative reference: ref. 'UNICODE' Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 JOSE Working Group M. Jones 3 Internet-Draft Microsoft 4 Intended status: Standards Track N. Sakimura 5 Expires: August 23, 2015 NRI 6 February 19, 2015 8 JSON Web Key (JWK) Thumbprint 9 draft-ietf-jose-jwk-thumbprint-02 11 Abstract 13 This specification defines a means of computing a thumbprint value 14 (a.k.a. digest) of JSON Web Key (JWK) objects analogous to the "x5t" 15 (X.509 Certificate SHA-1 Thumbprint) value defined for X.509 16 certificate objects. 18 Status of this Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at http://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on August 23, 2015. 35 Copyright Notice 37 Copyright (c) 2015 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 53 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3 54 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 3. JSON Web Key (JWK) Thumbprint . . . . . . . . . . . . . . . . 3 56 3.1. Example JWK Thumbprint Computation . . . . . . . . . . . . 4 57 3.2. JWK Members Used in the Thumbprint Computation . . . . . . 5 58 3.2.1. JWK Thumbprint of a Private Key . . . . . . . . . . . 6 59 3.2.2. Why Not Include Optional Members? . . . . . . . . . . 6 60 3.3. Order and Representation of Members in Hash Input . . . . 7 61 3.4. JWK Thumbprints of Keys Not in JWK Format . . . . . . . . 7 62 4. Practical JSON and Unicode Considerations . . . . . . . . . . 8 63 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 64 6. Security Considerations . . . . . . . . . . . . . . . . . . . 9 65 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 9 66 7.1. Normative References . . . . . . . . . . . . . . . . . . . 9 67 7.2. Informative References . . . . . . . . . . . . . . . . . . 10 68 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 10 69 Appendix B. Document History . . . . . . . . . . . . . . . . . . 10 70 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 11 72 1. Introduction 74 This specification defines a means of computing a thumbprint value 75 (a.k.a. digest) of JSON Web Key (JWK) [JWK] objects analogous to the 76 "x5t" (X.509 Certificate SHA-1 Thumbprint) value defined for X.509 77 certificate objects. This value can be used for identifying or 78 selecting the key that is the subject of the thumbprint, for 79 instance, by using the base64url encoded JWK Thumbprint value as a 80 "kid" (key ID) value. 82 1.1. Notational Conventions 84 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 85 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 86 "OPTIONAL" in this document are to be interpreted as described in Key 87 words for use in RFCs to Indicate Requirement Levels [RFC2119]. 89 2. Terminology 91 This specification uses the same terminology as the JSON Web Key 92 (JWK) [JWK], JSON Web Signature (JWS) [JWS], JSON Web Encryption 93 (JWE) [JWE], and JSON Web Algorithms (JWA) [JWA] specifications. 95 This term is defined by this specification: 97 JWK Thumbprint 98 The digest value for a key that is the subject of this 99 specification. 101 3. JSON Web Key (JWK) Thumbprint 103 The thumbprint of a JSON Web Key (JWK) is computed as follows: 105 1. Construct a JSON object [RFC7159] containing only the REQUIRED 106 members of a JWK representing the key and with no white space or 107 line breaks before or after any syntactic elements and with the 108 REQUIRED members ordered lexicographically by the Unicode 109 [UNICODE] code points of the member names. (This JSON object is 110 itself a legal JWK representation of the key.) 112 2. Hash the octets of the UTF-8 representation of this JSON object 113 with a cryptographic hash function H. For example, SHA-256 [SHS] 114 might be used as H. 116 The resulting value is the JWK Thumbprint with H of the JWK. The 117 details of this computation are further described in subsequent 118 sections. 120 3.1. Example JWK Thumbprint Computation 122 This section demonstrates the JWK Thumbprint computation for the JWK 123 below (with long lines broken for display purposes only): 125 { 126 "kty": "RSA", 127 "n": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx4cbbfAAt 128 VT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMstn6 129 4tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FD 130 W2QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n9 131 1CbOpbISD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINH 132 aQ-G_xBniIqbw0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw", 133 "e": "AQAB", 134 "alg": "RS256", 135 "kid": "2011-04-29" 136 } 138 As defined in JSON Web Key (JWK) [JWK] and JSON Web Algorithms (JWA) 139 [JWA], the REQUIRED members of an RSA public key are: 141 o "kty" 142 o "n" 143 o "e" 145 Therefore, these are the members used in the thumbprint computation. 147 Their lexicographic order (see more about this in Section 3.3) is: 149 o "e" 150 o "kty" 151 o "n" 153 Therefore the JSON object constructed as an intermediate step in the 154 computation is as follows (with long lines broken for display 155 purposes only): 157 {"e":"AQAB","kty":"RSA","n":"0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2 158 aiAFbWhM78LhWx4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCi 159 FV4n3oknjhMstn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65Y 160 GjQR0_FDW2QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n 161 91CbOpbISD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_x 162 BniIqbw0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw"} 164 The octets of the UTF-8 representation of this JSON object are: 166 [123, 34, 101, 34, 58, 34, 65, 81, 65, 66, 34, 44, 34, 107, 116, 121, 167 34, 58, 34, 82, 83, 65, 34, 44, 34, 110, 34, 58, 34, 48, 118, 120, 168 55, 97, 103, 111, 101, 98, 71, 99, 81, 83, 117, 117, 80, 105, 76, 74, 169 88, 90, 112, 116, 78, 57, 110, 110, 100, 114, 81, 109, 98, 88, 69, 170 112, 115, 50, 97, 105, 65, 70, 98, 87, 104, 77, 55, 56, 76, 104, 87, 171 120, 52, 99, 98, 98, 102, 65, 65, 116, 86, 84, 56, 54, 122, 119, 117, 172 49, 82, 75, 55, 97, 80, 70, 70, 120, 117, 104, 68, 82, 49, 76, 54, 173 116, 83, 111, 99, 95, 66, 74, 69, 67, 80, 101, 98, 87, 75, 82, 88, 174 106, 66, 90, 67, 105, 70, 86, 52, 110, 51, 111, 107, 110, 106, 104, 175 77, 115, 116, 110, 54, 52, 116, 90, 95, 50, 87, 45, 53, 74, 115, 71, 176 89, 52, 72, 99, 53, 110, 57, 121, 66, 88, 65, 114, 119, 108, 57, 51, 177 108, 113, 116, 55, 95, 82, 78, 53, 119, 54, 67, 102, 48, 104, 52, 81, 178 121, 81, 53, 118, 45, 54, 53, 89, 71, 106, 81, 82, 48, 95, 70, 68, 179 87, 50, 81, 118, 122, 113, 89, 51, 54, 56, 81, 81, 77, 105, 99, 65, 180 116, 97, 83, 113, 122, 115, 56, 75, 74, 90, 103, 110, 89, 98, 57, 99, 181 55, 100, 48, 122, 103, 100, 65, 90, 72, 122, 117, 54, 113, 77, 81, 182 118, 82, 76, 53, 104, 97, 106, 114, 110, 49, 110, 57, 49, 67, 98, 79, 183 112, 98, 73, 83, 68, 48, 56, 113, 78, 76, 121, 114, 100, 107, 116, 184 45, 98, 70, 84, 87, 104, 65, 73, 52, 118, 77, 81, 70, 104, 54, 87, 185 101, 90, 117, 48, 102, 77, 52, 108, 70, 100, 50, 78, 99, 82, 119, 186 114, 51, 88, 80, 107, 115, 73, 78, 72, 97, 81, 45, 71, 95, 120, 66, 187 110, 105, 73, 113, 98, 119, 48, 76, 115, 49, 106, 70, 52, 52, 45, 99, 188 115, 70, 67, 117, 114, 45, 107, 69, 103, 85, 56, 97, 119, 97, 112, 189 74, 122, 75, 110, 113, 68, 75, 103, 119, 34, 125] 191 Using SHA-256 [SHS] as the hash function H, the JWK SHA-256 192 Thumbprint value is the SHA-256 hash of these octets, specifically: 194 [55, 54, 203, 177, 120, 124, 184, 48, 156, 119, 238, 140, 55, 5, 197, 195 225, 111, 251, 158, 133, 151, 21, 144, 31, 30, 76, 89, 177, 17, 130, 196 245, 123] 198 The base64url encoding [JWS] of this JWK SHA-256 Thumbprint value 199 (which might, for instance, be used as a "kid" (key ID) value) is: 201 NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs 203 3.2. JWK Members Used in the Thumbprint Computation 205 Only the REQUIRED members of a key's representation are used when 206 computing its JWK Thumbprint value. As defined in JSON Web Key (JWK) 207 [JWK] and JSON Web Algorithms (JWA) [JWA], the REQUIRED members of an 208 elliptic curve public key for the curves specified in Section 6.2.1.1 209 of [JWK], in lexicographic order, are: 211 o "crv" 212 o "kty" 213 o "x" 214 o "y" 216 the REQUIRED members of an RSA public key, in lexicographic order, 217 are: 219 o "e" 220 o "kty" 221 o "n" 223 and the REQUIRED members of a symmetric key, in lexicographic order, 224 are: 226 o "k" 227 o "kty" 229 As other key type values are defined, the specifications defining 230 them should be similarly consulted to determine which members, in 231 addition to "kty", are REQUIRED. 233 3.2.1. JWK Thumbprint of a Private Key 235 The JWK Thumbprint of a private key is computed as the JWK Thumbprint 236 of the corresponding public key. This has the intentional benefit 237 that the same JWK Thumbprint value can be computed both by parties 238 using either the public or private key. The JWK Thumbprint can then 239 be used to refer to both keys of the key pair. Application context 240 can be used to determine whether the public or the private key is the 241 one being referred to by the JWK Thumbprint. 243 This specification defines the method of computing JWK Thumbprints of 244 private keys for interoperability reasons -- so that different 245 implementations computing JWK Thumbprints of private keys will 246 produce the same result. 248 3.2.2. Why Not Include Optional Members? 250 OPTIONAL members of JWKs are intentionally not included in the JWK 251 Thumbprint computation so that their absence or presence in the JWK 252 doesn't alter the resulting value. The JWK Thumbprint value is a 253 digest of the key value itself -- not of additional data that may 254 also accompany the key. 256 OPTIONAL members are not included so that the JWK Thumbprint refers 257 to a key -- not a key with an associated set of key attributes. This 258 has the benefit that while in different application contexts 259 different subsets of attributes about the key might or might not be 260 included in the JWK, the JWK Thumbprint of the key remains the same 261 regardless of which optional attributes are present. Different kinds 262 of thumbprints could be defined by other specifications that might 263 include some or all additional JWK members, should use cases arise 264 where such different kinds of thumbprints would be useful. See 265 Section 9.1 of [JWK] for notes on some ways to cryptographically bind 266 attributes to a key. 268 3.3. Order and Representation of Members in Hash Input 270 The REQUIRED members in the input to the hash function are ordered 271 lexicographically by the Unicode code points of the member names. 273 Characters in member names and member values MUST be represented 274 without being escaped. This means that thumbprints of JWKs that 275 require such characters are not defined by this specification. (This 276 is not expected to limit the applicability of this specification, in 277 practice, as the REQUIRED members of JWK representations are not 278 expected to use any of these characters.) The characters specified 279 as requiring escaping by Section 7 of [RFC7159] are quotation mark, 280 reverse solidus (a.k.a. backslash), and the control characters U+0000 281 through U+001F. 283 If the JWK key type uses members whose values are themselves JSON 284 objects (as of the time of this writing, none are defined that do), 285 the members of those objects must likewise be lexicographically 286 ordered. 288 If the JWK key type uses members whose values are JSON numbers (as of 289 the time of this writing, none are defined that do), if the numbers 290 are integers, they MUST be represented as a JSON number as defined in 291 Section 6 of [RFC7159] without including a fraction part or exponent 292 part. For instance, the value "1.024e3" MUST be represented as 293 "1024". This means that thumbprints of JWKs that use numbers that 294 are not integers are not defined by this specification. Also, as 295 noted in The I-JSON Message Format [I-D.ietf-json-i-json], 296 implementations cannot expect an integer whose absolute value is 297 greater than 9007199254740991 (i.e., that is outside the range 298 [-(2**53)+1, (2**53)-1]) to be treated as an exact value. 300 See Section 4 for a discussion of further practical considerations 301 pertaining to the representation of the hash input. 303 3.4. JWK Thumbprints of Keys Not in JWK Format 305 Note that a key need not be in JWK format to create a JWK Thumbprint 306 of it. The only prerequisites are that the JWK representation of the 307 key be defined and the party creating the JWK Thumbprint is in 308 possession of the necessary key material. These are sufficient to 309 create the hash input from the JWK representation of the key, as 310 described in Section 3.3. 312 4. Practical JSON and Unicode Considerations 314 Implementations will almost certainly use functionality provided by 315 the platform's JSON support, such as the JavaScript JSON.parse() 316 JSON.stringify() functions, when parsing the JWK and emitting the 317 JSON object used as the hash input. As a practical consideration, 318 future JWK member names should be avoided for which different 319 platforms or libraries might emit different representations. As of 320 the time of this writing, currently all defined JWK member names use 321 only printable ASCII characters, which should not exhibit this 322 problem. Note however, that JSON.stringify() cannot be counted on to 323 lexicographically sort the members of JSON objects, so while it may 324 be able to be used to emit some kinds of member values, different 325 code is likely to be needed to perform the sorting. 327 In particular, while the operation of lexicographically ordering 328 member names by their Unicode code points is well defined, different 329 platform sort functions may produce different results for non-ASCII 330 characters, in ways that may not be obvious to developers. If 331 writers of future specifications defining new JWK Key Type values 332 choose to restrict themselves to ASCII member names (which are for 333 machine and not human consumption anyway), some future 334 interoperability problems might be avoided. 336 Use of escaped characters in the input JWK representation SHOULD be 337 avoided. 339 While there is a natural representation to use for numeric values 340 that are integers, this specification doesn't attempt to define a 341 standard representation for numbers that are not integers or that 342 contain an exponent component. This is not expected to be a problem 343 in practice, as the REQUIRED members of JWK representations are not 344 expected to use numbers that are not integers. 346 Use of number representations containing fraction or exponent parts 347 in the input JWK representation SHOULD be avoided. 349 All of these practical considerations are really an instance of Jon 350 Postel's principle: "Be liberal in what you accept, and conservative 351 in what you send." 353 5. IANA Considerations 355 This specification makes no requests of IANA. 357 6. Security Considerations 359 The JSON Security Considerations and Unicode Comparison Security 360 Considerations described in Sections 10.2 and 10.3 of JSON Web 361 Signature (JWS) [JWS] also apply to this specification. 363 Also, as described in Section 4, some implementations may produce 364 incorrect results if esoteric or escaped characters are used in the 365 member names. The security implications of this appear to be limited 366 for JWK Thumbprints of public keys, since while it may result in 367 implementations failing to identify the intended key, it should not 368 leak information, since the information in a public key is already 369 public in nature, by definition. 371 A hash of a symmetric key has the potential to leak information about 372 the key value. Thus, the JWK Thumbprint of a symmetric key should be 373 typically be concealed from parties not in possession of the 374 symmetric key, unless in the application context, the cryptographic 375 hash used, such as SHA-256, is known to provide sufficient protection 376 against disclosure of the key value. 378 A JWK Thumbprint will only uniquely identify a particular key if a 379 single unambiguous JWK representation for that key is defined and 380 used when computing the JWK Thumbprint. (Such representations are 381 defined for all the key types defined in JSON Web Algorithms (JWA) 382 [JWA].) For example, if an RSA key were to use "e":"AAEAAQ" 383 (representing [0, 1, 0, 1]) rather than the specified correct 384 representation of "e":"AQAB" (representing [1, 0, 1]), a different 385 thumbprint value would be produced for what could be effectively the 386 same key, at least for implementations that are lax in validating the 387 JWK values that they accept. Thus, JWK Thumbprint values can only be 388 relied upon to be unique for a given key if the implementation also 389 validates that the correct representation of the key is used. 391 7. References 393 7.1. Normative References 395 [JWA] Jones, M., "JSON Web Algorithms (JWA)", 396 draft-ietf-jose-json-web-algorithms (work in progress), 397 January 2015. 399 [JWE] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 400 draft-ietf-jose-json-web-encryption (work in progress), 401 January 2015. 403 [JWK] Jones, M., "JSON Web Key (JWK)", 404 draft-ietf-jose-json-web-key (work in progress), 405 January 2015. 407 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 408 Signature (JWS)", draft-ietf-jose-json-web-signature (work 409 in progress), January 2015. 411 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 412 Requirement Levels", BCP 14, RFC 2119, March 1997. 414 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 415 Interchange Format", RFC 7159, March 2014. 417 [SHS] National Institute of Standards and Technology, "Secure 418 Hash Standard (SHS)", FIPS PUB 180-4, March 2012. 420 [UNICODE] The Unicode Consortium, "The Unicode Standard", 1991-, 421 . 423 7.2. Informative References 425 [I-D.ietf-json-i-json] 426 Bray, T., "The I-JSON Message Format", 427 draft-ietf-json-i-json-06 (work in progress), 428 January 2015. 430 Appendix A. Acknowledgements 432 James Manger and John Bradley participated in discussions that led to 433 the creation of this specification. Jim Schaad also contributed to 434 this specification. 436 Appendix B. Document History 438 [[ to be removed by the RFC editor before publication as an RFC ]] 440 -02 442 o No longer register the new JSON Web Signature (JWS) and JSON Web 443 Encryption (JWE) Header Parameters and the new JSON Web Key (JWK) 444 member name "jkt" (JWK SHA-256 Thumbprint) for holding these 445 values. 447 o Added security considerations about the measures needed to ensure 448 that a unique JWK Thumbprint value is produced for a key. 450 o Added text saying that the base64url encoded JWK Thumbprint value 451 could be used as a "kid" (key ID) value. 453 o Broke a sentence up that used to be way too long. 455 -01 457 o Addressed issues pointed out by Jim Schaad, including defining the 458 JWK Thumbprint computation in a manner that allows different hash 459 functions to be used over time. 461 o Added Nat Sakimura as an editor. 463 -00 465 o Created draft-ietf-jose-jwk-thumbprint-00 from 466 draft-jones-jose-jwk-thumbprint-01 with no normative changes. 468 Authors' Addresses 470 Michael B. Jones 471 Microsoft 473 Email: mbj@microsoft.com 474 URI: http://self-issued.info/ 476 Nat Sakimura 477 Nomura Research Institute 479 Email: n-sakimura@nri.co.jp 480 URI: http://nat.sakimura.org/