idnits 2.17.1 draft-jones-oauth-proof-of-possession-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 (April 1, 2014) is 3650 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 5226 (Obsoleted by RFC 8126) Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth Working Group M. Jones 3 Internet-Draft Microsoft 4 Intended status: Standards Track J. Bradley 5 Expires: October 3, 2014 Ping Identity 6 H. Tschofenig 7 April 1, 2014 9 Proof-Of-Possession Semantics for JSON Web Tokens (JWTs) 10 draft-jones-oauth-proof-of-possession-00 12 Abstract 14 This specification defines how to express a declaration in a JSON Web 15 Token (JWT) that the presenter of the JWT possesses a particular key 16 and that the recipient can cryptographically confirm proof-of- 17 possession of the key by the presenter. This property is also 18 sometimes described as the presenter being a holder-of-key. 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 October 3, 2014. 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 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . 3 57 2. Proof-Of-Possession Representation . . . . . . . . . . . . . . 3 58 2.1. Proof-of-Possession of a Private Key . . . . . . . . . . . 4 59 2.2. Proof-of-Possession of a Symmetric Key . . . . . . . . . . 4 60 2.3. Confirmation . . . . . . . . . . . . . . . . . . . . . . . 5 61 2.4. Specifics Intentionally Not Specified . . . . . . . . . . . 6 62 3. Security Considerations . . . . . . . . . . . . . . . . . . . . 6 63 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 6 64 4.1. JSON Web Token Claims Registration . . . . . . . . . . . . 7 65 4.1.1. Registry Contents . . . . . . . . . . . . . . . . . . . 7 66 4.2. JWT Confirmation Methods Registry . . . . . . . . . . . . . 7 67 4.2.1. Registration Template . . . . . . . . . . . . . . . . . 8 68 4.2.2. Initial Registry Contents . . . . . . . . . . . . . . . 8 69 5. References . . . . . . . . . . . . . . . . . . . . . . . . . . 8 70 5.1. Normative References . . . . . . . . . . . . . . . . . . . 8 71 5.2. Informative References . . . . . . . . . . . . . . . . . . 9 72 Appendix A. Open Issues . . . . . . . . . . . . . . . . . . . . . 9 73 Appendix B. Document History . . . . . . . . . . . . . . . . . . . 9 74 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 9 76 1. Introduction 78 This specification defines how to express a declaration in a JSON Web 79 Token (JWT) [JWT] that the presenter of the JWT possesses a 80 particular key and that the recipient can cryptographically confirm 81 proof-of-possession of the key by the presenter. This property is 82 also sometimes described as the presenter being a holder-of-key. 84 1.1. Notational Conventions 86 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 87 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 88 document are to be interpreted as described in RFC 2119 [RFC2119]. 90 Unless otherwise noted, all the protocol parameter names and values 91 are case sensitive. 93 1.2. Terminology 95 This specification uses terms defined in the JSON Web Token (JWT) 96 [JWT], JSON Web Key (JWK) [JWK], and JSON Web Encryption (JWE) [JWE] 97 specifications. 99 These terms are defined for use by this specification: 101 Presenter 102 Party that possesses the key identified by the JWT. 104 2. Proof-Of-Possession Representation 106 The presenter of a JWT declares that it possesses a particular key 107 and that the recipient can cryptographically confirm proof-of- 108 possession of the key by the issuer by including a "cnf" 109 (confirmation) claim in the JWT whose value is a JSON object, with 110 the JSON object containing a "jwk" (JSON Web Key) member identifying 111 the key. 113 The presenter can be identified in one of two ways by the JWT, 114 depending upon the application requirements. If the JWT contains a 115 "sub" (subject) claim, the presenter is the subject identified by the 116 JWT. (In some applications, the subject identifier will be relative 117 to the issuer identified by the "iss" (issuer) claim.) If the JWT 118 contains no "sub" (subject) claim, the presenter is the issuer 119 identified by the JWT using the "iss" (issuer) claim. The case in 120 which the presenter is the subject of the JWT is analogous to SAML 121 2.0 [OASIS.saml-core-2.0-os] SubjectConfirmation usage. At least one 122 of the "sub" and "iss" claims MUST be present in the JWT, and in some 123 use cases, both MUST be present. 125 2.1. Proof-of-Possession of a Private Key 127 When the key held by the issuer is a private key, the value of the 128 "jwk" member is a JSON Web Key (JWK) [JWK] representing the 129 corresponding public key. The following example demonstrates such a 130 declaration in the JWT Claims Set of a JWT: 132 { 133 "iss":"xas.xboxlive.com", 134 "aud":"http://auth.xboxlive.com", 135 "exp":"1361398824", 136 "nbf":"1360189224", 137 "cnf":{ 138 "jwk":{ 139 "kty":"EC", 140 "use":"sig", 141 "crv":"P-256", 142 "x":"18wHLeIgW9wVN6VD1Txgpqy2LszYkMf6J8njVAibvhM", 143 "y":"-V4dS4UaLMgP_4fY4j8ir7cl1TXlFdAgcx55o7TkcSA" 144 } 145 } 146 } 148 The JWK MUST contain the REQUIRED key elements for a JWK of that key 149 type and MAY contain other JWK elements, including the "kid" (key ID) 150 element. 152 2.2. Proof-of-Possession of a Symmetric Key 154 When the key held by the issuer is a symmetric key, the value of the 155 "jwk" member is an encrypted JSON Web Key (JWK) [JWK] encrypted to 156 the recipient using the JWE Compact Serialization containing the 157 symmetric key. The rules for encrypting a JWK are found in Section 6 158 of the JSON Web Key [JWK] specification. 160 The following is an example symmetric key that could be encrypted for 161 use in the "jwk" member: 163 { 164 "kty":"oct", 165 "alg":"HS256", 166 "k":"ZoRSOrFzN_FzUA5XKMYoVHyzff5oRJxl-IXRtztJ6uE" 167 } 169 The UTF-8 [RFC3629] encoding of this JWK would be used as the JWE 170 Plaintext. 172 The following is an example JWE Header could be used when encrypting 173 this key: 175 { 176 "alg":"RSA1_5", 177 "enc":"A128CBC-HS256", 178 "cty":"jwk+json" 179 } 181 The following example JWT Claims Set of a JWT illustrates the use of 182 an encrypted symmetric key as the "jwk" claim value: 184 { 185 "iss": "https://server.example.com", 186 "sub": "24400320", 187 "aud": "s6BhdRkqt3", 188 "nonce": "n-0S6_WzA2Mj", 189 "exp": 1311281970, 190 "iat": 1311280970, 191 "cnf":{ 192 "jwk": 193 "eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiY3R5Ijoi 194 andrK2pzb24ifQ. ... (remainder of JWE omitted for brevity)" 195 } 196 } 198 Note that the case in which the "jwk" claim contains an unencoded JWK 199 value and the case in which it contains an encrypted JWK value can be 200 distinguished by the type of the member value. In the first case, 201 the value is a JSON object containing the JWK and in the second case, 202 the value is a string containing the JWE JSON Serialization of the 203 encrypted JWK representation. 205 2.3. Confirmation 207 The "cnf" (confirmation) claim is used in the JWT to contain the 208 "jwk" member because a proof-of-possession key may not be the only 209 means of confirming the authenticity of the token. This is analogous 210 to the SAML 2.0 [OASIS.saml-core-2.0-os] SubjectConfirmation element, 211 in which a number of different subject confirmation methods can be 212 included, including proof-of-possession key information. When a 213 recipient receives a "cnf" claim with a member that it does not 214 understand, it MUST ignore that member. 216 This specification defines a registry for these elements in 217 Section 4.2 and registers the "jwk" member within the registry. 219 2.4. Specifics Intentionally Not Specified 221 Proof-of-possession is typically demonstrated by having the issuer 222 sign a value determined by the recipient using the key possessed by 223 the issuer. This value is sometimes called a "nonce" or a 224 "challenge". 226 The means of communicating the nonce and the nature of its contents 227 are intentionally not described in this specification, as different 228 protocols will communicate this information in different ways. 229 Likewise, the means of communicating the signed nonce is also not 230 specified, as this is also protocol-specific. 232 Note that another means of proving possession of the key when it is a 233 symmetric key is to encrypt the key to the recipient. The means of 234 obtaining a key for the recipient is likewise protocol-specific. 236 3. Security Considerations 238 All of the normal security issues, especially in relationship to 239 comparing URIs and dealing with unrecognized values, that are 240 discussed in JWT [JWT] also apply here. 242 In addition, proof-of-possession introduces its own unique security 243 issues. Possessing the key is only valuable if it is kept secret. 244 Appropriate means must be used to ensure that unintended parties do 245 not learn the secret or symmetric key value. 247 Proof-of-possession via encrypted symmetric secrets is subject to 248 replay attacks. This attack can be avoided when a signed nonce or 249 challenge is used, since the recipient can use a distinct nonce or 250 challenged for each interaction. 252 4. IANA Considerations 254 The following registration procedure is used for all the registries 255 established by this specification. 257 Values are registered with a Specification Required [RFC5226] after a 258 two-week review period on the [TBD]@ietf.org mailing list, on the 259 advice of one or more Designated Experts. However, to allow for the 260 allocation of values prior to publication, the Designated Expert(s) 261 may approve registration once they are satisfied that such a 262 specification will be published. 264 Registration requests must be sent to the [TBD]@ietf.org mailing list 265 for review and comment, with an appropriate subject (e.g., "Request 266 for access token type: example"). [[ Note to the RFC Editor: The name 267 of the mailing list should be determined in consultation with the 268 IESG and IANA. Suggested name: jwt-reg-review. ]] 270 Within the review period, the Designated Expert(s) will either 271 approve or deny the registration request, communicating this decision 272 to the review list and IANA. Denials should include an explanation 273 and, if applicable, suggestions as to how to make the request 274 successful. Registration requests that are undetermined for a period 275 longer than 21 days can be brought to the IESG's attention (using the 276 iesg@iesg.org mailing list) for resolution. 278 Criteria that should be applied by the Designated Expert(s) includes 279 determining whether the proposed registration duplicates existing 280 functionality, determining whether it is likely to be of general 281 applicability or whether it is useful only for a single application, 282 and whether the registration makes sense. 284 IANA must only accept registry updates from the Designated Expert(s) 285 and should direct all requests for registration to the review mailing 286 list. 288 It is suggested that multiple Designated Experts be appointed who are 289 able to represent the perspectives of different applications using 290 this specification, in order to enable broadly-informed review of 291 registration decisions. In cases where a registration decision could 292 be perceived as creating a conflict of interest for a particular 293 Expert, that Expert should defer to the judgment of the other 294 Expert(s). 296 4.1. JSON Web Token Claims Registration 298 This specification registers the "cnf" claim in the IANA JSON Web 299 Token Claims registry defined in [JWT]. 301 4.1.1. Registry Contents 303 o Claim Name: "cnf" 304 o Claim Description: Confirmation 305 o Change Controller: IESG 306 o Specification Document(s): Section 2.3 of this document 308 4.2. JWT Confirmation Methods Registry 310 This specification establishes the IANA JWT Confirmation Methods 311 registry for JWT "cnf" member values. The registry records the 312 confirmation method member and a reference to the specification that 313 defines it. 315 4.2.1. Registration Template 317 Confirmation Method Value: 318 The name requested (e.g., "example"). Because a core goal of this 319 specification is for the resulting representations to be compact, 320 it is RECOMMENDED that the name be short -- not to exceed 8 321 characters without a compelling reason to do so. This name is 322 case-sensitive. Names may not match other registered names in a 323 case-insensitive manner unless the Designated Expert(s) state that 324 there is a compelling reason to allow an exception in this 325 particular case. 327 Confirmation Method Description: 328 Brief description of the confirmation method (e.g., "Example 329 description"). 331 Change Controller: 332 For Standards Track RFCs, state "IESG". For others, give the name 333 of the responsible party. Other details (e.g., postal address, 334 email address, home page URI) may also be included. 336 Specification Document(s): 337 Reference to the document(s) that specify the parameter, 338 preferably including URI(s) that can be used to retrieve copies of 339 the document(s). An indication of the relevant sections may also 340 be included but is not required. 342 4.2.2. Initial Registry Contents 344 o Confirmation Method Value: "jwk" 345 o Confirmation Method Description: JSON Web Key or Encrypted JSON 346 Web Key 347 o Change Controller: IESG 348 o Specification Document(s): Section 2 of [[ this document ]] 350 5. References 352 5.1. Normative References 354 [JWE] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 355 draft-ietf-jose-json-web-encryption (work in progress), 356 March 2014. 358 [JWK] Jones, M., "JSON Web Key (JWK)", 359 draft-ietf-jose-json-web-key (work in progress), 360 March 2014. 362 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 363 (JWT)", draft-ietf-oauth-json-web-token (work in 364 progress), March 2014. 366 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 367 Requirement Levels", BCP 14, RFC 2119, March 1997. 369 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 370 10646", STD 63, RFC 3629, November 2003. 372 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 373 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 374 May 2008. 376 5.2. Informative References 378 [OASIS.saml-core-2.0-os] 379 Cantor, S., Kemp, J., Philpott, R., and E. Maler, 380 "Assertions and Protocol for the OASIS Security Assertion 381 Markup Language (SAML) V2.0", OASIS Standard saml-core- 382 2.0-os, March 2005. 384 Appendix A. Open Issues 386 In some conversations, we have said that it is the issuer of the JWT 387 that possesses the key, and in some conversations, we have said that 388 it is the presenter of the JWT that possesses the key. Which 389 description should we use? 391 Appendix B. Document History 393 [[ to be removed by the RFC Editor before publication as an RFC ]] 395 -00 397 o Wrote the first draft. 399 Authors' Addresses 401 Michael B. Jones 402 Microsoft 404 Email: mbj@microsoft.com 405 URI: http://self-issued.info/ 407 John Bradley 408 Ping Identity 410 Email: ve7jtb@ve7jtb.com 411 URI: http://www.thread-safe.com/ 413 Hannes Tschofenig 415 Email: Hannes.Tschofenig@gmx.net 416 URI: http://www.tschofenig.priv.at