idnits 2.17.1 draft-ietf-oauth-proof-of-possession-02.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 (March 9, 2015) is 3334 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-01 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: September 10, 2015 Ping Identity 6 H. Tschofenig 7 ARM Limited 8 March 9, 2015 10 Proof-Of-Possession Semantics for JSON Web Tokens (JWTs) 11 draft-ietf-oauth-proof-of-possession-02 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 September 10, 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 . . . . . . . . . . . . . . . . . . 4 57 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 58 3. Proof-Of-Possession Representation . . . . . . . . . . . . . . 4 59 3.1. Proof-of-Possession of an Asymmetric Key . . . . . . . . . 5 60 3.2. Proof-of-Possession of a Symmetric Key . . . . . . . . . . 5 61 3.3. Proof-of-Possession Using a Key ID . . . . . . . . . . . . 6 62 3.4. Confirmation . . . . . . . . . . . . . . . . . . . . . . . 7 63 3.5. Specifics Intentionally Not Specified . . . . . . . . . . 7 64 4. Security Considerations . . . . . . . . . . . . . . . . . . . 8 65 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 66 5.1. JSON Web Token Claims Registration . . . . . . . . . . . . 9 67 5.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 9 68 5.2. JWT Confirmation Methods Registry . . . . . . . . . . . . 10 69 5.2.1. Registration Template . . . . . . . . . . . . . . . . 10 70 5.2.2. Initial Registry Contents . . . . . . . . . . . . . . 10 71 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 72 6.1. Normative References . . . . . . . . . . . . . . . . . . . 11 73 6.2. Informative References . . . . . . . . . . . . . . . . . . 11 74 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 12 75 Appendix B. Document History . . . . . . . . . . . . . . . . . . 12 76 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 12 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 Envision the following two use cases. The first use case describes 87 the use of a symmetric proof-of-possession key and the second use 88 case uses an asymmetric proof-of-possession key. 90 An OAuth 2.0 authorization server generates a JWT and places an 91 encrypted symmetric key inside the newly introduced confirmation 92 claim. This symmetric key is encrypted with a key known only to the 93 authorization server and the recipient. The entire JWT is then 94 integrity protected by the issuer (the authorization server). The 95 JWT is then sent to the presenter. Since the presenter is unable to 96 obtain the encrypted symmetric key from the JWT itself, the 97 authorization server conveys that symmetric key separately to the 98 presenter. Now, the presenter is in possession of the symmetric key 99 as well as the JWT (which includes the confirmation claim member). 100 When the presenter needs to present the JWT to the recipient, it also 101 needs to demonstrate possession of the symmetric key; the presenter, 102 for example, uses the symmetric key in a challenge/response protocol 103 with the recipient. The recipient is then able to verify that it is 104 interacting with the genuine presenter by decrypting the JWK 105 contained inside the confirmation claim of the JWT. By doing this, 106 the recipient obtains the symmetric key, which it then uses to verify 107 cryptographically protected messages exchanged with the presenter. 108 This symmetric key mechanism described above is conceptually similar 109 to the use of Kerberos tickets. 111 In the second case, consider a presenter that generates a public/ 112 private key pair. It then sends the public key to an OAuth 2.0 113 authorization server (the issuer), which creates a JWT and places a 114 public key (or an identifier for it) inside the newly introduced 115 confirmation claim. The entire JWT is integrity protected using a 116 digital signature to protect it against modifications. The JWT is 117 then sent to the presenter. When the presenter needs to present the 118 JWT to the recipient, it also needs to demonstrate possession of the 119 private key. The presenter, for example, uses the private key in a 120 TLS exchange with the recipient. The recipient is able to verify 121 that it is interacting with the genuine presenter by extracting the 122 public key from the confirmation claim of the JWT (after verifying 123 the digital signature of the JWT) and utilizing it with the private 124 key in the TLS exchange. The asymmetric key mechanism described 125 above is conceptually similar to a certificate. 127 In both cases the JWT may contain other claims that are needed by the 128 application. 130 1.1. Notational Conventions 132 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 133 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 134 "OPTIONAL" in this document are to be interpreted as described in RFC 135 2119 [RFC2119]. 137 Unless otherwise noted, all the protocol parameter names and values 138 are case sensitive. 140 2. Terminology 142 This specification uses terms defined in the JSON Web Token (JWT) 143 [JWT], JSON Web Key (JWK) [JWK], and JSON Web Encryption (JWE) [JWE] 144 specifications. 146 These terms are defined by this specification: 148 Issuer 149 Party that creates the JWT and binds the proof-of-possession key 150 to it. 152 Presenter 153 Party that proves possession of a private key (for asymmetric key 154 cryptography) or secret key (for symmetric key cryptography) to a 155 recipient. The presenter may be the issuer or a party different 156 from the issuer. 158 Recipient 159 Party that receives the JWT containing the proof-of-possession key 160 information from the presenter. 162 3. Proof-Of-Possession Representation 164 The presenter of a JWT declares that it possesses a particular key 165 and that the recipient can cryptographically confirm proof-of- 166 possession of the key by the presenter by including a "cnf" 167 (confirmation) claim in the JWT whose value is a JSON object, with 168 the JSON object containing a "jwk" (JSON Web Key) or "kid" (key ID) 169 member identifying the key. 171 The presenter can be identified in one of two ways by the JWT, 172 depending upon the application requirements. If the JWT contains a 173 "sub" (subject) claim, the presenter is the subject identified by the 174 JWT. (In some applications, the subject identifier will be relative 175 to the issuer identified by the "iss" (issuer) claim.) If the JWT 176 contains no "sub" (subject) claim, the presenter is the issuer 177 identified by the JWT using the "iss" (issuer) claim. The case in 178 which the presenter is the subject of the JWT is analogous to SAML 179 2.0 [OASIS.saml-core-2.0-os] SubjectConfirmation usage. At least one 180 of the "sub" and "iss" claims MUST be present in the JWT, and in some 181 use cases, both MUST be present. 183 3.1. Proof-of-Possession of an Asymmetric Key 185 When the key held by the presenter is an asymmetric private key, the 186 value of the "jwk" member is a JSON Web Key (JWK) [JWK] representing 187 the corresponding asymmetric public key. The following example 188 demonstrates such a declaration in the JWT Claims Set of a JWT: 190 { 191 "iss": "https://server.example.com", 192 "aud": "https://client.example.org", 193 "exp": "1361398824", 194 "nbf": "1360189224", 195 "cnf":{ 196 "jwk":{ 197 "kty": "EC", 198 "use": "sig", 199 "crv": "P-256", 200 "x": "18wHLeIgW9wVN6VD1Txgpqy2LszYkMf6J8njVAibvhM", 201 "y": "-V4dS4UaLMgP_4fY4j8ir7cl1TXlFdAgcx55o7TkcSA" 202 } 203 } 204 } 206 The JWK MUST contain the required key members for a JWK of that key 207 type and MAY contain other JWK members, including the "kid" (key ID) 208 member. 210 3.2. Proof-of-Possession of a Symmetric Key 212 When the key held by the presenter is a symmetric key, the value of 213 the "jwk" member is an encrypted JSON Web Key (JWK) [JWK] encrypted 214 to a key known to the recipient using the JWE Compact Serialization 215 containing the symmetric key. The rules for encrypting a JWK are 216 found in Section 6 of the JSON Web Key [JWK] specification. 218 The following example illustrates a symmetric key that could 219 subsequently be encrypted for use in the "jwk" member: 221 { 222 "kty": "oct", 223 "alg": "HS256", 224 "k": "ZoRSOrFzN_FzUA5XKMYoVHyzff5oRJxl-IXRtztJ6uE" 225 } 227 The UTF-8 [RFC3629] encoding of this JWK would be used as the JWE 228 Plaintext when encrypting the key. 230 The following example is a JWE Header that could be used when 231 encrypting this key: 233 { 234 "alg": "RSA1_5", 235 "enc": "A128CBC-HS256", 236 "cty": "jwk+json" 237 } 239 The following example JWT Claims Set of a JWT illustrates the use of 240 an encrypted symmetric key as the "jwk" claim value: 242 { 243 "iss": "https://server.example.com", 244 "sub": "24400320", 245 "aud": "s6BhdRkqt3", 246 "nonce": "n-0S6_WzA2Mj", 247 "exp": 1311281970, 248 "iat": 1311280970, 249 "cnf":{ 250 "jwk": 251 "eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiY3R5Ijoi 252 andrK2pzb24ifQ. ... (remainder of JWE omitted for brevity)" 253 } 254 } 256 Note that the case in which the "jwk" claim contains an unencoded JWK 257 value and the case in which it contains an encrypted JWK value can be 258 distinguished by the type of the member value. In the first case, 259 the value is a JSON object containing the JWK and in the second case, 260 the value is a string containing the JWE JSON Serialization of the 261 encrypted JWK representation. 263 3.3. Proof-of-Possession Using a Key ID 265 The proof-of-possession key can also be identified by the use of a 266 Key ID instead of communicating the actual key, provided the 267 recipient is able to obtain the identified key using the Key ID. In 268 this case, the presenter of a JWT declares that it possesses a 269 particular key and that the recipient can cryptographically confirm 270 proof-of-possession of the key by the presenter by including a "cnf" 271 (confirmation) claim in the JWT whose value is a JSON object, with 272 the JSON object containing a "kid" (key ID) member identifying the 273 key. 275 The following example demonstrates such a declaration in the JWT 276 Claims Set of a JWT: 278 { 279 "iss": "https://server.example.com", 280 "aud": "https://client.example.org", 281 "exp": "1361398824", 282 "nbf": "1360189224", 283 "cnf":{ 284 "kid": "dfd1aa97-6d8d-4575-a0fe-34b96de2bfad" 285 } 286 } 288 3.4. Confirmation 290 The "cnf" (confirmation) claim is used in the JWT to contain the 291 "jwk" or "kid" member because a proof-of-possession key may not be 292 the only means of confirming the authenticity of the token. This is 293 analogous to the SAML 2.0 [OASIS.saml-core-2.0-os] 294 SubjectConfirmation element, in which a number of different subject 295 confirmation methods can be included, including proof-of-possession 296 key information. When a recipient receives a "cnf" claim with a 297 member that it does not understand, it MUST ignore that member. 299 This specification defines a registry for these members in 300 Section 5.2 and registers the "jwk" and "kid" members within the 301 registry. 303 3.5. Specifics Intentionally Not Specified 305 Proof-of-possession is typically demonstrated by having the presenter 306 sign a value determined by the recipient using the key possessed by 307 the presenter. This value is sometimes called a "nonce" or a 308 "challenge". 310 The means of communicating the nonce and the nature of its contents 311 are intentionally not described in this specification, as different 312 protocols will communicate this information in different ways. 313 Likewise, the means of communicating the signed nonce is also not 314 specified, as this is also protocol-specific. 316 Note that another means of proving possession of the key when it is a 317 symmetric key is to encrypt the key to the recipient. The means of 318 obtaining a key for the recipient is likewise protocol-specific. 320 For an example specification that uses the mechanisms defined in this 321 document, see [I-D.ietf-oauth-pop-architecture]. 323 4. Security Considerations 325 All of the normal security issues, especially in relationship to 326 comparing URIs and dealing with unrecognized values, that are 327 discussed in JWT [JWT] also apply here. 329 In addition, proof-of-possession introduces its own unique security 330 issues. Possessing the key is only valuable if it is kept secret. 331 Appropriate means must be used to ensure that unintended parties do 332 not learn the private key or symmetric key value. 334 Proof-of-possession via encrypted symmetric secrets is subject to 335 replay attacks. This attack can be avoided when a signed nonce or 336 challenge is used, since the recipient can use a distinct nonce or 337 challenged for each interaction. 339 Similarly to other information included in a JWT, it is necessary to 340 apply data origin authentication and integrity protection (via a 341 keyed message digest or a digital signature). Data origin 342 authentication ensures that the recipient of the JWT learns about the 343 entity that created the JWT, since this will be important for any 344 policy decisions. Integrity protection prevents an adversary from 345 changing any elements conveyed within the JWT payload. Special care 346 has to be applied when carrying symmetric keys inside the JWT, since 347 those not only require integrity protection, but also confidentiality 348 protection. 350 A recipient may not understand the newly introduced "cnf" claim and 351 may consequently treat it as a bearer token. While this is a 352 legitimate concern, it is outside the scope of this specification, 353 since demonstration the possession of the key associated with the 354 "cnf" claim is not covered by this specification. For more details, 355 please consult [I-D.ietf-oauth-pop-architecture]. 357 5. IANA Considerations 359 The following registration procedure is used for all the registries 360 established by this specification. 362 Values are registered with a Specification Required [RFC5226] after a 363 three-week review period on the [TBD]@ietf.org mailing list, on the 364 advice of one or more Designated Experts. However, to allow for the 365 allocation of values prior to publication, the Designated Expert(s) 366 may approve registration once they are satisfied that such a 367 specification will be published. 369 Registration requests must be sent to the [TBD]@ietf.org mailing list 370 for review and comment, with an appropriate subject (e.g., "Request 371 for access token type: example"). [[ Note to the RFC Editor: The name 372 of the mailing list should be determined in consultation with the 373 IESG and IANA. Suggested name: oauth-pop-reg-review@ietf.org. ]] 375 Within the review period, the Designated Expert(s) will either 376 approve or deny the registration request, communicating this decision 377 to the review list and IANA. Denials should include an explanation 378 and, if applicable, suggestions as to how to make the request 379 successful. Registration requests that are undetermined for a period 380 longer than 21 days can be brought to the IESG's attention (using the 381 iesg@ietf.org mailing list) for resolution. 383 Criteria that should be applied by the Designated Expert(s) includes 384 determining whether the proposed registration duplicates existing 385 functionality, determining whether it is likely to be of general 386 applicability or whether it is useful only for a single application, 387 and whether the registration makes sense. 389 IANA must only accept registry updates from the Designated Expert(s) 390 and should direct all requests for registration to the review mailing 391 list. 393 It is suggested that multiple Designated Experts be appointed who are 394 able to represent the perspectives of different applications using 395 this specification, in order to enable broadly-informed review of 396 registration decisions. In cases where a registration decision could 397 be perceived as creating a conflict of interest for a particular 398 Expert, that Expert should defer to the judgment of the other 399 Expert(s). 401 5.1. JSON Web Token Claims Registration 403 This specification registers the "cnf" claim in the IANA JSON Web 404 Token Claims registry defined in [JWT]. 406 5.1.1. Registry Contents 408 o Claim Name: "cnf" 409 o Claim Description: Confirmation 410 o Change Controller: IESG 411 o Specification Document(s): Section 3.4 of this document 413 5.2. JWT Confirmation Methods Registry 415 This specification establishes the IANA JWT Confirmation Methods 416 registry for JWT "cnf" member values. The registry records the 417 confirmation method member and a reference to the specification that 418 defines it. 420 5.2.1. Registration Template 422 Confirmation Method Value: 423 The name requested (e.g., "example"). Because a core goal of this 424 specification is for the resulting representations to be compact, 425 it is RECOMMENDED that the name be short -- not to exceed 8 426 characters without a compelling reason to do so. This name is 427 case-sensitive. Names may not match other registered names in a 428 case-insensitive manner unless the Designated Expert(s) state that 429 there is a compelling reason to allow an exception in this 430 particular case. 432 Confirmation Method Description: 433 Brief description of the confirmation method (e.g., "Example 434 description"). 436 Change Controller: 437 For Standards Track RFCs, state "IESG". For others, give the name 438 of the responsible party. Other details (e.g., postal address, 439 email address, home page URI) may also be included. 441 Specification Document(s): 442 Reference to the document(s) that specify the parameter, 443 preferably including URI(s) that can be used to retrieve copies of 444 the document(s). An indication of the relevant sections may also 445 be included but is not required. 447 5.2.2. Initial Registry Contents 449 o Confirmation Method Value: "jwk" 450 o Confirmation Method Description: JSON Web Key or Encrypted JSON 451 Web Key 452 o Change Controller: IESG 453 o Specification Document(s): Section 3.1 of [[ this document ]] 454 o Confirmation Method Value: "kid" 455 o Confirmation Method Description: Key Identifier 456 o Change Controller: IESG 457 o Specification Document(s): Section 3.3 of [[ this document ]] 459 6. References 461 6.1. Normative References 463 [JWE] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 464 draft-ietf-jose-json-web-encryption (work in progress), 465 January 2015. 467 [JWK] Jones, M., "JSON Web Key (JWK)", 468 draft-ietf-jose-json-web-key (work in progress), 469 January 2015. 471 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 472 (JWT)", draft-ietf-oauth-json-web-token (work in 473 progress), December 2014. 475 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 476 Requirement Levels", BCP 14, RFC 2119, March 1997. 478 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 479 10646", STD 63, RFC 3629, November 2003. 481 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 482 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 483 May 2008. 485 6.2. Informative References 487 [I-D.ietf-oauth-pop-architecture] 488 Hunt, P., ietf@justin.richer.org, i., Mills, W., Mishra, 489 P., and H. Tschofenig, "OAuth 2.0 Proof-of-Possession 490 (PoP) Security Architecture", 491 draft-ietf-oauth-pop-architecture-01 (work in progress), 492 March 2015. 494 [OASIS.saml-core-2.0-os] 495 Cantor, S., Kemp, J., Philpott, R., and E. Maler, 496 "Assertions and Protocol for the OASIS Security Assertion 497 Markup Language (SAML) V2.0", OASIS Standard saml-core- 498 2.0-os, March 2005. 500 Appendix A. Acknowledgements 502 The authors wish to thank James Manger for his review of the 503 specification. 505 Appendix B. Document History 507 [[ to be removed by the RFC Editor before publication as an RFC ]] 509 -02 511 o Defined the terms Issuer, Presenter, and Recipient and updated 512 their usage within the document. 514 o Added a description of a use case using an asymmetric proof-of- 515 possession key to the introduction. 517 o Added the "kid" (key ID) confirmation method. 519 o These changes address the open issues identified in the previous 520 draft. 522 -01 524 o Updated references. 526 -00 528 o Created the initial working group draft from 529 draft-jones-oauth-proof-of-possession-02. 531 Authors' Addresses 533 Michael B. Jones 534 Microsoft 536 Email: mbj@microsoft.com 537 URI: http://self-issued.info/ 539 John Bradley 540 Ping Identity 542 Email: ve7jtb@ve7jtb.com 543 URI: http://www.thread-safe.com/ 544 Hannes Tschofenig 545 ARM Limited 546 Austria 548 Email: Hannes.Tschofenig@gmx.net 549 URI: http://www.tschofenig.priv.at