idnits 2.17.1 draft-ietf-jose-jwk-thumbprint-00.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 (November 10, 2014) is 3454 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) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 1 comment (--). 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 November 10, 2014 5 Expires: May 14, 2015 7 JSON Web Key (JWK) Thumbprint 8 draft-ietf-jose-jwk-thumbprint-00 10 Abstract 12 This specification defines a means of computing a thumbprint value 13 (a.k.a. digest) of JSON Web Key (JWK) objects analogous to the "x5t" 14 (X.509 Certificate SHA-1 Thumbprint) value defined for X.509 15 certificate objects. This specification also registers the new JSON 16 Web Signature (JWS) and JSON Web Encryption (JWE) Header Parameters 17 and the new JSON Web Key (JWK) member name "jkt" (JWK SHA-256 18 Thumbprint) for holding these values. 20 Status of this Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on May 14, 2015. 37 Copyright Notice 39 Copyright (c) 2014 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3 56 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 3. JSON Web Key (JWK) Thumbprint . . . . . . . . . . . . . . . . 3 58 3.1. Example JWK Thumbprint Computation . . . . . . . . . . . . 4 59 3.2. JWK Members Used in the Thumbprint Computation . . . . . . 5 60 3.2.1. JWK Thumbprint of a Private Key . . . . . . . . . . . 6 61 3.2.2. Why Not Include Optional Members? . . . . . . . . . . 6 62 3.3. Order and Representation of Members in Hash Input . . . . 6 63 3.4. JWK Thumbprints of Any Keys . . . . . . . . . . . . . . . 7 64 4. "jkt" Member Definitions . . . . . . . . . . . . . . . . . . . 7 65 4.1. "jkt" (JWK SHA-256 Thumbprint) JWS Header Parameter . . . 7 66 4.2. "jkt" (JWK SHA-256 Thumbprint) JWE Header Parameter . . . 7 67 4.3. "jkt" (JWK SHA-256 Thumbprint) JWK Parameter . . . . . . . 8 68 4.4. Possible Future Alternative Thumbprint Computations . . . 8 69 5. Practical JSON and Unicode Considerations . . . . . . . . . . 8 70 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 71 6.1. JWS and JWE Header Parameter Registration . . . . . . . . 9 72 6.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 9 73 6.2. JSON Web Key Parameters Registration . . . . . . . . . . . 9 74 6.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 9 75 7. Security Considerations . . . . . . . . . . . . . . . . . . . 10 76 8. Normative References . . . . . . . . . . . . . . . . . . . . . 10 77 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 10 78 Appendix B. Document History . . . . . . . . . . . . . . . . . . 11 79 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 11 81 1. Introduction 83 This specification defines a means of computing a thumbprint value 84 (a.k.a. digest) of JSON Web Key (JWK) [JWK] objects analogous to the 85 "x5t" (X.509 Certificate SHA-1 Thumbprint) value defined for X.509 86 certificate objects. This specification also registers the new JSON 87 Web Signature (JWS) [JWS] and JSON Web Encryption (JWE) [JWE] Header 88 Parameters and the new JSON Web Key (JWK) [JWK] member name "jkt" 89 (JWK SHA-256 Thumbprint) for holding these values. 91 1.1. Notational Conventions 93 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 94 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 95 "OPTIONAL" in this document are to be interpreted as described in Key 96 words for use in RFCs to Indicate Requirement Levels [RFC2119]. 98 2. Terminology 100 This specification uses the same terminology as the JSON Web Key 101 (JWK) [JWK], JSON Web Signature (JWS) [JWS], JSON Web Encryption 102 (JWE) [JWE], and JSON Web Algorithms (JWA) [JWA] specifications. 104 This term is defined by this specification: 106 JWK Thumbprint 107 The digest value for a key that is the subject of this 108 specification. 110 3. JSON Web Key (JWK) Thumbprint 112 This specification defines the thumbprint of a JSON Web Key (JWK) 113 value as being a function of the REQUIRED members of the key's JWK 114 representation. Specifically, this function is the SHA-256 hash of 115 the octets of the UTF-8 representation of a JSON object [RFC7159] 116 constructed containing only the REQUIRED members of a JWK 117 representing the key and with no white space or line breaks before or 118 after any syntactic elements and with the REQUIRED members ordered 119 lexicographically by the Unicode code points of the member names. 120 This JSON object is itself a legal JWK representation of the key 121 value. The details of this computation are further described in 122 subsequent sections. 124 3.1. Example JWK Thumbprint Computation 126 This section demonstrates the JWK Thumbprint computation for the JWK 127 below (with long lines broken for display purposes only): 129 { 130 "kty": "RSA", 131 "n": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx4cbbfAAt 132 VT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMstn6 133 4tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FD 134 W2QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n9 135 1CbOpbISD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINH 136 aQ-G_xBniIqbw0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw", 137 "e": "AQAB", 138 "alg": "RS256", 139 "kid": "2011-04-29" 140 } 142 As defined in JSON Web Key (JWK) [JWK] and JSON Web Algorithms (JWA) 143 [JWA], the REQUIRED members of an RSA public key are: 145 o "kty" 146 o "n" 147 o "e" 149 Therefore, these are the members used in the thumbprint computation. 151 Their lexicographic order (see more about this in Section 3.3) is: 153 o "e" 154 o "kty" 155 o "n" 157 Therefore the JSON object constructed as an intermediate step in the 158 computation is as follows (with long lines broken for display 159 purposes only): 161 {"e":"AQAB","kty":"RSA","n":"0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2 162 aiAFbWhM78LhWx4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCi 163 FV4n3oknjhMstn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65Y 164 GjQR0_FDW2QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n 165 91CbOpbISD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_x 166 BniIqbw0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw"} 168 The octets of the UTF-8 representation of this JSON object are: 170 [123, 34, 101, 34, 58, 34, 65, 81, 65, 66, 34, 44, 34, 107, 116, 121, 171 34, 58, 34, 82, 83, 65, 34, 44, 34, 110, 34, 58, 34, 48, 118, 120, 172 55, 97, 103, 111, 101, 98, 71, 99, 81, 83, 117, 117, 80, 105, 76, 74, 173 88, 90, 112, 116, 78, 57, 110, 110, 100, 114, 81, 109, 98, 88, 69, 174 112, 115, 50, 97, 105, 65, 70, 98, 87, 104, 77, 55, 56, 76, 104, 87, 175 120, 52, 99, 98, 98, 102, 65, 65, 116, 86, 84, 56, 54, 122, 119, 117, 176 49, 82, 75, 55, 97, 80, 70, 70, 120, 117, 104, 68, 82, 49, 76, 54, 177 116, 83, 111, 99, 95, 66, 74, 69, 67, 80, 101, 98, 87, 75, 82, 88, 178 106, 66, 90, 67, 105, 70, 86, 52, 110, 51, 111, 107, 110, 106, 104, 179 77, 115, 116, 110, 54, 52, 116, 90, 95, 50, 87, 45, 53, 74, 115, 71, 180 89, 52, 72, 99, 53, 110, 57, 121, 66, 88, 65, 114, 119, 108, 57, 51, 181 108, 113, 116, 55, 95, 82, 78, 53, 119, 54, 67, 102, 48, 104, 52, 81, 182 121, 81, 53, 118, 45, 54, 53, 89, 71, 106, 81, 82, 48, 95, 70, 68, 183 87, 50, 81, 118, 122, 113, 89, 51, 54, 56, 81, 81, 77, 105, 99, 65, 184 116, 97, 83, 113, 122, 115, 56, 75, 74, 90, 103, 110, 89, 98, 57, 99, 185 55, 100, 48, 122, 103, 100, 65, 90, 72, 122, 117, 54, 113, 77, 81, 186 118, 82, 76, 53, 104, 97, 106, 114, 110, 49, 110, 57, 49, 67, 98, 79, 187 112, 98, 73, 83, 68, 48, 56, 113, 78, 76, 121, 114, 100, 107, 116, 188 45, 98, 70, 84, 87, 104, 65, 73, 52, 118, 77, 81, 70, 104, 54, 87, 189 101, 90, 117, 48, 102, 77, 52, 108, 70, 100, 50, 78, 99, 82, 119, 190 114, 51, 88, 80, 107, 115, 73, 78, 72, 97, 81, 45, 71, 95, 120, 66, 191 110, 105, 73, 113, 98, 119, 48, 76, 115, 49, 106, 70, 52, 52, 45, 99, 192 115, 70, 67, 117, 114, 45, 107, 69, 103, 85, 56, 97, 119, 97, 112, 193 74, 122, 75, 110, 113, 68, 75, 103, 119, 34, 125] 195 The JWK Thumbprint value is the SHA-256 hash of these octets, 196 specifically: 198 [55, 54, 203, 177, 120, 124, 184, 48, 156, 119, 238, 140, 55, 5, 197, 199 225, 111, 251, 158, 133, 151, 21, 144, 31, 30, 76, 89, 177, 17, 130, 200 245, 123] 202 The base64url encoding of this JWK Thumbprint value (which would be 203 used in the "jkt" members registered below) is: 205 NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs 207 3.2. JWK Members Used in the Thumbprint Computation 209 Only the REQUIRED members of a key's representation are used when 210 computing its JWK Thumbprint value. As defined in JSON Web Key (JWK) 211 [JWK] and JSON Web Algorithms (JWA) [JWA], the REQUIRED members of an 212 elliptic curve public key, in lexicographic order, are: 214 o "crv" 215 o "kty" 216 o "x" 217 o "y" 219 the REQUIRED members of an RSA public key, in lexicographic order, 220 are: 222 o "e" 223 o "kty" 224 o "n" 226 and the REQUIRED members of a symmetric key, in lexicographic order, 227 are: 229 o "k" 230 o "kty" 232 As other key type values are defined, the specifications defining 233 them should be similarly consulted to determine which members, in 234 addition to "kty", are REQUIRED. 236 3.2.1. JWK Thumbprint of a Private Key 238 The JWK Thumbprint of a private key is computed as the JWK Thumbprint 239 of the corresponding public key. This has the intentional benefit 240 that the same JWK Thumbprint value can be computed both by parties 241 using either the public or private key. The JWK Thumbprint can then 242 be used to refer to both keys of the key pair. Application context 243 can be used to determine whether the public or the private key is the 244 one being referred to by the JWK Thumbprint. 246 3.2.2. Why Not Include Optional Members? 248 OPTIONAL members of JWKs are intentionally not included in the JWK 249 Thumbprint computation so that their absence or presence in the JWK 250 doesn't alter the resulting value. The JWK Thumbprint value is a 251 digest of the key value itself -- not of additional data that may 252 also accompany the key. 254 3.3. Order and Representation of Members in Hash Input 256 The REQUIRED members in the input to the SHA-256 hash function are 257 ordered lexicographically by the Unicode code points of the member 258 names. 260 Characters in member names and member values MUST be represented 261 without being escaped. This means that thumbprints of JWK values 262 that require such characters are not defined by this specification. 263 (This is not expected to limit the applicability of this 264 specification, in practice, as the REQUIRED members of JWK 265 representations are not expected to use any of these characters.) 266 The characters specified as requiring escaping by Section 7 of 267 [RFC7159] are quotation mark, reverse solidus (a.k.a. backslash), and 268 the control characters U+0000 through U+001F. 270 If the JWK key type uses members whose values are themselves JSON 271 objects (as of the time of this writing, none are defined that do), 272 the members of those objects must likewise be lexicographically 273 ordered. 275 If the JWK key type uses members whose values are JSON numbers (as of 276 the time of this writing, none are defined that do), if the numbers 277 are integers, they MUST be represented as a JSON number as defined in 278 Section 6 of [RFC7159] without including a fraction part or exponent 279 part. For instance, the value "1.024e3" MUST be represented as 280 "1024". This means that thumbprints of JWK values that use numbers 281 that are not integers are not defined by this specification. 283 See Section 5 for a discussion of further practical considerations 284 pertaining to the representation of the hash input. 286 3.4. JWK Thumbprints of Any Keys 288 Note that a key need not be in JWK format to create a JWK Thumbprint 289 of it. The only prerequisites are that the JWK representation of the 290 key be defined and the party creating the JWK Thumbprint is in 291 possession of the necessary key material. These are sufficient to 292 create the hash input, as described in Section 3.3. 294 4. "jkt" Member Definitions 296 This section defines "jkt" (JWK SHA-256 Thumbprint) members used for 297 holding base64url encoded JWK Thumbprint values in JWK, JWS, and JWE 298 objects. 300 4.1. "jkt" (JWK SHA-256 Thumbprint) JWS Header Parameter 302 The "jkt" (JWK SHA-256 Thumbprint) JWS Header Parameter is a 303 base64url encoded JWK Thumbprint (a.k.a. digest) of the public key 304 that corresponds to the key used to digitally sign the JWS. Use of 305 this JWS Header Parameter is OPTIONAL. 307 4.2. "jkt" (JWK SHA-256 Thumbprint) JWE Header Parameter 309 This parameter has the same meaning, syntax, and processing rules as 310 the "jkt" JWS Header Parameter defined in Section 4.1, except that 311 the JWK Thumbprint references the public key to which the JWE was 312 encrypted; this can be used to determine the private key needed to 313 decrypt the JWE. 315 4.3. "jkt" (JWK SHA-256 Thumbprint) JWK Parameter 317 The "jkt" (JWK SHA-256 Thumbprint) JWK parameter is a base64url 318 encoded JWK Thumbprint (a.k.a. digest) of the JWK. If present, the 319 JWK Thumbprint value represented MUST have been computed from the 320 other members of the JWK as described in Section 3. Use of this 321 member is OPTIONAL. 323 4.4. Possible Future Alternative Thumbprint Computations 325 If, in the future, JWK Thumbprints need to be computed using hash 326 functions other than SHA-256, it is suggested that additional related 327 JWK, JWS, and JWE parameters be defined for that purpose. For 328 example, it is suggested that a new "jkt#S3-256" (X.509 Certificate 329 Thumbprint using SHA-3-256) JWK parameter could be defined by 330 registering it in the IANA JSON Web Key Parameters registry and the 331 IANA JSON Web Signature and Encryption Header Parameters registry. 333 5. Practical JSON and Unicode Considerations 335 Implementations will almost certainly use functionality provided by 336 the platform's JSON support, such as the JavaScript JSON.parse() 337 JSON.stringify() functions, when parsing the JWK and emitting the 338 JSON object used as the SHA-256 hash input. As a practical 339 consideration, future JWK member names should be avoided for which 340 different platforms or libraries might emit different 341 representations. As of the time of this writing, currently all 342 defined JWK member names use only printable ASCII characters, which 343 should not exhibit this problem. 345 In particular, while the operation of lexicographically ordering 346 member names by their Unicode code points is well defined, different 347 platform sort functions may produce different results for non-ASCII 348 characters, in ways that may not be obvious to developers. If 349 writers of future specifications defining new JWK Key Type values 350 choose to restrict themselves to ASCII member names (which are for 351 machine and not human consumption anyway), some future 352 interoperability problems might be avoided. 354 Use of escaped characters in the input JWK representation should be 355 avoided. 357 While there is a natural representation to use for numeric values 358 that are integers, this specification doesn't attempt to define a 359 standard representation for numbers that are not integers or that 360 contain an exponent component. This is not expected to be a problem 361 in practice, as the REQUIRED members of JWK representations are not 362 expected to use numbers that are not integers. 364 Use of number representations containing fraction or exponent parts 365 in the input JWK representation should be avoided. 367 All of these practical considerations are really an instance of Jon 368 Postel's principle: "Be liberal in what you accept, and conservative 369 in what you send." 371 6. IANA Considerations 373 6.1. JWS and JWE Header Parameter Registration 375 This specification registers the "jkt" Header Parameters defined in 376 Sections 4.1 and 4.2 in the IANA JSON Web Signature and Encryption 377 Header Parameters registry defined in [JWS]. 379 6.1.1. Registry Contents 381 o Header Parameter Name: "jkt" 382 o Header Parameter Description: JWS JWK Thumbprint 383 o Header Parameter Usage Location(s): JWS 384 o Change Controller: IETF 385 o Specification Document(s): Section 4.1 of [[ this document ]] 387 o Header Parameter Name: "jkt" 388 o Header Parameter Description: JWE JWK Thumbprint 389 o Header Parameter Usage Location(s): JWE 390 o Change Controller: IETF 391 o Specification Document(s): Section 4.2 of [[ this document ]] 393 6.2. JSON Web Key Parameters Registration 395 This specification registers the "jkt" JWK member defined in 396 Section 4.3 in the IANA JSON Web Key Parameters registry defined in 397 [JWK]. 399 6.2.1. Registry Contents 401 o Parameter Name: "jkt" 402 o Parameter Description: JWK Thumbprint 403 o Used with "kty" Value(s): * 404 o Parameter Information Class: Public 405 o Change Controller: IESG 406 o Specification Document(s): Section 4.3 of [[ this document ]] 408 7. Security Considerations 410 The JSON Security Considerations and Unicode security considerations 411 described in Sections 10.2 and 10.3 of JSON Web Signature (JWS) [JWS] 412 also apply to this specification. 414 Also, as described in Section 5, some implementations may produce 415 incorrect results if esoteric or escaped characters are used in the 416 member names. The security implications of this appear to be limited 417 for JWK Thumbprints of public keys, since while it may result in 418 implementations failing to identify the intended key, it should not 419 leak information, since the information in a public key is already 420 public in nature, by definition. 422 8. Normative References 424 [JWA] Jones, M., "JSON Web Algorithms (JWA)", 425 draft-ietf-jose-json-web-algorithms (work in progress), 426 October 2014. 428 [JWE] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 429 draft-ietf-jose-json-web-encryption (work in progress), 430 October 2014. 432 [JWK] Jones, M., "JSON Web Key (JWK)", 433 draft-ietf-jose-json-web-key (work in progress), 434 October 2014. 436 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 437 Signature (JWS)", draft-ietf-jose-json-web-signature (work 438 in progress), October 2014. 440 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 441 Requirement Levels", BCP 14, RFC 2119, March 1997. 443 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 444 Interchange Format", RFC 7159, March 2014. 446 Appendix A. Acknowledgements 448 James Manger, Nat Sakimura, and John Bradley participated in 449 discussions that led to the creation of this specification. 451 Appendix B. Document History 453 [[ to be removed by the RFC editor before publication as an RFC ]] 455 -00 457 o Created draft-ietf-jose-jwk-thumbprint-00 from 458 draft-jones-jose-jwk-thumbprint-01 with no normative changes. 460 Author's Address 462 Michael B. Jones 463 Microsoft 465 Email: mbj@microsoft.com 466 URI: http://self-issued.info/