idnits 2.17.1 draft-ietf-jose-jwk-thumbprint-03.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 26, 2015) is 3346 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 386 -- Looks like a reference, but probably isn't: '1' on line 386 ** 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 30, 2015 NRI 6 February 26, 2015 8 JSON Web Key (JWK) Thumbprint 9 draft-ietf-jose-jwk-thumbprint-03 11 Abstract 13 This specification defines a means of computing a thumbprint value 14 (a.k.a. digest) of a key represented as a JSON Web Key (JWK). 16 Status of this Memo 18 This Internet-Draft is submitted in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF). Note that other groups may also distribute 23 working documents as Internet-Drafts. The list of current Internet- 24 Drafts is at http://datatracker.ietf.org/drafts/current/. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 This Internet-Draft will expire on August 30, 2015. 33 Copyright Notice 35 Copyright (c) 2015 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents 40 (http://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. Code Components extracted from this document must 44 include Simplified BSD License text as described in Section 4.e of 45 the Trust Legal Provisions and are provided without warranty as 46 described in the Simplified BSD License. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 51 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3 52 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 53 3. JSON Web Key (JWK) Thumbprint . . . . . . . . . . . . . . . . 3 54 3.1. Example JWK Thumbprint Computation . . . . . . . . . . . . 4 55 3.2. JWK Members Used in the Thumbprint Computation . . . . . . 5 56 3.2.1. JWK Thumbprint of a Private Key . . . . . . . . . . . 6 57 3.2.2. Why Not Include Optional Members? . . . . . . . . . . 6 58 3.3. Order and Representation of Members in Hash Input . . . . 7 59 3.4. JWK Thumbprints of Keys Not in JWK Format . . . . . . . . 7 60 4. Practical JSON and Unicode Considerations . . . . . . . . . . 8 61 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 62 6. Security Considerations . . . . . . . . . . . . . . . . . . . 9 63 7. Relationship to Digests of X.509 Values . . . . . . . . . . . 10 64 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 10 65 8.1. Normative References . . . . . . . . . . . . . . . . . . . 10 66 8.2. Informative References . . . . . . . . . . . . . . . . . . 10 67 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 11 68 Appendix B. Document History . . . . . . . . . . . . . . . . . . 11 69 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 12 71 1. Introduction 73 This specification defines a means of computing a thumbprint value 74 (a.k.a. digest) of a key represented as a JSON Web Key (JWK). This 75 value can be used for identifying or selecting the key that is the 76 subject of the thumbprint, for instance, by using the base64url 77 encoded JWK Thumbprint value as a "kid" (key ID) value. 79 1.1. Notational Conventions 81 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 82 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 83 "OPTIONAL" in this document are to be interpreted as described in Key 84 words for use in RFCs to Indicate Requirement Levels [RFC2119]. 86 2. Terminology 88 This specification uses the same terminology as the JSON Web Key 89 (JWK) [JWK], JSON Web Signature (JWS) [JWS], and JSON Web Algorithms 90 (JWA) [JWA] specifications. 92 This term is defined by this specification: 94 JWK Thumbprint 95 The digest value for a key that is the subject of this 96 specification. 98 3. JSON Web Key (JWK) Thumbprint 100 The thumbprint of a JSON Web Key (JWK) is computed as follows: 102 1. Construct a JSON object [RFC7159] containing only the REQUIRED 103 members of a JWK representing the key and with no white space or 104 line breaks before or after any syntactic elements and with the 105 REQUIRED members ordered lexicographically by the Unicode 106 [UNICODE] code points of the member names. (This JSON object is 107 itself a legal JWK representation of the key.) 109 2. Hash the octets of the UTF-8 representation of this JSON object 110 with a cryptographic hash function H. For example, SHA-256 [SHS] 111 might be used as H. 113 The resulting value is the JWK Thumbprint with H of the JWK. The 114 details of this computation are further described in subsequent 115 sections. 117 3.1. Example JWK Thumbprint Computation 119 This section demonstrates the JWK Thumbprint computation for the JWK 120 below (with long lines broken for display purposes only): 122 { 123 "kty": "RSA", 124 "n": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx4cbbfAAt 125 VT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMstn6 126 4tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FD 127 W2QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n9 128 1CbOpbISD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINH 129 aQ-G_xBniIqbw0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw", 130 "e": "AQAB", 131 "alg": "RS256", 132 "kid": "2011-04-29" 133 } 135 As defined in JSON Web Key (JWK) [JWK] and JSON Web Algorithms (JWA) 136 [JWA], the REQUIRED members of an RSA public key are: 138 o "kty" 139 o "n" 140 o "e" 142 Therefore, these are the members used in the thumbprint computation. 144 Their lexicographic order (see more about this in Section 3.3) is: 146 o "e" 147 o "kty" 148 o "n" 150 Therefore the JSON object constructed as an intermediate step in the 151 computation is as follows (with long lines broken for display 152 purposes only): 154 {"e":"AQAB","kty":"RSA","n":"0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2 155 aiAFbWhM78LhWx4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCi 156 FV4n3oknjhMstn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65Y 157 GjQR0_FDW2QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n 158 91CbOpbISD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_x 159 BniIqbw0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw"} 161 The octets of the UTF-8 representation of this JSON object are: 163 [123, 34, 101, 34, 58, 34, 65, 81, 65, 66, 34, 44, 34, 107, 116, 121, 164 34, 58, 34, 82, 83, 65, 34, 44, 34, 110, 34, 58, 34, 48, 118, 120, 165 55, 97, 103, 111, 101, 98, 71, 99, 81, 83, 117, 117, 80, 105, 76, 74, 166 88, 90, 112, 116, 78, 57, 110, 110, 100, 114, 81, 109, 98, 88, 69, 167 112, 115, 50, 97, 105, 65, 70, 98, 87, 104, 77, 55, 56, 76, 104, 87, 168 120, 52, 99, 98, 98, 102, 65, 65, 116, 86, 84, 56, 54, 122, 119, 117, 169 49, 82, 75, 55, 97, 80, 70, 70, 120, 117, 104, 68, 82, 49, 76, 54, 170 116, 83, 111, 99, 95, 66, 74, 69, 67, 80, 101, 98, 87, 75, 82, 88, 171 106, 66, 90, 67, 105, 70, 86, 52, 110, 51, 111, 107, 110, 106, 104, 172 77, 115, 116, 110, 54, 52, 116, 90, 95, 50, 87, 45, 53, 74, 115, 71, 173 89, 52, 72, 99, 53, 110, 57, 121, 66, 88, 65, 114, 119, 108, 57, 51, 174 108, 113, 116, 55, 95, 82, 78, 53, 119, 54, 67, 102, 48, 104, 52, 81, 175 121, 81, 53, 118, 45, 54, 53, 89, 71, 106, 81, 82, 48, 95, 70, 68, 176 87, 50, 81, 118, 122, 113, 89, 51, 54, 56, 81, 81, 77, 105, 99, 65, 177 116, 97, 83, 113, 122, 115, 56, 75, 74, 90, 103, 110, 89, 98, 57, 99, 178 55, 100, 48, 122, 103, 100, 65, 90, 72, 122, 117, 54, 113, 77, 81, 179 118, 82, 76, 53, 104, 97, 106, 114, 110, 49, 110, 57, 49, 67, 98, 79, 180 112, 98, 73, 83, 68, 48, 56, 113, 78, 76, 121, 114, 100, 107, 116, 181 45, 98, 70, 84, 87, 104, 65, 73, 52, 118, 77, 81, 70, 104, 54, 87, 182 101, 90, 117, 48, 102, 77, 52, 108, 70, 100, 50, 78, 99, 82, 119, 183 114, 51, 88, 80, 107, 115, 73, 78, 72, 97, 81, 45, 71, 95, 120, 66, 184 110, 105, 73, 113, 98, 119, 48, 76, 115, 49, 106, 70, 52, 52, 45, 99, 185 115, 70, 67, 117, 114, 45, 107, 69, 103, 85, 56, 97, 119, 97, 112, 186 74, 122, 75, 110, 113, 68, 75, 103, 119, 34, 125] 188 Using SHA-256 [SHS] as the hash function H, the JWK SHA-256 189 Thumbprint value is the SHA-256 hash of these octets, specifically: 191 [55, 54, 203, 177, 120, 124, 184, 48, 156, 119, 238, 140, 55, 5, 197, 192 225, 111, 251, 158, 133, 151, 21, 144, 31, 30, 76, 89, 177, 17, 130, 193 245, 123] 195 The base64url encoding [JWS] of this JWK SHA-256 Thumbprint value 196 (which might, for instance, be used as a "kid" (key ID) value) is: 198 NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs 200 3.2. JWK Members Used in the Thumbprint Computation 202 Only the REQUIRED members of a key's representation are used when 203 computing its JWK Thumbprint value. As defined in JSON Web Key (JWK) 204 [JWK] and JSON Web Algorithms (JWA) [JWA], the REQUIRED members of an 205 elliptic curve public key for the curves specified in Section 6.2.1.1 206 of [JWK], in lexicographic order, are: 208 o "crv" 209 o "kty" 210 o "x" 211 o "y" 213 the REQUIRED members of an RSA public key, in lexicographic order, 214 are: 216 o "e" 217 o "kty" 218 o "n" 220 and the REQUIRED members of a symmetric key, in lexicographic order, 221 are: 223 o "k" 224 o "kty" 226 As other key type values are defined, the specifications defining 227 them should be similarly consulted to determine which members, in 228 addition to "kty", are REQUIRED. 230 3.2.1. JWK Thumbprint of a Private Key 232 The JWK Thumbprint of a private key is computed as the JWK Thumbprint 233 of the corresponding public key. This has the intentional benefit 234 that the same JWK Thumbprint value can be computed both by parties 235 using either the public or private key. The JWK Thumbprint can then 236 be used to refer to both keys of the key pair. Application context 237 can be used to determine whether the public or the private key is the 238 one being referred to by the JWK Thumbprint. 240 This specification defines the method of computing JWK Thumbprints of 241 private keys for interoperability reasons -- so that different 242 implementations computing JWK Thumbprints of private keys will 243 produce the same result. 245 3.2.2. Why Not Include Optional Members? 247 Optional members of JWKs are intentionally not included in the JWK 248 Thumbprint computation so that their absence or presence in the JWK 249 doesn't alter the resulting value. The JWK Thumbprint value is a 250 digest of the key value itself -- not of additional data that may 251 also accompany the key. 253 Optional members are not included so that the JWK Thumbprint refers 254 to a key -- not a key with an associated set of key attributes. This 255 has the benefit that while in different application contexts 256 different subsets of attributes about the key might or might not be 257 included in the JWK, the JWK Thumbprint of the key remains the same 258 regardless of which optional attributes are present. Different kinds 259 of thumbprints could be defined by other specifications that might 260 include some or all additional JWK members, should use cases arise 261 where such different kinds of thumbprints would be useful. See 262 Section 9.1 of [JWK] for notes on some ways to cryptographically bind 263 attributes to a key. 265 3.3. Order and Representation of Members in Hash Input 267 The required members in the input to the hash function are ordered 268 lexicographically by the Unicode code points of the member names. 270 Characters in member names and member values MUST be represented 271 without being escaped. This means that thumbprints of JWKs that 272 require such characters are not defined by this specification. (This 273 is not expected to limit the applicability of this specification, in 274 practice, as the members of JWK representations are not expected to 275 use any of these characters.) The characters specified as requiring 276 escaping by Section 7 of [RFC7159] are quotation mark, reverse 277 solidus (a.k.a. backslash), and the control characters U+0000 through 278 U+001F. 280 If the JWK key type uses members whose values are themselves JSON 281 objects (as of the time of this writing, none are defined that do), 282 the members of those objects must likewise be lexicographically 283 ordered. 285 If the JWK key type uses members whose values are JSON numbers (as of 286 the time of this writing, none are defined that do), if the numbers 287 are integers, they MUST be represented as a JSON number as defined in 288 Section 6 of [RFC7159] without including a fraction part or exponent 289 part. For instance, the value "1.024e3" MUST be represented as 290 "1024". This means that thumbprints of JWKs that use numbers that 291 are not integers are not defined by this specification. Also, as 292 noted in The I-JSON Message Format [I-D.ietf-json-i-json], 293 implementations cannot expect an integer whose absolute value is 294 greater than 9007199254740991 (i.e., that is outside the range 295 [-(2**53)+1, (2**53)-1]) to be treated as an exact value. 297 See Section 4 for a discussion of further practical considerations 298 pertaining to the representation of the hash input. 300 3.4. JWK Thumbprints of Keys Not in JWK Format 302 Note that a key need not be in JWK format to create a JWK Thumbprint 303 of it. The only prerequisites are that the JWK representation of the 304 key be defined and the party creating the JWK Thumbprint is in 305 possession of the necessary key material. These are sufficient to 306 create the hash input from the JWK representation of the key, as 307 described in Section 3.3. 309 4. Practical JSON and Unicode Considerations 311 Implementations will almost certainly use functionality provided by 312 the platform's JSON support when parsing the JWK and emitting the 313 JSON object used as the hash input. As a practical consideration, 314 future JWK member names should be avoided for which different 315 platforms or libraries might emit different representations. As of 316 the time of this writing, currently all defined JWK member names use 317 only printable ASCII characters, which should not exhibit this 318 problem. Note however, that JSON.stringify() cannot be counted on to 319 lexicographically sort the members of JSON objects, so while it may 320 be able to be used to emit some kinds of member values, different 321 code is likely to be needed to perform the sorting. 323 In particular, while the operation of lexicographically ordering 324 member names by their Unicode code points is well defined, different 325 platform sort functions may produce different results for non-ASCII 326 characters, in ways that may not be obvious to developers. If 327 writers of future specifications defining new JWK Key Type values 328 choose to restrict themselves to ASCII member names (which are for 329 machine and not human consumption anyway), some future 330 interoperability problems might be avoided. 332 However, if new JWK members are defined that use non-ASCII member 333 names, their definitions should specify the exact Unicode code point 334 sequences used to represent them, particularly in cases in which 335 Unicode normalization could result in the transformation of one set 336 of code points into another under any circumstances. 338 Use of escaped characters in the input JWK representation SHOULD be 339 avoided. 341 While there is a natural representation to use for numeric values 342 that are integers, this specification doesn't attempt to define a 343 standard representation for numbers that are not integers or that 344 contain an exponent component. This is not expected to be a problem 345 in practice, as the required members of JWK representations are not 346 expected to use numbers that are not integers. 348 Use of number representations containing fraction or exponent parts 349 in the input JWK representation SHOULD be avoided. 351 All of these practical considerations are really an instance of Jon 352 Postel's principle: "Be liberal in what you accept, and conservative 353 in what you send." 355 5. IANA Considerations 357 This specification makes no requests of IANA. 359 6. Security Considerations 361 The JSON Security Considerations and Unicode Comparison Security 362 Considerations described in Sections 10.2 and 10.3 of JSON Web 363 Signature (JWS) [JWS] also apply to this specification. 365 Also, as described in Section 4, some implementations may produce 366 incorrect results if esoteric or escaped characters are used in the 367 member names. The security implications of this appear to be limited 368 for JWK Thumbprints of public keys, since while it may result in 369 implementations failing to identify the intended key, it should not 370 leak information, since the information in a public key is already 371 public in nature, by definition. 373 A hash of a symmetric key has the potential to leak information about 374 the key value. Thus, the JWK Thumbprint of a symmetric key should be 375 typically be concealed from parties not in possession of the 376 symmetric key, unless in the application context, the cryptographic 377 hash used, such as SHA-256, is known to provide sufficient protection 378 against disclosure of the key value. 380 A JWK Thumbprint will only uniquely identify a particular key if a 381 single unambiguous JWK representation for that key is defined and 382 used when computing the JWK Thumbprint. (Such representations are 383 defined for all the key types defined in JSON Web Algorithms (JWA) 384 [JWA].) For example, if an RSA key were to use "e":"AAEAAQ" 385 (representing [0, 1, 0, 1]) rather than the specified correct 386 representation of "e":"AQAB" (representing [1, 0, 1]), a different 387 thumbprint value would be produced for what could be effectively the 388 same key, at least for implementations that are lax in validating the 389 JWK values that they accept. Thus, JWK Thumbprint values can only be 390 relied upon to be unique for a given key if the implementation also 391 validates that the correct representation of the key is used. 393 Even more insidious is that an attacker may supply a key that is a 394 transformation of a legal key in order to have it appear to be a 395 different key. For instance, if a legitimate RSA key uses a modulus 396 value N and an attacker supplies a key with modulus 3*N, the modified 397 key would still work about 1/3 of the time, but would appear to be a 398 different key. Thus, while thumbprint values are valuable for 399 identifying legitimate keys, comparing thumbprint values is not a 400 reliable means of excluding (blacklisting) the use of particular keys 401 (or transformations thereof). 403 7. Relationship to Digests of X.509 Values 405 JWK Thumbprint values are computed on the members required to 406 represent a key, rather than all members of a JWK that the key is 407 represented in. Thus, they are more analogous to applications that 408 use digests of X.509 Subject Public Key Info (SPKI) values, which are 409 defined in Section 4.1.2.7 of [RFC5280], than to applications that 410 use digests of complete certificate values, as the "x5t" (X.509 411 Certificate SHA-1 Thumbprint) [JWS] value defined for X.509 412 certificate objects does. While logically equivalent to a digest of 413 the SPKI representation of the key, a JWK Thumbprint is computed over 414 a JSON representation of that key, rather than over an ASN.1 415 representation of it. 417 8. References 419 8.1. Normative References 421 [JWA] Jones, M., "JSON Web Algorithms (JWA)", 422 draft-ietf-jose-json-web-algorithms (work in progress), 423 January 2015. 425 [JWK] Jones, M., "JSON Web Key (JWK)", 426 draft-ietf-jose-json-web-key (work in progress), 427 January 2015. 429 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 430 Signature (JWS)", draft-ietf-jose-json-web-signature (work 431 in progress), January 2015. 433 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 434 Requirement Levels", BCP 14, RFC 2119, March 1997. 436 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 437 Interchange Format", RFC 7159, March 2014. 439 [SHS] National Institute of Standards and Technology, "Secure 440 Hash Standard (SHS)", FIPS PUB 180-4, March 2012. 442 [UNICODE] The Unicode Consortium, "The Unicode Standard", 1991-, 443 . 445 8.2. Informative References 447 [I-D.ietf-json-i-json] 448 Bray, T., "The I-JSON Message Format", 449 draft-ietf-json-i-json-06 (work in progress), 450 January 2015. 452 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 453 Housley, R., and W. Polk, "Internet X.509 Public Key 454 Infrastructure Certificate and Certificate Revocation List 455 (CRL) Profile", RFC 5280, May 2008. 457 Appendix A. Acknowledgements 459 James Manger and John Bradley participated in discussions that led to 460 the creation of this specification. Jim Schaad also contributed to 461 this specification. 463 Appendix B. Document History 465 [[ to be removed by the RFC editor before publication as an RFC ]] 467 -03 469 o Addressed review comments by James Manger and Jim Schaad, 470 including adding a section on the relationship to digests of X.509 471 values. 473 -02 475 o No longer register the new JSON Web Signature (JWS) and JSON Web 476 Encryption (JWE) Header Parameters and the new JSON Web Key (JWK) 477 member name "jkt" (JWK SHA-256 Thumbprint) for holding these 478 values. 480 o Added security considerations about the measures needed to ensure 481 that a unique JWK Thumbprint value is produced for a key. 483 o Added text saying that the base64url encoded JWK Thumbprint value 484 could be used as a "kid" (key ID) value. 486 o Broke a sentence up that used to be way too long. 488 -01 490 o Addressed issues pointed out by Jim Schaad, including defining the 491 JWK Thumbprint computation in a manner that allows different hash 492 functions to be used over time. 494 o Added Nat Sakimura as an editor. 496 -00 498 o Created draft-ietf-jose-jwk-thumbprint-00 from 499 draft-jones-jose-jwk-thumbprint-01 with no normative changes. 501 Authors' Addresses 503 Michael B. Jones 504 Microsoft 506 Email: mbj@microsoft.com 507 URI: http://self-issued.info/ 509 Nat Sakimura 510 Nomura Research Institute 512 Email: n-sakimura@nri.co.jp 513 URI: http://nat.sakimura.org/