idnits 2.17.1 draft-ietf-oauth-proof-of-possession-03.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 6, 2015) is 3217 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) == Missing Reference: 'RFC 7519' is mentioned on line 536, but not defined ** 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 (~~), 3 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: January 7, 2016 Ping Identity 6 H. Tschofenig 7 ARM Limited 8 July 6, 2015 10 Proof-of-Possession Key Semantics for JSON Web Tokens (JWTs) 11 draft-ietf-oauth-proof-of-possession-03 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 7, 2016. 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. Representations for Proof-of-Possession Keys . . . . . . . . . 4 59 3.1. Representation for an Asymmetric Proof-of-Possession 60 Key . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 61 3.2. Representation for an Encrypted Symmetric 62 Proof-of-Possession Key . . . . . . . . . . . . . . . . . 5 63 3.3. Representation of a Key ID for a Proof-of-Possession 64 Key . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 65 3.4. Confirmation . . . . . . . . . . . . . . . . . . . . . . . 7 66 3.5. Specifics Intentionally Not Specified . . . . . . . . . . 7 67 4. Security Considerations . . . . . . . . . . . . . . . . . . . 8 68 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 69 5.1. JSON Web Token Claims Registration . . . . . . . . . . . . 9 70 5.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 10 71 5.2. JWT Confirmation Methods Registry . . . . . . . . . . . . 10 72 5.2.1. Registration Template . . . . . . . . . . . . . . . . 10 73 5.2.2. Initial Registry Contents . . . . . . . . . . . . . . 10 74 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 75 6.1. Normative References . . . . . . . . . . . . . . . . . . . 11 76 6.2. Informative References . . . . . . . . . . . . . . . . . . 11 77 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 12 78 Appendix B. Document History . . . . . . . . . . . . . . . . . . 12 79 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 13 81 1. Introduction 83 This specification defines how to express a declaration in a JSON Web 84 Token (JWT) [JWT] that the presenter of the JWT possesses a 85 particular key and that the recipient can cryptographically confirm 86 proof-of-possession of the key by the presenter. This property is 87 also sometimes described as the presenter being a holder-of-key. 89 Envision the following two use cases. The first use case describes 90 the use of a symmetric proof-of-possession key and the second use 91 case uses an asymmetric proof-of-possession key. 93 An issuer generates a JWT and places an encrypted symmetric key 94 inside the newly introduced confirmation claim. This symmetric key 95 is encrypted with a key known only to the issuer and the recipient. 96 The entire JWT is then integrity protected by the issuer. The JWT is 97 then sent to the presenter. Since the presenter is unable to obtain 98 the encrypted symmetric key from the JWT itself, the issuer conveys 99 that symmetric key separately to the presenter. Now, the presenter 100 is in possession of the symmetric key as well as the JWT (which 101 includes the confirmation claim member). When the presenter needs to 102 present the JWT to the recipient, it also needs to demonstrate 103 possession of the symmetric key; the presenter, for example, uses the 104 symmetric key in a challenge/response protocol with the recipient. 105 The recipient is then able to verify that it is interacting with the 106 genuine presenter by decrypting the JWK contained inside the 107 confirmation claim of the JWT. By doing this, the recipient obtains 108 the symmetric key, which it then uses to verify cryptographically 109 protected messages exchanged with the presenter. This symmetric key 110 mechanism described above is conceptually similar to the use of 111 Kerberos tickets. 113 In the second case, consider a presenter that generates a public/ 114 private key pair. It then sends the public key to an issuer, which 115 creates a JWT and places a public key (or an identifier for it) 116 inside the newly introduced confirmation claim. The entire JWT is 117 integrity protected using a digital signature to protect it against 118 modifications. The JWT is then sent to the presenter. When the 119 presenter needs to present the JWT to the recipient, it also needs to 120 demonstrate possession of the private key. The presenter, for 121 example, uses the private key in a TLS exchange with the recipient or 122 signs a nonce with the private key. The recipient is able to verify 123 that it is interacting with the genuine presenter by extracting the 124 public key from the confirmation claim of the JWT (after verifying 125 the digital signature of the JWT) and utilizing it with the private 126 key in the TLS exchange or checking the nonce signature. 128 In both cases the JWT may contain other claims that are needed by the 129 application. 131 1.1. Notational Conventions 133 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 134 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 135 "OPTIONAL" in this document are to be interpreted as described in RFC 136 2119 [RFC2119]. 138 Unless otherwise noted, all the protocol parameter names and values 139 are case sensitive. 141 2. Terminology 143 This specification uses terms defined in the JSON Web Token (JWT) 144 [JWT], JSON Web Key (JWK) [JWK], and JSON Web Encryption (JWE) [JWE] 145 specifications. 147 These terms are defined by this specification: 149 Issuer 150 Party that creates the JWT and binds the proof-of-possession key 151 to it. 153 Presenter 154 Party that proves possession of a private key (for asymmetric key 155 cryptography) or secret key (for symmetric key cryptography) to a 156 recipient. The presenter may be the issuer or a party distinct 157 from the issuer. 159 Recipient 160 Party that receives the JWT containing the proof-of-possession key 161 information from the presenter. 163 3. Representations for Proof-of-Possession Keys 165 The issuer of a JWT declares that the presenter possesses a 166 particular key and that the recipient can cryptographically confirm 167 proof-of-possession of the key by the presenter by including a "cnf" 168 (confirmation) claim in the JWT whose value is a JSON object, with a 169 JSON object containing a "jwk" (JSON Web Key) member, a "jwe" (JSON 170 Web Encryption) member, or a "kid" (key ID) member identifying the 171 key. 173 The presenter can be identified in one of several ways by the JWT, 174 depending upon the application requirements. If the JWT contains a 175 "sub" (subject) claim, the presenter is normally the subject 176 identified by the JWT. (In some applications, the subject identifier 177 will be relative to the issuer identified by the "iss" (issuer) 178 claim.) If the JWT contains no "sub" (subject) claim, the presenter 179 is normally the issuer identified by the JWT using the "iss" (issuer) 180 claim. The case in which the presenter is the subject of the JWT is 181 analogous to SAML 2.0 [OASIS.saml-core-2.0-os] SubjectConfirmation 182 usage. At least one of the "sub" and "iss" claims MUST be present in 183 the JWT. Some use cases may require that both be present. 185 Another means used by some applications to identify the presenter is 186 an explicit claim, such as the "azp" (authorized party) claim defined 187 by OpenID Connect [OpenID.Core]. Ultimately, the means of 188 identifying the presenter is application-specific, as is the means of 189 confirming possession of the key that is communicated. 191 3.1. Representation for an Asymmetric Proof-of-Possession Key 193 When the key held by the presenter is an asymmetric private key, the 194 "jwk" member is a JSON Web Key (JWK) [JWK] representing the 195 corresponding asymmetric public key. The following example 196 demonstrates such a declaration in the JWT Claims Set of a JWT: 198 { 199 "iss": "https://server.example.com", 200 "aud": "https://client.example.org", 201 "exp": "1361398824", 202 "nbf": "1360189224", 203 "cnf":{ 204 "jwk":{ 205 "kty": "EC", 206 "use": "sig", 207 "crv": "P-256", 208 "x": "18wHLeIgW9wVN6VD1Txgpqy2LszYkMf6J8njVAibvhM", 209 "y": "-V4dS4UaLMgP_4fY4j8ir7cl1TXlFdAgcx55o7TkcSA" 210 } 211 } 212 } 214 The JWK MUST contain the required key members for a JWK of that key 215 type and MAY contain other JWK members, including the "kid" (key ID) 216 member. 218 3.2. Representation for an Encrypted Symmetric Proof-of-Possession Key 220 When the key held by the presenter is a symmetric key, the "jwe" 221 member is an encrypted JSON Web Key (JWK) [JWK] encrypted to a key 222 known to the recipient using the JWE Compact Serialization containing 223 the symmetric key. The rules for encrypting a JWK are found in 224 Section 7 of the JSON Web Key [JWK] specification. 226 The following example illustrates a symmetric key that could 227 subsequently be encrypted for use in the "jwe" member: 229 { 230 "kty": "oct", 231 "alg": "HS256", 232 "k": "ZoRSOrFzN_FzUA5XKMYoVHyzff5oRJxl-IXRtztJ6uE" 233 } 235 The UTF-8 [RFC3629] encoding of this JWK would be used as the JWE 236 Plaintext when encrypting the key. 238 The following example is a JWE Header that could be used when 239 encrypting this key: 241 { 242 "alg": "RSA1_5", 243 "enc": "A128CBC-HS256" 244 } 246 The following example JWT Claims Set of a JWT illustrates the use of 247 an encrypted symmetric key as the "jwe" member value: 249 { 250 "iss": "https://server.example.com", 251 "sub": "24400320", 252 "aud": "s6BhdRkqt3", 253 "nonce": "n-0S6_WzA2Mj", 254 "exp": 1311281970, 255 "iat": 1311280970, 256 "cnf":{ 257 "jwe": 258 "eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 259 (remainder of JWE omitted for brevity)" 260 } 261 } 263 3.3. Representation of a Key ID for a Proof-of-Possession Key 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 issuer of a JWT declares that the presenter possesses 269 a 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", "jwe", or "kid" member because a proof-of-possession key may 292 not be the only means of confirming the authenticity of the token. 293 This is 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 establishes the IANA "JWT Confirmation Methods" 300 registry for these members in Section 5.2 and registers the "jwk", 301 "jwe", and "kid" members within the registry. Other specifications 302 can register other members used for confirmation, including members 303 for conveying other proof-of-possession keys, possibly using 304 different key representations. 306 3.5. Specifics Intentionally Not Specified 308 Proof-of-possession is typically demonstrated by having the presenter 309 sign a value determined by the recipient using the key possessed by 310 the presenter. This value is sometimes called a "nonce" or a 311 "challenge". 313 The means of communicating the nonce and the nature of its contents 314 are intentionally not described in this specification, as different 315 protocols will communicate this information in different ways. 316 Likewise, the means of communicating the signed nonce is also not 317 specified, as this is also protocol-specific. 319 Note that another means of proving possession of the key when it is a 320 symmetric key is to encrypt the key to the recipient. The means of 321 obtaining a key for the recipient is likewise protocol-specific. 323 For an example specification that uses the mechanisms defined in this 324 document, see [I-D.ietf-oauth-pop-architecture]. 326 4. Security Considerations 328 All of the normal security issues, especially in relationship to 329 comparing URIs and dealing with unrecognized values, that are 330 discussed in JWT [JWT] also apply here. 332 In addition, proof-of-possession introduces its own unique security 333 issues. Possessing the key is only valuable if it is kept secret. 334 Appropriate means must be used to ensure that unintended parties do 335 not learn the private key or symmetric key value. 337 Proof-of-possession via encrypted symmetric secrets is subject to 338 replay attacks. This attack can be avoided when a signed nonce or 339 challenge is used, since the recipient can use a distinct nonce or 340 challenged for each interaction. 342 Similarly to other information included in a JWT, it is necessary to 343 apply data origin authentication and integrity protection (via a 344 keyed message digest or a digital signature). Data origin 345 authentication ensures that the recipient of the JWT learns about the 346 entity that created the JWT, since this will be important for any 347 policy decisions. Integrity protection prevents an adversary from 348 changing any elements conveyed within the JWT payload. Special care 349 has to be applied when carrying symmetric keys inside the JWT, since 350 those not only require integrity protection, but also confidentiality 351 protection. 353 A recipient may not understand the newly introduced "cnf" claim and 354 may consequently treat it as a bearer token. While this is a 355 legitimate concern, it is outside the scope of this specification, 356 since demonstration the possession of the key associated with the 357 "cnf" claim is not covered by this specification. For more details, 358 please consult [I-D.ietf-oauth-pop-architecture]. 360 5. IANA Considerations 362 The following registration procedure is used for all the registries 363 established by this specification. 365 Values are registered on a Specification Required [RFC5226] basis 366 after a three-week review period on the oauth-pop-reg-review@ietf.org 367 mailing list, on the advice of one or more Designated Experts. 368 However, to allow for the allocation of values prior to publication, 369 the Designated Experts may approve registration once they are 370 satisfied that such a specification will be published. [[ Note to the 371 RFC Editor: The name of the mailing list should be determined in 372 consultation with the IESG and IANA. Suggested name: 373 oauth-pop-reg-review@ietf.org. ]] 375 Registration requests sent to the mailing list for review should use 376 an appropriate subject (e.g., "Request to register JWT Confirmation 377 Method: example"). 379 Within the review period, the Designated Experts will either approve 380 or deny the registration request, communicating this decision to the 381 review list and IANA. Denials should include an explanation and, if 382 applicable, suggestions as to how to make the request successful. 383 Registration requests that are undetermined for a period longer than 384 21 days can be brought to the IESG's attention (using the 385 iesg@ietf.org mailing list) for resolution. 387 Criteria that should be applied by the Designated Experts includes 388 determining whether the proposed registration duplicates existing 389 functionality, determining whether it is likely to be of general 390 applicability or whether it is useful only for a single application, 391 and whether the registration makes sense. 393 IANA must only accept registry updates from the Designated Experts 394 and should direct all requests for registration to the review mailing 395 list. 397 It is suggested that multiple Designated Experts be appointed who are 398 able to represent the perspectives of different applications using 399 this specification, in order to enable broadly-informed review of 400 registration decisions. In cases where a registration decision could 401 be perceived as creating a conflict of interest for a particular 402 Expert, that Expert should defer to the judgment of the other 403 Experts. 405 5.1. JSON Web Token Claims Registration 407 This specification registers the "cnf" claim in the IANA JSON Web 408 Token Claims registry defined in [JWT]. 410 5.1.1. Registry Contents 412 o Claim Name: "cnf" 413 o Claim Description: Confirmation 414 o Change Controller: IESG 415 o Specification Document(s): Section 3.4 of this document 417 5.2. JWT Confirmation Methods Registry 419 This specification establishes the IANA "JWT Confirmation Methods" 420 registry for JWT "cnf" member values. The registry records the 421 confirmation method member and a reference to the specification that 422 defines it. 424 5.2.1. Registration Template 426 Confirmation Method Value: 427 The name requested (e.g., "kid"). Because a core goal of this 428 specification is for the resulting representations to be compact, 429 it is RECOMMENDED that the name be short -- not to exceed 8 430 characters without a compelling reason to do so. This name is 431 case-sensitive. Names may not match other registered names in a 432 case-insensitive manner unless the Designated Experts state that 433 there is a compelling reason to allow an exception. 435 Confirmation Method Description: 436 Brief description of the confirmation method (e.g., "Key 437 Identifier"). 439 Change Controller: 440 For Standards Track RFCs, list the "IESG". For others, give the 441 name of the responsible party. Other details (e.g., postal 442 address, email address, home page URI) may also be included. 444 Specification Document(s): 445 Reference to the document or documents that specify the parameter, 446 preferably including URIs that can be used to retrieve copies of 447 the documents. An indication of the relevant sections may also be 448 included but is not required. 450 5.2.2. Initial Registry Contents 452 o Confirmation Method Value: "jwk" 453 o Confirmation Method Description: JSON Web Key Representing Public 454 Key 455 o Change Controller: IESG 456 o Specification Document(s): Section 3.1 of [[ this document ]] 458 o Confirmation Method Value: "jwe" 459 o Confirmation Method Description: Encrypted JSON Web Key 460 o Change Controller: IESG 461 o Specification Document(s): Section 3.2 of [[ this document ]] 463 o Confirmation Method Value: "kid" 464 o Confirmation Method Description: Key Identifier 465 o Change Controller: IESG 466 o Specification Document(s): Section 3.3 of [[ this document ]] 468 6. References 470 6.1. Normative References 472 [JWE] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 473 RFC 7516, May 2015, 474 . 476 [JWK] Jones, M., "JSON Web Key (JWK)", RFC 7517, May 2015, 477 . 479 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 480 (JWT)", RFC 7519, May 2015, 481 . 483 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 484 Requirement Levels", BCP 14, RFC 2119, March 1997. 486 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 487 10646", STD 63, RFC 3629, November 2003. 489 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 490 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 491 May 2008. 493 6.2. Informative References 495 [I-D.ietf-oauth-pop-architecture] 496 Hunt, P., Richer, J., Mills, W., Mishra, P., and H. 497 Tschofenig, "OAuth 2.0 Proof-of-Possession (PoP) Security 498 Architecture", draft-ietf-oauth-pop-architecture-01 (work 499 in progress), March 2015. 501 [OASIS.saml-core-2.0-os] 502 Cantor, S., Kemp, J., Philpott, R., and E. Maler, 503 "Assertions and Protocol for the OASIS Security Assertion 504 Markup Language (SAML) V2.0", OASIS Standard saml-core- 505 2.0-os, March 2005. 507 [OpenID.Core] 508 Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 509 C. Mortimore, "OpenID Connect Core 1.0", November 2014, 510 . 512 Appendix A. Acknowledgements 514 The authors wish to thank Brian Campbell, James Manger, Justin 515 Richer, and Nat Sakimura for their reviews of the specification. 517 Appendix B. Document History 519 [[ to be removed by the RFC Editor before publication as an RFC ]] 521 -03 523 o Separated the "jwk" and "jwe" confirmation members; the former 524 represents a public key as a JWK and the latter represents a 525 symmetric key as a JWE encrypted JWK. 527 o Changed the title to indicate that a proof-of-possession key is 528 being communicated. 530 o Updated language that formerly assumed that the issuer was an 531 OAuth 2.0 authorization server. 533 o Described ways that applications can choose to identify the 534 presenter, including use of the "iss", "sub", and "azp" claims. 536 o Harmonized the registry language with that used in JWT [RFC 7519]. 538 o Addressed other issues identified during working group last call. 540 o Referenced the JWT and JOSE RFCs. 542 -02 544 o Defined the terms Issuer, Presenter, and Recipient and updated 545 their usage within the document. 547 o Added a description of a use case using an asymmetric proof-of- 548 possession key to the introduction. 550 o Added the "kid" (key ID) confirmation method. 552 o These changes address the open issues identified in the previous 553 draft. 555 -01 557 o Updated references. 559 -00 561 o Created the initial working group draft from 562 draft-jones-oauth-proof-of-possession-02. 564 Authors' Addresses 566 Michael B. Jones 567 Microsoft 569 Email: mbj@microsoft.com 570 URI: http://self-issued.info/ 572 John Bradley 573 Ping Identity 575 Email: ve7jtb@ve7jtb.com 576 URI: http://www.thread-safe.com/ 578 Hannes Tschofenig 579 ARM Limited 580 Austria 582 Email: Hannes.Tschofenig@gmx.net 583 URI: http://www.tschofenig.priv.at