idnits 2.17.1 draft-ietf-oauth-proof-of-possession-01.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 (January 28, 2015) is 3374 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) == Outdated reference: A later version (-08) exists of draft-ietf-oauth-pop-architecture-00 Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 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: August 1, 2015 Ping Identity 6 H. Tschofenig 7 ARM Limited 8 January 28, 2015 10 Proof-Of-Possession Semantics for JSON Web Tokens (JWTs) 11 draft-ietf-oauth-proof-of-possession-01 13 Abstract 15 This specification defines how to express a declaration in a JSON Web 16 Token (JWT) that the presenter of the JWT possesses a particular key 17 and that the recipient can cryptographically confirm proof-of- 18 possession of the key by the presenter. This property is also 19 sometimes described as the presenter being a holder-of-key. 21 Status of this Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on August 1, 2015. 38 Copyright Notice 40 Copyright (c) 2015 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 56 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3 57 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 58 3. Proof-Of-Possession Representation . . . . . . . . . . . . . . 4 59 3.1. Proof-of-Possession of an Asymmetric Key . . . . . . . . . 4 60 3.2. Proof-of-Possession of a Symmetric Key . . . . . . . . . . 5 61 3.3. Confirmation . . . . . . . . . . . . . . . . . . . . . . . 6 62 3.4. Specifics Intentionally Not Specified . . . . . . . . . . 6 63 4. Security Considerations . . . . . . . . . . . . . . . . . . . 6 64 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 65 5.1. JSON Web Token Claims Registration . . . . . . . . . . . . 8 66 5.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 8 67 5.2. JWT Confirmation Methods Registry . . . . . . . . . . . . 8 68 5.2.1. Registration Template . . . . . . . . . . . . . . . . 9 69 5.2.2. Initial Registry Contents . . . . . . . . . . . . . . 9 70 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 9 71 6.1. Normative References . . . . . . . . . . . . . . . . . . . 9 72 6.2. Informative References . . . . . . . . . . . . . . . . . . 10 73 Appendix A. Open Issues . . . . . . . . . . . . . . . . . . . . . 10 74 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 10 75 Appendix C. Document History . . . . . . . . . . . . . . . . . . 10 76 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 11 78 1. Introduction 80 This specification defines how to express a declaration in a JSON Web 81 Token (JWT) [JWT] that the presenter of the JWT possesses a 82 particular key and that the recipient can cryptographically confirm 83 proof-of-possession of the key by the presenter. This property is 84 also sometimes described as the presenter being a holder-of-key. 86 [[ Editorial Note: This paragraph needs to be updated to provide more 87 context and possibly also to describe the use of asymmetric keys 88 instead. It's not clear that the symmetric case is as useful or 89 valuable, and it is certainly more complicated.]] Envision the 90 following use case: An OAuth 2.0 authorization server generates a JWT 91 and places an encrypted symmetric key inside the newly introduced 92 confirmation claim. This symmetric key is encrypted with a key known 93 only to the authorization server and the recipient. The JWT is then 94 sent to the presenter. Since the presenter is unable to obtain the 95 encrypted symmetric key, the authorization server conveys that 96 symmetric key separately to the presenter. Now, the presenter is in 97 possession of the symmetric key as well as the JWT (which includes 98 the confirmation claim member). When the presenter needs to utilize 99 the JWT to at recipient, it also needs to demonstrate possession of 100 the symmetric key; the presenter, for example, uses the symmetric key 101 in a challenge/response protocol with the recipient. The recipient 102 is able to verify that it is interacting with the genuine presenter 103 by decrypting the JWK contained inside the confirmation claim of the 104 JWT. By doing this the recipient obtains the symmetric key, which it 105 then uses to verify cryptographically protected messages exchanged 106 with the presenter. 108 1.1. Notational Conventions 110 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 111 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 112 document are to be interpreted as described in RFC 2119 [RFC2119]. 114 Unless otherwise noted, all the protocol parameter names and values 115 are case sensitive. 117 2. Terminology 119 This specification uses terms defined in the JSON Web Token (JWT) 120 [JWT], JSON Web Key (JWK) [JWK], and JSON Web Encryption (JWE) [JWE] 121 specifications. 123 These terms are defined by this specification: 125 Presenter 126 Party that possesses the key identified by the JWT. 128 3. Proof-Of-Possession Representation 130 The presenter of a JWT declares that it possesses a particular key 131 and that the recipient can cryptographically confirm proof-of- 132 possession of the key by the issuer by including a "cnf" 133 (confirmation) claim in the JWT whose value is a JSON object, with 134 the JSON object containing a "jwk" (JSON Web Key) member identifying 135 the key. 137 The presenter can be identified in one of two ways by the JWT, 138 depending upon the application requirements. If the JWT contains a 139 "sub" (subject) claim, the presenter is the subject identified by the 140 JWT. (In some applications, the subject identifier will be relative 141 to the issuer identified by the "iss" (issuer) claim.) If the JWT 142 contains no "sub" (subject) claim, the presenter is the issuer 143 identified by the JWT using the "iss" (issuer) claim. The case in 144 which the presenter is the subject of the JWT is analogous to SAML 145 2.0 [OASIS.saml-core-2.0-os] SubjectConfirmation usage. At least one 146 of the "sub" and "iss" claims MUST be present in the JWT, and in some 147 use cases, both MUST be present. 149 3.1. Proof-of-Possession of an Asymmetric Key 151 When the key held by the issuer is an asymmetric private key, the 152 value of the "jwk" member is a JSON Web Key (JWK) [JWK] representing 153 the corresponding asymmetric public key. The following example 154 demonstrates such a declaration in the JWT Claims Set of a JWT: 156 { 157 "iss":"xas.example.com", 158 "aud":"http://auth.example.com", 159 "exp":"1361398824", 160 "nbf":"1360189224", 161 "cnf":{ 162 "jwk":{ 163 "kty":"EC", 164 "use":"sig", 165 "crv":"P-256", 166 "x":"18wHLeIgW9wVN6VD1Txgpqy2LszYkMf6J8njVAibvhM", 167 "y":"-V4dS4UaLMgP_4fY4j8ir7cl1TXlFdAgcx55o7TkcSA" 168 } 169 } 170 } 172 The JWK MUST contain the required key members for a JWK of that key 173 type and MAY contain other JWK members, including the "kid" (key ID) 174 member. 176 3.2. Proof-of-Possession of a Symmetric Key 178 When the key held by the issuer is a symmetric key, the value of the 179 "jwk" member is an encrypted JSON Web Key (JWK) [JWK] encrypted to a 180 key known to the recipient using the JWE Compact Serialization 181 containing the symmetric key. The rules for encrypting a JWK are 182 found in Section 6 of the JSON Web Key [JWK] specification. 184 The following example illustrates a symmetric key that could 185 subsequently be encrypted for use in the "jwk" member: 187 { 188 "kty":"oct", 189 "alg":"HS256", 190 "k":"ZoRSOrFzN_FzUA5XKMYoVHyzff5oRJxl-IXRtztJ6uE" 191 } 193 The UTF-8 [RFC3629] encoding of this JWK would be used as the JWE 194 Plaintext when encrypting the key. 196 The following example is a JWE Header that could be used when 197 encrypting this key: 199 { 200 "alg":"RSA1_5", 201 "enc":"A128CBC-HS256", 202 "cty":"jwk+json" 203 } 205 The following example JWT Claims Set of a JWT illustrates the use of 206 an encrypted symmetric key as the "jwk" claim value: 208 { 209 "iss": "https://server.example.com", 210 "sub": "24400320", 211 "aud": "s6BhdRkqt3", 212 "nonce": "n-0S6_WzA2Mj", 213 "exp": 1311281970, 214 "iat": 1311280970, 215 "cnf":{ 216 "jwk": 217 "eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiY3R5Ijoi 218 andrK2pzb24ifQ. ... (remainder of JWE omitted for brevity)" 219 } 221 } 223 Note that the case in which the "jwk" claim contains an unencoded JWK 224 value and the case in which it contains an encrypted JWK value can be 225 distinguished by the type of the member value. In the first case, 226 the value is a JSON object containing the JWK and in the second case, 227 the value is a string containing the JWE JSON Serialization of the 228 encrypted JWK representation. 230 3.3. Confirmation 232 The "cnf" (confirmation) claim is used in the JWT to contain the 233 "jwk" member because a proof-of-possession key may not be the only 234 means of confirming the authenticity of the token. This is analogous 235 to the SAML 2.0 [OASIS.saml-core-2.0-os] SubjectConfirmation element, 236 in which a number of different subject confirmation methods can be 237 included, including proof-of-possession key information. When a 238 recipient receives a "cnf" claim with a member that it does not 239 understand, it MUST ignore that member. 241 This specification defines a registry for these members in 242 Section 5.2 and registers the "jwk" member within the registry. 244 3.4. Specifics Intentionally Not Specified 246 Proof-of-possession is typically demonstrated by having the issuer 247 sign a value determined by the recipient using the key possessed by 248 the issuer. This value is sometimes called a "nonce" or a 249 "challenge". 251 The means of communicating the nonce and the nature of its contents 252 are intentionally not described in this specification, as different 253 protocols will communicate this information in different ways. 254 Likewise, the means of communicating the signed nonce is also not 255 specified, as this is also protocol-specific. 257 Note that another means of proving possession of the key when it is a 258 symmetric key is to encrypt the key to the recipient. The means of 259 obtaining a key for the recipient is likewise protocol-specific. 261 For an example specification that uses the mechanisms defined in this 262 document, see [I-D.ietf-oauth-pop-architecture]. 264 4. Security Considerations 266 All of the normal security issues, especially in relationship to 267 comparing URIs and dealing with unrecognized values, that are 268 discussed in JWT [JWT] also apply here. 270 In addition, proof-of-possession introduces its own unique security 271 issues. Possessing the key is only valuable if it is kept secret. 272 Appropriate means must be used to ensure that unintended parties do 273 not learn the private key or symmetric key value. 275 Proof-of-possession via encrypted symmetric secrets is subject to 276 replay attacks. This attack can be avoided when a signed nonce or 277 challenge is used, since the recipient can use a distinct nonce or 278 challenged for each interaction. 280 Similarly to other information included in a JWT, it is necessary to 281 apply data origin authentication and integrity protection (via a 282 keyed message digest or a digital signature). Data origin 283 authentication ensures that the recipient of the JWT learns about the 284 entity that created the JWT, since this will be important for any 285 policy decisions. Integrity protection prevents an adversary from 286 changing any elements conveyed within the JWT payload. Special care 287 has to be applied when carrying symmetric keys inside the JWT, since 288 those not only require integrity protection, but also confidentiality 289 protection. 291 A recipient may not understand the newly introduced "cnf" claim and 292 may consequently treat it as a bearer token. While this is a 293 legitimate concern, it is outside the scope of this specification, 294 since demonstration the possession of the key associated with the 295 "cnf" claim is not covered by this specification. For more details, 296 please consult [I-D.ietf-oauth-pop-architecture]. 298 5. IANA Considerations 300 The following registration procedure is used for all the registries 301 established by this specification. 303 Values are registered with a Specification Required [RFC5226] after a 304 two-week review period on the [TBD]@ietf.org mailing list, on the 305 advice of one or more Designated Experts. However, to allow for the 306 allocation of values prior to publication, the Designated Expert(s) 307 may approve registration once they are satisfied that such a 308 specification will be published. 310 Registration requests must be sent to the [TBD]@ietf.org mailing list 311 for review and comment, with an appropriate subject (e.g., "Request 312 for access token type: example"). [[ Note to the RFC Editor: The name 313 of the mailing list should be determined in consultation with the 314 IESG and IANA. Suggested name: jwt-reg-review. ]] 315 Within the review period, the Designated Expert(s) will either 316 approve or deny the registration request, communicating this decision 317 to the review list and IANA. Denials should include an explanation 318 and, if applicable, suggestions as to how to make the request 319 successful. Registration requests that are undetermined for a period 320 longer than 21 days can be brought to the IESG's attention (using the 321 iesg@iesg.org mailing list) for resolution. 323 Criteria that should be applied by the Designated Expert(s) includes 324 determining whether the proposed registration duplicates existing 325 functionality, determining whether it is likely to be of general 326 applicability or whether it is useful only for a single application, 327 and whether the registration makes sense. 329 IANA must only accept registry updates from the Designated Expert(s) 330 and should direct all requests for registration to the review mailing 331 list. 333 It is suggested that multiple Designated Experts be appointed who are 334 able to represent the perspectives of different applications using 335 this specification, in order to enable broadly-informed review of 336 registration decisions. In cases where a registration decision could 337 be perceived as creating a conflict of interest for a particular 338 Expert, that Expert should defer to the judgment of the other 339 Expert(s). 341 5.1. JSON Web Token Claims Registration 343 This specification registers the "cnf" claim in the IANA JSON Web 344 Token Claims registry defined in [JWT]. 346 5.1.1. Registry Contents 348 o Claim Name: "cnf" 349 o Claim Description: Confirmation 350 o Change Controller: IESG 351 o Specification Document(s): Section 3.3 of this document 353 5.2. JWT Confirmation Methods Registry 355 This specification establishes the IANA JWT Confirmation Methods 356 registry for JWT "cnf" member values. The registry records the 357 confirmation method member and a reference to the specification that 358 defines it. 360 5.2.1. Registration Template 362 Confirmation Method Value: 363 The name requested (e.g., "example"). Because a core goal of this 364 specification is for the resulting representations to be compact, 365 it is RECOMMENDED that the name be short -- not to exceed 8 366 characters without a compelling reason to do so. This name is 367 case-sensitive. Names may not match other registered names in a 368 case-insensitive manner unless the Designated Expert(s) state that 369 there is a compelling reason to allow an exception in this 370 particular case. 372 Confirmation Method Description: 373 Brief description of the confirmation method (e.g., "Example 374 description"). 376 Change Controller: 377 For Standards Track RFCs, state "IESG". For others, give the name 378 of the responsible party. Other details (e.g., postal address, 379 email address, home page URI) may also be included. 381 Specification Document(s): 382 Reference to the document(s) that specify the parameter, 383 preferably including URI(s) that can be used to retrieve copies of 384 the document(s). An indication of the relevant sections may also 385 be included but is not required. 387 5.2.2. Initial Registry Contents 389 o Confirmation Method Value: "jwk" 390 o Confirmation Method Description: JSON Web Key or Encrypted JSON 391 Web Key 392 o Change Controller: IESG 393 o Specification Document(s): Section 3 of [[ this document ]] 395 6. References 397 6.1. Normative References 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 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 408 (JWT)", draft-ietf-oauth-json-web-token (work in 409 progress), December 2014. 411 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 412 Requirement Levels", BCP 14, RFC 2119, March 1997. 414 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 415 10646", STD 63, RFC 3629, November 2003. 417 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 418 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 419 May 2008. 421 6.2. Informative References 423 [I-D.ietf-oauth-pop-architecture] 424 Hunt, P., Richer, J., Mills, W., Mishra, P., and H. 425 Tschofenig, "OAuth 2.0 Proof-of-Possession (PoP) Security 426 Architecture", draft-ietf-oauth-pop-architecture-00 (work 427 in progress), July 2014. 429 [OASIS.saml-core-2.0-os] 430 Cantor, S., Kemp, J., Philpott, R., and E. Maler, 431 "Assertions and Protocol for the OASIS Security Assertion 432 Markup Language (SAML) V2.0", OASIS Standard saml-core- 433 2.0-os, March 2005. 435 Appendix A. Open Issues 437 In some conversations, we have said that it is the issuer of the JWT 438 that possesses the key, and in some conversations, we have said that 439 it is the presenter of the JWT that possesses the key. Which 440 description should we use? 442 Appendix B. Acknowledgements 444 The authors wish to thank James Manger for his review of the 445 specification. 447 Appendix C. Document History 449 [[ to be removed by the RFC Editor before publication as an RFC ]] 451 -01 452 o Updated references. 454 -00 456 o Created the initial working group draft from 457 draft-jones-oauth-proof-of-possession-02. 459 Authors' Addresses 461 Michael B. Jones 462 Microsoft 464 Email: mbj@microsoft.com 465 URI: http://self-issued.info/ 467 John Bradley 468 Ping Identity 470 Email: ve7jtb@ve7jtb.com 471 URI: http://www.thread-safe.com/ 473 Hannes Tschofenig 474 ARM Limited 475 Austria 477 Email: Hannes.Tschofenig@gmx.net 478 URI: http://www.tschofenig.priv.at