idnits 2.17.1 draft-ietf-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 (July 21, 2014) is 3567 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: January 22, 2015 Ping Identity 6 H. Tschofenig 7 ARM Limited 8 July 21, 2014 10 Proof-Of-Possession Semantics for JSON Web Tokens (JWTs) 11 draft-ietf-oauth-proof-of-possession-00.txt 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 January 22, 2015. 38 Copyright Notice 40 Copyright (c) 2014 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 . . . . . . . . . . . . . . . . . . . . . . . . 2 56 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 57 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 58 3. Proof-Of-Possession Representation . . . . . . . . . . . . . 3 59 3.1. Proof-of-Possession of an Asymmetric Key . . . . . . . . 4 60 3.2. Proof-of-Possession of a Symmetric Key . . . . . . . . . 4 61 3.3. Confirmation . . . . . . . . . . . . . . . . . . . . . . 5 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 . . . . . . . . . . . . . . . . 8 69 5.2.2. Initial Registry Contents . . . . . . . . . . . . . . 9 70 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 71 6.1. Normative References . . . . . . . . . . . . . . . . . . 9 72 6.2. Informative References . . . . . . . . . . . . . . . . . 9 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 } 220 } 222 Note that the case in which the "jwk" claim contains an unencoded JWK 223 value and the case in which it contains an encrypted JWK value can be 224 distinguished by the type of the member value. In the first case, 225 the value is a JSON object containing the JWK and in the second case, 226 the value is a string containing the JWE JSON Serialization of the 227 encrypted JWK representation. 229 3.3. Confirmation 231 The "cnf" (confirmation) claim is used in the JWT to contain the 232 "jwk" member because a proof-of-possession key may not be the only 233 means of confirming the authenticity of the token. This is analogous 234 to the SAML 2.0 [OASIS.saml-core-2.0-os] SubjectConfirmation element, 235 in which a number of different subject confirmation methods can be 236 included, including proof-of-possession key information. When a 237 recipient receives a "cnf" claim with a member that it does not 238 understand, it MUST ignore that member. 240 This specification defines a registry for these members in 241 Section 5.2 and registers the "jwk" member within the registry. 243 3.4. Specifics Intentionally Not Specified 245 Proof-of-possession is typically demonstrated by having the issuer 246 sign a value determined by the recipient using the key possessed by 247 the issuer. This value is sometimes called a "nonce" or a 248 "challenge". 250 The means of communicating the nonce and the nature of its contents 251 are intentionally not described in this specification, as different 252 protocols will communicate this information in different ways. 253 Likewise, the means of communicating the signed nonce is also not 254 specified, as this is also protocol-specific. 256 Note that another means of proving possession of the key when it is a 257 symmetric key is to encrypt the key to the recipient. The means of 258 obtaining a key for the recipient is likewise protocol-specific. 260 For an example specification that uses the mechanisms defined in this 261 document, see [I-D.hunt-oauth-pop-architecture]. 263 4. Security Considerations 265 All of the normal security issues, especially in relationship to 266 comparing URIs and dealing with unrecognized values, that are 267 discussed in JWT [JWT] also apply here. 269 In addition, proof-of-possession introduces its own unique security 270 issues. Possessing the key is only valuable if it is kept secret. 271 Appropriate means must be used to ensure that unintended parties do 272 not learn the private key or symmetric key value. 274 Proof-of-possession via encrypted symmetric secrets is subject to 275 replay attacks. This attack can be avoided when a signed nonce or 276 challenge is used, since the recipient can use a distinct nonce or 277 challenged for each interaction. 279 Similarly to other information included in a JWT, it is necessary to 280 apply data origin authentication and integrity protection (via a 281 keyed message digest or a digital signature). Data origin 282 authentication ensures that the recipient of the JWT learns about the 283 entity that created the JWT, since this will be important for any 284 policy decisions. Integrity protection prevents an adversary from 285 changing any elements conveyed within the JWT payload. Special care 286 has to be applied when carrying symmetric keys inside the JWT, since 287 those not only require integrity protection, but also confidentiality 288 protection. 290 A recipient may not understand the newly introduced "cnf" claim and 291 may consequently treat it as a bearer token. While this is a 292 legitimate concern, it is outside the scope of this specification, 293 since demonstration the possession of the key associated with the 294 "cnf" claim is not covered by this specification. For more details, 295 please consult [I-D.hunt-oauth-pop-architecture]. 297 5. IANA Considerations 299 The following registration procedure is used for all the registries 300 established by this specification. 302 Values are registered with a Specification Required [RFC5226] after a 303 two-week review period on the [TBD]@ietf.org mailing list, on the 304 advice of one or more Designated Experts. However, to allow for the 305 allocation of values prior to publication, the Designated Expert(s) 306 may approve registration once they are satisfied that such a 307 specification will be published. 309 Registration requests must be sent to the [TBD]@ietf.org mailing list 310 for review and comment, with an appropriate subject (e.g., "Request 311 for access token type: example"). [[ Note to the RFC Editor: The 312 name of the mailing list should be determined in consultation with 313 the 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): 383 Reference to the document(s) that specify the parameter, 384 preferably including URI(s) that can be used to retrieve copies of 385 the document(s). An indication of the relevant sections may also 386 be included but is not required. 388 5.2.2. Initial Registry Contents 390 o Confirmation Method Value: "jwk" 391 o Confirmation Method Description: JSON Web Key or Encrypted JSON 392 Web Key 393 o Change Controller: IESG 394 o Specification Document(s): Section 3 of [[ this document ]] 396 6. References 398 6.1. Normative References 400 [JWE] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 401 draft-ietf-jose-json-web-encryption (work in progress), 402 July 2014. 404 [JWK] Jones, M., "JSON Web Key (JWK)", draft-ietf-jose-json-web- 405 key (work in progress), July 2014. 407 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 408 (JWT)", draft-ietf-oauth-json-web-token (work in 409 progress), July 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.hunt-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-hunt-oauth-pop-architecture-02 (work 427 in progress), June 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 -02 453 o Used the same section structuring conventions as the JWT 454 specification. 455 o Reverted some changes introduced in -01 without adequate prior 456 review. 457 o Applied some editorial corrections. 459 -01 461 o Updated affiliation. 462 o Various editorial changes. 463 o Updates to the security considerations section based on review 464 feedback by James Manager. 465 o Included the kid element in the examples (as requested by James 466 Manger). 467 o Expanded the introduction section. 468 o Moved the terminology/RFC2119 boilerplate text from the 469 introduction to a separate terminology section. 471 -00 473 o Wrote the first draft. 475 Authors' Addresses 477 Michael B. Jones 478 Microsoft 480 Email: mbj@microsoft.com 481 URI: http://self-issued.info/ 483 John Bradley 484 Ping Identity 486 Email: ve7jtb@ve7jtb.com 487 URI: http://www.thread-safe.com/ 489 Hannes Tschofenig 490 ARM Limited 491 Austria 493 Email: Hannes.Tschofenig@gmx.net 494 URI: http://www.tschofenig.priv.at