draft-ietf-oauth-proof-of-possession-09.txt   draft-ietf-oauth-proof-of-possession-10.txt 
OAuth Working Group M. Jones OAuth Working Group M. Jones
Internet-Draft Microsoft Internet-Draft Microsoft
Intended status: Standards Track J. Bradley Intended status: Standards Track J. Bradley
Expires: June 15, 2016 Ping Identity Expires: June 18, 2016 Ping Identity
H. Tschofenig H. Tschofenig
ARM Limited ARM Limited
December 13, 2015 December 16, 2015
Proof-of-Possession Key Semantics for JSON Web Tokens (JWTs) Proof-of-Possession Key Semantics for JSON Web Tokens (JWTs)
draft-ietf-oauth-proof-of-possession-09 draft-ietf-oauth-proof-of-possession-10
Abstract Abstract
This specification defines how to express a declaration in a JSON Web This specification defines how to declare in a JSON Web Token (JWT)
Token (JWT) that the presenter of the JWT possesses a particular key that the presenter of the JWT possesses a particular proof-of-
and that the recipient can cryptographically confirm proof-of- possession key and that the recipient can cryptographically confirm
possession of the key by the presenter. Being able to prove proof-of-possession of the key by the presenter. Being able to prove
possession of a key is also sometimes described as the presenter possession of a key is also sometimes described as the presenter
being a holder-of-key. being a holder-of-key.
Status of this Memo Status of this Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on June 15, 2016. This Internet-Draft will expire on June 18, 2016.
Copyright Notice Copyright Notice
Copyright (c) 2015 IETF Trust and the persons identified as the Copyright (c) 2015 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 31 skipping to change at page 2, line 31
3.5. Representation of a URL for a Proof-of-Possession Key . . 9 3.5. Representation of a URL for a Proof-of-Possession Key . . 9
3.6. Specifics Intentionally Not Specified . . . . . . . . . . 10 3.6. Specifics Intentionally Not Specified . . . . . . . . . . 10
4. Security Considerations . . . . . . . . . . . . . . . . . . . 10 4. Security Considerations . . . . . . . . . . . . . . . . . . . 10
5. Privacy Considerations . . . . . . . . . . . . . . . . . . . . 11 5. Privacy Considerations . . . . . . . . . . . . . . . . . . . . 11
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11
6.1. JSON Web Token Claims Registration . . . . . . . . . . . . 12 6.1. JSON Web Token Claims Registration . . . . . . . . . . . . 12
6.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 12 6.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 12
6.2. JWT Confirmation Methods Registry . . . . . . . . . . . . 12 6.2. JWT Confirmation Methods Registry . . . . . . . . . . . . 12
6.2.1. Registration Template . . . . . . . . . . . . . . . . 12 6.2.1. Registration Template . . . . . . . . . . . . . . . . 12
6.2.2. Initial Registry Contents . . . . . . . . . . . . . . 13 6.2.2. Initial Registry Contents . . . . . . . . . . . . . . 13
7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 14 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 13
7.1. Normative References . . . . . . . . . . . . . . . . . . . 14 7.1. Normative References . . . . . . . . . . . . . . . . . . . 13
7.2. Informative References . . . . . . . . . . . . . . . . . . 15 7.2. Informative References . . . . . . . . . . . . . . . . . . 14
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 15 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 15
Appendix B. Document History . . . . . . . . . . . . . . . . . . 15 Appendix B. Document History . . . . . . . . . . . . . . . . . . 15
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 17 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 17
1. Introduction 1. Introduction
This specification defines how a JSON Web Token (JWT) [JWT] can This specification defines how a JSON Web Token [JWT] can declare
declare that the presenter of the JWT possesses a key and that the that the presenter of the JWT possesses a particular proof-of-
recipient can cryptographically confirm that the presenter possesses possession key and that the recipient can cryptographically confirm
that key. Proof-of-possession of a key is also sometimes described proof-of-possession of the key by the presenter. Proof-of-possession
as the presenter being a holder-of-key. The of a key is also sometimes described as the presenter being a holder-
[I-D.ietf-oauth-pop-architecture] specification describes key of-key. The [I-D.ietf-oauth-pop-architecture] specification
confirmation, among other confirmation mechanisms. This describes key confirmation, among other confirmation mechanisms.
specification defines how to communicate key confirmation key This specification defines how to communicate key confirmation key
information in JWTs. information in JWTs.
Envision the following two use cases. The first use case employs a Envision the following two use cases. The first use case employs a
symmetric proof-of-possession key and the second use case employs an symmetric proof-of-possession key and the second use case employs an
asymmetric proof-of-possession key. asymmetric proof-of-possession key.
+--------------+ +--------------+
| | +--------------+ | | +--------------+
| |--(3) Presentation of -->| | | |--(3) Presentation of -->| |
| | JWT w/ Encrypted | | | | JWT w/ Encrypted | |
skipping to change at page 5, line 30 skipping to change at page 5, line 30
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in RFC "OPTIONAL" in this document are to be interpreted as described in RFC
2119 [RFC2119]. 2119 [RFC2119].
Unless otherwise noted, all the protocol parameter names and values Unless otherwise noted, all the protocol parameter names and values
are case sensitive. are case sensitive.
2. Terminology 2. Terminology
This specification uses terms defined in the JSON Web Token (JWT) This specification uses terms defined in the JSON Web Token [JWT],
[JWT], JSON Web Key (JWK) [JWK], and JSON Web Encryption (JWE) [JWE] JSON Web Key [JWK], and JSON Web Encryption [JWE] specifications.
specifications.
These terms are defined by this specification: These terms are defined by this specification:
Issuer Issuer
Party that creates the JWT and binds the proof-of-possession key Party that creates the JWT and binds the proof-of-possession key
to it. to it.
Presenter Presenter
Party that proves possession of a private key (for asymmetric key Party that proves possession of a private key (for asymmetric key
cryptography) or secret key (for symmetric key cryptography) to a cryptography) or secret key (for symmetric key cryptography) to a
recipient. recipient.
Recipient Recipient
Party that receives the JWT containing the proof-of-possession key Party that receives the JWT containing the proof-of-possession key
information from the presenter. information from the presenter.
3. Representations for Proof-of-Possession Keys 3. Representations for Proof-of-Possession Keys
The issuer of a JWT declares that the presenter possesses a By including a "cnf" (confirmation) claim in a JWT, the issuer of the
particular key and that the recipient can cryptographically confirm JWT declares that the presenter possesses a particular key, and that
proof-of-possession of the key by the presenter by including a "cnf" the recipient can cryptographically confirm that the presenter has
(confirmation) claim in the JWT whose value is a JSON object. possession of that key. The value of the "cnf" claim is a JSON
Members in the JSON object identify the proof-of-possession key. object and the members of that object identify the proof-of-
possession key.
The presenter can be identified in one of several ways by the JWT, The presenter can be identified in one of several ways by the JWT,
depending upon the application requirements. If the JWT contains a depending upon the application requirements. If the JWT contains a
"sub" (subject) claim [JWT], the presenter is normally the subject "sub" (subject) claim [JWT], the presenter is normally the subject
identified by the JWT. (In some applications, the subject identifier identified by the JWT. (In some applications, the subject identifier
will be relative to the issuer identified by the "iss" (issuer) claim will be relative to the issuer identified by the "iss" (issuer) claim
[JWT].) If the JWT contains no "sub" (subject) claim, the presenter [JWT].) If the JWT contains no "sub" (subject) claim, the presenter
is normally the issuer identified by the JWT using the "iss" (issuer) is normally the issuer identified by the JWT using the "iss" (issuer)
claim. The case in which the presenter is the subject of the JWT is claim. The case in which the presenter is the subject of the JWT is
analogous to SAML 2.0 [OASIS.saml-core-2.0-os] SubjectConfirmation analogous to SAML 2.0 [OASIS.saml-core-2.0-os] SubjectConfirmation
skipping to change at page 7, line 22 skipping to change at page 7, line 23
the same JWT, one way for it to achieve this is to use other claim the same JWT, one way for it to achieve this is to use other claim
names, in addition to "cnf", to hold the additional proof-of- names, in addition to "cnf", to hold the additional proof-of-
possession key information. These claims could use the same syntax possession key information. These claims could use the same syntax
and semantics as the "cnf" claim. Those claims would be defined by and semantics as the "cnf" claim. Those claims would be defined by
applications or other specifications and could be registered in the applications or other specifications and could be registered in the
IANA "JSON Web Token Claims" registry [IANA.JWT.Claims]. IANA "JSON Web Token Claims" registry [IANA.JWT.Claims].
3.2. Representation of an Asymmetric Proof-of-Possession Key 3.2. Representation of an Asymmetric Proof-of-Possession Key
When the key held by the presenter is an asymmetric private key, the When the key held by the presenter is an asymmetric private key, the
"jwk" member is a JSON Web Key (JWK) [JWK] representing the "jwk" member is a JSON Web Key [JWK] representing the corresponding
corresponding asymmetric public key. The following example asymmetric public key. The following example demonstrates such a
demonstrates such a declaration in the JWT Claims Set of a JWT: declaration in the JWT Claims Set of a JWT:
{ {
"iss": "https://server.example.com", "iss": "https://server.example.com",
"aud": "https://client.example.org", "aud": "https://client.example.org",
"exp": 1361398824, "exp": 1361398824,
"cnf":{ "cnf":{
"jwk":{ "jwk":{
"kty": "EC", "kty": "EC",
"use": "sig", "use": "sig",
"crv": "P-256", "crv": "P-256",
skipping to change at page 8, line 8 skipping to change at page 8, line 8
member. member.
The "jwk" member MAY also be used for a JWK representing a symmetric The "jwk" member MAY also be used for a JWK representing a symmetric
key, provided that the JWT is encrypted so that the key is not key, provided that the JWT is encrypted so that the key is not
revealed to unintended parties. If the JWT is not encrypted, the revealed to unintended parties. If the JWT is not encrypted, the
symmetric key MUST be encrypted as described below. symmetric key MUST be encrypted as described below.
3.3. Representation of an Encrypted Symmetric Proof-of-Possession Key 3.3. Representation of an Encrypted Symmetric Proof-of-Possession Key
When the key held by the presenter is a symmetric key, the "jwe" When the key held by the presenter is a symmetric key, the "jwe"
member is an encrypted JSON Web Key (JWK) [JWK] encrypted to a key member is an encrypted JSON Web Key [JWK] encrypted to a key known to
known to the recipient using the JWE Compact Serialization containing the recipient using the JWE Compact Serialization containing the
the symmetric key. The rules for encrypting a JWK are found in symmetric key. The rules for encrypting a JWK are found in Section 7
Section 7 of the JSON Web Key [JWK] specification. of the JSON Web Key [JWK] specification.
The following example illustrates a symmetric key that could The following example illustrates a symmetric key that could
subsequently be encrypted for use in the "jwe" member: subsequently be encrypted for use in the "jwe" member:
{ {
"kty": "oct", "kty": "oct",
"alg": "HS256", "alg": "HS256",
"k": "ZoRSOrFzN_FzUA5XKMYoVHyzff5oRJxl-IXRtztJ6uE" "k": "ZoRSOrFzN_FzUA5XKMYoVHyzff5oRJxl-IXRtztJ6uE"
} }
skipping to change at page 9, line 45 skipping to change at page 9, line 45
The proof-of-possession key can be passed by reference instead of The proof-of-possession key can be passed by reference instead of
being passed by value. This is done using the "jku" (JWK Set URL) being passed by value. This is done using the "jku" (JWK Set URL)
member. Its value is a URI [RFC3986] that refers to a resource for a member. Its value is a URI [RFC3986] that refers to a resource for a
set of JSON-encoded public keys represented as a JWK Set [JWK], one set of JSON-encoded public keys represented as a JWK Set [JWK], one
of which is the proof-of-possession key. If there are multiple keys of which is the proof-of-possession key. If there are multiple keys
in the referenced JWK Set document, a "kid" member MUST also be in the referenced JWK Set document, a "kid" member MUST also be
included, with the referenced key's JWK also containing the same included, with the referenced key's JWK also containing the same
"kid" value. "kid" value.
The protocol used to acquire the resource MUST provide integrity The protocol used to acquire the resource MUST provide integrity
protection; an HTTP GET request to retrieve the JWK Set MUST use protection. An HTTP GET request to retrieve the JWK Set MUST use
Transport Layer Security (TLS) [RFC5246]; and the identity of the Transport Layer Security (TLS) [RFC5246] and the identity of the
server MUST be validated, as per Section 6 of RFC 6125 [RFC6125]. server MUST be validated, as per Section 6 of RFC 6125 [RFC6125].
The following example demonstrates such a declaration in the JWT The following example demonstrates such a declaration in the JWT
Claims Set of a JWT: Claims Set of a JWT:
{ {
"iss": "https://server.example.com", "iss": "https://server.example.com",
"sub": "17760704", "sub": "17760704",
"aud": "https://client.example.org", "aud": "https://client.example.org",
"exp": 1440804813, "exp": 1440804813,
skipping to change at page 10, line 38 skipping to change at page 10, line 38
Note that another means of proving possession of the key when it is a Note that another means of proving possession of the key when it is a
symmetric key is to encrypt the key to the recipient. The means of symmetric key is to encrypt the key to the recipient. The means of
obtaining a key for the recipient is likewise protocol-specific. obtaining a key for the recipient is likewise protocol-specific.
For examples using the mechanisms defined in this specification, see For examples using the mechanisms defined in this specification, see
[I-D.ietf-oauth-pop-architecture]. [I-D.ietf-oauth-pop-architecture].
4. Security Considerations 4. Security Considerations
All of the security considerations that are discussed in JWT [JWT] All of the security considerations that are discussed in [JWT] also
also apply here. In addition, proof-of-possession introduces its own apply here. In addition, proof-of-possession introduces its own
unique security issues. Possessing a key is only valuable if it is unique security issues. Possessing a key is only valuable if it is
kept secret. Appropriate means must be used to ensure that kept secret. Appropriate means must be used to ensure that
unintended parties do not learn private key or symmetric key values. unintended parties do not learn private key or symmetric key values.
Proof-of-possession via encrypted symmetric secrets is subject to Proof-of-possession via encrypted symmetric secrets is subject to
replay attacks. This attack can be avoided when a signed nonce or replay attacks. This attack can be avoided when a signed nonce or
challenge is used, since the recipient can use a distinct nonce or challenge is used, since the recipient can use a distinct nonce or
challenge for each interaction. challenge for each interaction.
Similarly to other information included in a JWT, it is necessary to Similarly to other information included in a JWT, it is necessary to
skipping to change at page 11, line 18 skipping to change at page 11, line 18
has to be applied when carrying symmetric keys inside the JWT, since has to be applied when carrying symmetric keys inside the JWT, since
those not only require integrity protection, but also confidentiality those not only require integrity protection, but also confidentiality
protection. protection.
A recipient might not understand the "cnf" claim. Applications that A recipient might not understand the "cnf" claim. Applications that
require the proof-of-possession keys communicated with it to be require the proof-of-possession keys communicated with it to be
understood and processed must ensure that the parts of this understood and processed must ensure that the parts of this
specification that they use are implemented. specification that they use are implemented.
Applications utilizing proof-of-possession should also utilize Applications utilizing proof-of-possession should also utilize
audience restriction, as they provide different protections. Proof- audience restriction, as described in Section 4.1.3 of [JWT], as it
of-possession can be used by recipients to reject messages from provides different protections. Proof-of-possession can be used by
unauthorized senders. Audience restriction can be used by recipients recipients to reject messages from unauthorized senders. Audience
to reject messages intended for different recipients. restriction can be used by recipients to reject messages intended for
different recipients.
5. Privacy Considerations 5. Privacy Considerations
A proof-of-possession key can be used as a correlation handle if the A proof-of-possession key can be used as a correlation handle if the
same key is used with multiple parties. Thus, for privacy reasons, same key is used with multiple parties. Thus, for privacy reasons,
it is recommended that different proof-of-possession keys be used it is recommended that different proof-of-possession keys be used
when interacting with different parties. when interacting with different parties.
6. IANA Considerations 6. IANA Considerations
skipping to change at page 11, line 47 skipping to change at page 11, line 48
mailing list, on the advice of one or more Designated Experts. mailing list, on the advice of one or more Designated Experts.
However, to allow for the allocation of values prior to publication, However, to allow for the allocation of values prior to publication,
the Designated Experts may approve registration once they are the Designated Experts may approve registration once they are
satisfied that such a specification will be published. [[ Note to the satisfied that such a specification will be published. [[ Note to the
RFC Editor: The name of the mailing list should be determined in RFC Editor: The name of the mailing list should be determined in
consultation with the IESG and IANA. Suggested name: consultation with the IESG and IANA. Suggested name:
oauth-pop-reg-review@ietf.org. ]] oauth-pop-reg-review@ietf.org. ]]
Registration requests sent to the mailing list for review should use Registration requests sent to the mailing list for review should use
an appropriate subject (e.g., "Request to register JWT Confirmation an appropriate subject (e.g., "Request to register JWT Confirmation
Method: example"). Method: example"). Registration requests that are undetermined for a
period longer than 21 days can be brought to the IESG's attention
Within the review period, the Designated Experts will either approve (using the iesg@ietf.org mailing list) for resolution.
or deny the registration request, communicating this decision to the
review list and IANA. Denials should include an explanation and, if
applicable, suggestions as to how to make the request successful.
Registration requests that are undetermined for a period longer than
21 days can be brought to the IESG's attention (using the
iesg@ietf.org mailing list) for resolution.
Criteria that should be applied by the Designated Experts includes Criteria that should be applied by the Designated Experts include
determining whether the proposed registration duplicates existing determining whether the proposed registration duplicates existing
functionality, determining whether it is likely to be of general functionality, determining whether it is likely to be of general
applicability or whether it is useful only for a single application, applicability or whether it is useful only for a single application,
and whether the registration makes sense. and whether the registration makes sense.
IANA must only accept registry updates from the Designated Experts
and should direct all requests for registration to the review mailing
list.
It is suggested that multiple Designated Experts be appointed who are It is suggested that multiple Designated Experts be appointed who are
able to represent the perspectives of different applications using able to represent the perspectives of different applications using
this specification, in order to enable broadly-informed review of this specification, in order to enable broadly-informed review of
registration decisions. In cases where a registration decision could registration decisions. In cases where a registration decision could
be perceived as creating a conflict of interest for a particular be perceived as creating a conflict of interest for a particular
Expert, that Expert should defer to the judgment of the other Expert, that Expert should defer to the judgment of the other
Experts. Experts.
6.1. JSON Web Token Claims Registration 6.1. JSON Web Token Claims Registration
skipping to change at page 15, line 41 skipping to change at page 15, line 32
Appendix A. Acknowledgements Appendix A. Acknowledgements
The authors wish to thank Brian Campbell, Kepeng Li, James Manger, The authors wish to thank Brian Campbell, Kepeng Li, James Manger,
Kathleen Moriarty, Justin Richer, and Nat Sakimura for their reviews Kathleen Moriarty, Justin Richer, and Nat Sakimura for their reviews
of the specification. of the specification.
Appendix B. Document History Appendix B. Document History
[[ to be removed by the RFC Editor before publication as an RFC ]] [[ to be removed by the RFC Editor before publication as an RFC ]]
-10
o Addressed review comments by Barry Leiba.
-09 -09
o Removed erroneous quotation marks around numeric "exp" claim o Removed erroneous quotation marks around numeric "exp" claim
values in examples. values in examples.
-08 -08
o Added security consideration about also utilizing audience o Added security consideration about also utilizing audience
restriction. restriction.
 End of changes. 18 change blocks. 
56 lines changed or deleted 51 lines changed or added

This html diff was produced by rfcdiff 1.42. The latest version is available from http://tools.ietf.org/tools/rfcdiff/