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/