--- 1/draft-ietf-oauth-proof-of-possession-05.txt 2015-11-04 07:15:48.185273332 -0800 +++ 2/draft-ietf-oauth-proof-of-possession-06.txt 2015-11-04 07:15:48.221274215 -0800 @@ -1,21 +1,21 @@ OAuth Working Group M. Jones Internet-Draft Microsoft Intended status: Standards Track J. Bradley -Expires: April 21, 2016 Ping Identity +Expires: May 7, 2016 Ping Identity H. Tschofenig ARM Limited - October 19, 2015 + November 4, 2015 Proof-of-Possession Key Semantics for JSON Web Tokens (JWTs) - draft-ietf-oauth-proof-of-possession-05 + draft-ietf-oauth-proof-of-possession-06 Abstract This specification defines how to express a declaration in a JSON Web Token (JWT) that the presenter of the JWT possesses a particular key and that the recipient can cryptographically confirm proof-of- possession of the key by the presenter. Being able to prove possession of a key is also sometimes described as the presenter being a holder-of-key. @@ -27,116 +27,172 @@ Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." - This Internet-Draft will expire on April 21, 2016. + This Internet-Draft will expire on May 7, 2016. Copyright Notice Copyright (c) 2015 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 - 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 4 - 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 - 3. Representations for Proof-of-Possession Keys . . . . . . . . . 4 - 3.1. Confirmation Claim . . . . . . . . . . . . . . . . . . . . 5 - 3.2. Representation of an Asymmetric Proof-of-Possession Key . 6 + 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 5 + 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 + 3. Representations for Proof-of-Possession Keys . . . . . . . . . 6 + 3.1. Confirmation Claim . . . . . . . . . . . . . . . . . . . . 6 + 3.2. Representation of an Asymmetric Proof-of-Possession Key . 7 3.3. Representation of an Encrypted Symmetric - Proof-of-Possession Key . . . . . . . . . . . . . . . . . 6 + Proof-of-Possession Key . . . . . . . . . . . . . . . . . 7 3.4. Representation of a Key ID for a Proof-of-Possession - Key . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 - 3.5. Representation of a URL for a Proof-of-Possession Key . . 8 - 3.6. Specifics Intentionally Not Specified . . . . . . . . . . 8 - 4. Security Considerations . . . . . . . . . . . . . . . . . . . 9 - 5. Privacy Considerations . . . . . . . . . . . . . . . . . . . . 10 - 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 - 6.1. JSON Web Token Claims Registration . . . . . . . . . . . . 11 - 6.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 11 - 6.2. JWT Confirmation Methods Registry . . . . . . . . . . . . 11 - 6.2.1. Registration Template . . . . . . . . . . . . . . . . 11 - 6.2.2. Initial Registry Contents . . . . . . . . . . . . . . 12 - 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 12 - 7.1. Normative References . . . . . . . . . . . . . . . . . . . 12 - 7.2. Informative References . . . . . . . . . . . . . . . . . . 13 - Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 14 - Appendix B. Document History . . . . . . . . . . . . . . . . . . 14 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 15 + Key . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 + 3.5. Representation of a URL for a Proof-of-Possession Key . . 9 + 3.6. Specifics Intentionally Not Specified . . . . . . . . . . 9 + 4. Security Considerations . . . . . . . . . . . . . . . . . . . 10 + 5. Privacy Considerations . . . . . . . . . . . . . . . . . . . . 11 + 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 + 6.1. JSON Web Token Claims Registration . . . . . . . . . . . . 12 + 6.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 12 + 6.2. JWT Confirmation Methods Registry . . . . . . . . . . . . 12 + 6.2.1. Registration Template . . . . . . . . . . . . . . . . 12 + 6.2.2. Initial Registry Contents . . . . . . . . . . . . . . 13 + 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 13 + 7.1. Normative References . . . . . . . . . . . . . . . . . . . 13 + 7.2. Informative References . . . . . . . . . . . . . . . . . . 14 + Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 15 + Appendix B. Document History . . . . . . . . . . . . . . . . . . 15 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 16 1. Introduction This specification defines how a JSON Web Token (JWT) [JWT] can declare that the presenter of the JWT possesses a key and that the recipient can cryptographically confirm that the presenter possesses that key. Proof-of-possession of a key is also sometimes described as the presenter being a holder-of-key. The [I-D.ietf-oauth-pop-architecture] specification describes key confirmation, among other confirmation mechanisms. This specification defines how to communicate key confirmation key information in JWTs. - Envision the following two use cases. The first use case describes - the use of a symmetric proof-of-possession key and the second use - case uses an asymmetric proof-of-possession key. + Envision the following two use cases. The first use case employs a + symmetric proof-of-possession key and the second use case employs an + asymmetric proof-of-possession key. - An issuer generates a JWT and places an encrypted symmetric key - inside the newly introduced confirmation claim. This symmetric key - is encrypted with a key known only to the issuer and the recipient. - The entire JWT is then integrity protected by the issuer. The JWT is - then sent to the presenter. Since the presenter is unable to obtain - the encrypted symmetric key from the JWT itself, the issuer conveys - that symmetric key separately to the presenter. Now, the presenter - is in possession of the symmetric key as well as the JWT (which - includes the confirmation claim member). When the presenter needs to - present the JWT to the recipient, it also needs to demonstrate - possession of the symmetric key; the presenter, for example, uses the - symmetric key in a challenge/response protocol with the recipient. - The recipient is then able to verify that it is interacting with the - genuine presenter by decrypting the JWK contained inside the + +--------------+ + | | +--------------+ + | |--(4) Presentation of -->| | + | | JWT w/ Encrypted | | + | Presenter | PoP Key | | + | | | | + | |<-(5) Communication ---->| | + | | Authenticated by | | + +--------------+ PoP Key | | + | ^ | | + | | | | + (1) Sym. (3) JWT w/ | Recipient | + | PoP | Encrypted | | + | Key | PoP Key | | + v | | | + +--------------+ | | + | | | | + | | | | + | |<-(2) Key Exchange for ->| | + | Issuer | Key Encryption Key | | + | | | | + | | | | + | | +--------------+ + +--------------+ + + Figure 1: Proof-of-Possession with a Symmetric Key + + In the case illustrated in Figure 1, the presenter generates a + symmetric key and (1) privately sends it to the issuer. The issuer + generates a JWT with an encrypted copy of this symmetric key in the + newly introduced confirmation claim. This symmetric key is encrypted + with a key known only to the issuer and the recipient, which is + established in step (2), if it doesn't already exist. The entire JWT + is integrity protected by the issuer. The JWT is then (3) sent to + the presenter. Now, the presenter is in possession of the symmetric + key as well as the JWT (which includes the confirmation claim). When + the presenter (4) presents the JWT to the recipient, it also needs to + demonstrate possession of the symmetric key; the presenter, for + example, (5) uses the symmetric key in a challenge/response protocol + with the recipient. The recipient is then able to verify that it is + interacting with the genuine presenter by decrypting the key in the confirmation claim of the JWT. By doing this, the recipient obtains the symmetric key, which it then uses to verify cryptographically - protected messages exchanged with the presenter. This symmetric key - mechanism described above is conceptually similar to the use of + protected messages exchanged with the presenter (5). This symmetric + key mechanism described above is conceptually similar to the use of Kerberos tickets. - In the second case, consider a presenter that generates a public/ - private key pair. It then sends the public key to an issuer, which - creates a JWT and places a public key (or an identifier for it) - inside the newly introduced confirmation claim. The entire JWT is - integrity protected using a digital signature to protect it against - modifications. The JWT is then sent to the presenter. When the - presenter needs to present the JWT to the recipient, it also needs to - demonstrate possession of the private key. The presenter, for - example, uses the private key in a TLS exchange with the recipient or - signs a nonce with the private key. The recipient is able to verify - that it is interacting with the genuine presenter by extracting the - public key from the confirmation claim of the JWT (after verifying - the digital signature of the JWT) and utilizing it with the private - key in the TLS exchange or checking the nonce signature. + +--------------+ + | | +--------------+ + | |--(3) Presentation of -->| | + | | JWT w/ Public | | + | Presenter | PoP Key | | + | | | | + | |<-(4) Communication ---->| | + | | Authenticated by | | + +--------------+ PoP Key | | + | ^ | | + | | | | + (1) Public (2) JWT w/ | Recipient | + | PoP | Public | | + | Key | PoP Key | | + v | | | + +--------------+ | | + | | | | + | | | | + | | | | + | Issuer | | | + | | | | + | | | | + | | +--------------+ + +--------------+ + + Figure 2: Proof-of-Possession with an Asymmetric Key + + In the case illustrated in Figure 2, the presenter generates a + public/private key pair and (1) sends the public key to the issuer, + which creates a JWT that contains the public key (or an identifier + for it) in the newly introduced confirmation claim. The entire JWT + is integrity protected using a digital signature to protect it + against modifications. The JWT is then (2) sent to the presenter. + + When the presenter (3) presents the JWT to the recipient, it also + needs to demonstrate possession of the private key. The presenter, + for example, (4) uses the private key in a TLS exchange with the + recipient or (4) signs a nonce with the private key. The recipient + is able to verify that it is interacting with the genuine presenter + by extracting the public key from the confirmation claim of the JWT + (after verifying the digital signature of the JWT) and utilizing it + with the private key in the TLS exchange or by checking the nonce + signature. In both cases, the JWT may contain other claims that are needed by the application. 1.1. Notational Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119]. @@ -605,20 +661,24 @@ Appendix A. Acknowledgements The authors wish to thank Brian Campbell, Kepeng Li, James Manger, Justin Richer, and Nat Sakimura for their reviews of the specification. Appendix B. Document History [[ to be removed by the RFC Editor before publication as an RFC ]] + -06 + + o Added diagrams to the introduction. + -05 o Addressed review comments by Kepeng Li. -04 o Allowed the use of "jwk" for symmetric keys when the JWT is encrypted. o Added the "jku" (JWK Set URL) member.