< draft-ietf-jose-json-web-key-14.txt		draft-ietf-jose-json-web-key-15.txt >
	JOSE Working Group M. Jones		JOSE Working Group M. Jones
	Internet-Draft Microsoft		Internet-Draft Microsoft
	Intended status: Standards Track July 29, 2013		Intended status: Standards Track September 3, 2013
	Expires: January 30, 2014		Expires: March 7, 2014
	JSON Web Key (JWK)		JSON Web Key (JWK)
	draft-ietf-jose-json-web-key-14		draft-ietf-jose-json-web-key-15
	Abstract		Abstract
	A JSON Web Key (JWK) is a JavaScript Object Notation (JSON) data		A JSON Web Key (JWK) is a JavaScript Object Notation (JSON) data
	structure that represents a cryptographic key. This specification		structure that represents a cryptographic key. This specification
	also defines a JSON Web Key Set (JWK Set) JSON data structure for		also defines a JSON Web Key Set (JWK Set) JSON data structure for
	representing a set of JWKs. Cryptographic algorithms and identifiers		representing a set of JWKs. Cryptographic algorithms and identifiers
	for use with this specification are described in the separate JSON		for use with this specification are described in the separate JSON
	Web Algorithms (JWA) specification.		Web Algorithms (JWA) specification and IANA registries defined by
			that specification.
	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 January 30, 2014.		This Internet-Draft will expire on March 7, 2014.
	Copyright Notice		Copyright Notice
	Copyright (c) 2013 IETF Trust and the persons identified as the		Copyright (c) 2013 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 16 ¶		skipping to change at page 2, line 17 ¶
	Table of Contents		Table of Contents
	1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3		1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
	1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3		1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3
	2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3		2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
	3. JSON Web Key (JWK) Format . . . . . . . . . . . . . . . . . . 4		3. JSON Web Key (JWK) Format . . . . . . . . . . . . . . . . . . 4
	3.1. "kty" (Key Type) Parameter . . . . . . . . . . . . . . . . 4		3.1. "kty" (Key Type) Parameter . . . . . . . . . . . . . . . . 4
	3.2. "use" (Key Use) Parameter . . . . . . . . . . . . . . . . 5		3.2. "use" (Key Use) Parameter . . . . . . . . . . . . . . . . 5
	3.3. "alg" (Algorithm) Parameter . . . . . . . . . . . . . . . 5		3.3. "alg" (Algorithm) Parameter . . . . . . . . . . . . . . . 5
	3.4. "kid" (Key ID) Parameter . . . . . . . . . . . . . . . . . 5		3.4. "kid" (Key ID) Parameter . . . . . . . . . . . . . . . . . 5
	3.5. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . . . 5		3.5. "x5u" (X.509 URL) Parameter . . . . . . . . . . . . . . . 5
	3.6. "x5t" (X.509 Certificate Thumbprint) Header Parameter . . 6		3.6. "x5t" (X.509 Certificate Thumbprint) Parameter . . . . . . 6
	3.7. "x5c" (X.509 Certificate Chain) Parameter . . . . . . . . 6		3.7. "x5c" (X.509 Certificate Chain) Parameter . . . . . . . . 6
	4. JSON Web Key Set (JWK Set) Format . . . . . . . . . . . . . . 6		4. JSON Web Key Set (JWK Set) Format . . . . . . . . . . . . . . 6
	4.1. "keys" (JSON Web Key Set) Parameter . . . . . . . . . . . 6		4.1. "keys" (JSON Web Key Set) Parameter . . . . . . . . . . . 6
	5. String Comparison Rules . . . . . . . . . . . . . . . . . . . 7		5. String Comparison Rules . . . . . . . . . . . . . . . . . . . 7
	6. Encrypted JWK and Encrypted JWK Set Formats . . . . . . . . . 7		6. Encrypted JWK and Encrypted JWK Set Formats . . . . . . . . . 7
	7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7		7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7
	7.1. JSON Web Key Parameters Registry . . . . . . . . . . . . . 8		7.1. JSON Web Key Parameters Registry . . . . . . . . . . . . . 8
	7.1.1. Registration Template . . . . . . . . . . . . . . . . 8		7.1.1. Registration Template . . . . . . . . . . . . . . . . 8
	7.1.2. Initial Registry Contents . . . . . . . . . . . . . . 9		7.1.2. Initial Registry Contents . . . . . . . . . . . . . . 9
	7.2. JSON Web Key Set Parameters Registry . . . . . . . . . . . 9		7.2. JSON Web Key Set Parameters Registry . . . . . . . . . . . 9
	skipping to change at page 3, line 12 ¶		skipping to change at page 3, line 12 ¶
	Appendix D. Document History . . . . . . . . . . . . . . . . . . 19		Appendix D. Document History . . . . . . . . . . . . . . . . . . 19
	Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 22		Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 22
	1. Introduction		1. Introduction
	A JSON Web Key (JWK) is a JavaScript Object Notation (JSON) [RFC4627]		A JSON Web Key (JWK) is a JavaScript Object Notation (JSON) [RFC4627]
	data structure that represents a cryptographic key. This		data structure that represents a cryptographic key. This
	specification also defines a JSON Web Key Set (JWK Set) JSON data		specification also defines a JSON Web Key Set (JWK Set) JSON data
	structure for representing a set of JWKs. Cryptographic algorithms		structure for representing a set of JWKs. Cryptographic algorithms
	and identifiers for use with this specification are described in the		and identifiers for use with this specification are described in the
	separate JSON Web Algorithms (JWA) [JWA] specification.		separate JSON Web Algorithms (JWA) [JWA] specification and IANA
			registries defined by that specification.
	Goals for this specification do not include representing certificate		Goals for this specification do not include representing certificate
	chains, representing certified keys, and replacing X.509		chains, representing certified keys, and replacing X.509
	certificates.		certificates.
	JWKs and JWK Sets are used in the JSON Web Signature (JWS) [JWS] and		JWKs and JWK Sets are used in the JSON Web Signature (JWS) [JWS] and
	JSON Web Encryption (JWE) [JWE] specifications.		JSON Web Encryption (JWE) [JWE] specifications.
			Names defined by this specification are short because a core goal is
			for the resulting representations to be compact.
	1.1. Notational Conventions		1.1. Notational Conventions
	The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",		The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
	"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this		"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
	document are to be interpreted as described in Key words for use in		document are to be interpreted as described in Key words for use in
	RFCs to Indicate Requirement Levels [RFC2119].		RFCs to Indicate Requirement Levels [RFC2119].
	2. Terminology		2. Terminology
	JSON Web Key (JWK) A JSON object that represents a cryptographic		JSON Web Key (JWK) A JSON object that represents a cryptographic
	key.		key.
	JSON Web Key Set (JWK Set) A JSON object that contains an array of		JSON Web Key Set (JWK Set) A JSON object that contains an array of
	JWKs as the value of its "keys" member.		JWKs as the value of its "keys" member.
	Base64url Encoding The URL- and filename-safe Base64 encoding		Base64url Encoding Base64 encoding using the URL- and filename-safe
	described in RFC 4648 [RFC4648], Section 5, with the (non URL-		character set defined in Section 5 of RFC 4648 [RFC4648], with all
	safe) '=' padding characters omitted, as permitted by Section 3.2.		trailing '=' characters omitted (as permitted by Section 3.2).
	(See Appendix C of [JWS] for notes on implementing base64url		(See Appendix C of [JWS] for notes on implementing base64url
	encoding without padding.)		encoding without padding.)
	Collision Resistant Namespace A namespace that allows names to be		Collision Resistant Namespace A namespace that allows names to be
	allocated in a manner such that they are highly unlikely to		allocated in a manner such that they are highly unlikely to
	collide with other names. For instance, collision resistance can		collide with other names. Examples of Collision Resistant
	be achieved through administrative delegation of portions of the		Namespaces include: Domain Names, Object Identifiers (OIDs) as
	namespace or through use of collision-resistant name allocation		defined in the ITU-T X.660 and X.670 Recommendation series, and
	functions. Examples of Collision Resistant Namespaces include:		Universally Unique IDentifiers (UUIDs) [RFC4122]. When using an
	Domain Names, Object Identifiers (OIDs) as defined in the ITU-T		administratively delegated namespace, the definer of a name needs
	X.660 and X.670 Recommendation series, and Universally Unique		to take reasonable precautions to ensure they are in control of
	IDentifiers (UUIDs) [RFC4122]. When using an administratively		the portion of the namespace they use to define the name.
	delegated namespace, the definer of a name needs to take
	reasonable precautions to ensure they are in control of the
	portion of the namespace they use to define the name.
	Encrypted JWK A JWE with a JWK as its plaintext value.
	Encrypted JWK Set A JWE with a JWK Set as its plaintext value.
	3. JSON Web Key (JWK) Format		3. JSON Web Key (JWK) Format
	A JSON Web Key (JWK) is a JSON object containing specific members, as		A JSON Web Key (JWK) is a JSON object containing specific members, as
	specified below. Those members that are common to multiple key types		specified below. Those members that are common to multiple key types
	are defined below.		are defined below.
	In addition to the common parameters, each JWK will have members that		In addition to the common parameters, each JWK will have members that
	are specific to the kind of key being represented. These members		are specific to the kind of key being represented. These members
	represent the parameters of the key. Section 5 of the JSON Web		represent the parameters of the key. Section 5 of the JSON Web
	skipping to change at page 5, line 39 ¶		skipping to change at page 5, line 38 ¶
	The "kid" (key ID) member can be used to match a specific key. This		The "kid" (key ID) member can be used to match a specific key. This
	can be used, for instance, to choose among a set of keys within a JWK		can be used, for instance, to choose among a set of keys within a JWK
	Set during key rollover. The interpretation of the "kid" value is		Set during key rollover. The interpretation of the "kid" value is
	unspecified. When "kid" values are used within a JWK Set, different		unspecified. When "kid" values are used within a JWK Set, different
	keys within the JWK Set SHOULD use distinct "kid" values. The "kid"		keys within the JWK Set SHOULD use distinct "kid" values. The "kid"
	value is a case sensitive string. Use of this member is OPTIONAL.		value is a case sensitive string. Use of this member is OPTIONAL.
	When used with JWS or JWE, the "kid" value can be used to match a JWS		When used with JWS or JWE, the "kid" value can be used to match a JWS
	or JWE "kid" header parameter value.		or JWE "kid" header parameter value.
	3.5. "x5u" (X.509 URL) Header Parameter		3.5. "x5u" (X.509 URL) Parameter
	The "x5u" (X.509 URL) member is a URI [RFC3986] that refers to a		The "x5u" (X.509 URL) member is a URI [RFC3986] that refers to a
	resource for an X.509 public key certificate or certificate chain		resource for an X.509 public key certificate or certificate chain
	[RFC5280]. The identified resource MUST provide a representation of		[RFC5280]. The identified resource MUST provide a representation of
	the certificate or certificate chain that conforms to RFC 5280		the certificate or certificate chain that conforms to RFC 5280
	[RFC5280] in PEM encoded form [RFC1421]. The key in the first		[RFC5280] in PEM encoded form [RFC1421]. The key in the first
	certificate MUST match the bare public key represented by other		certificate MUST match the bare public key represented by other
	members of the JWK. The protocol used to acquire the resource MUST		members of the JWK. The protocol used to acquire the resource MUST
	provide integrity protection; an HTTP GET request to retrieve the		provide integrity protection; an HTTP GET request to retrieve the
	certificate MUST use TLS [RFC2818] [RFC5246]; the identity of the		certificate MUST use TLS [RFC2818] [RFC5246]; the identity of the
	server MUST be validated, as per Section 3.1 of HTTP Over TLS		server MUST be validated, as per Section 3.1 of HTTP Over TLS
	[RFC2818]. Use of this member is OPTIONAL.		[RFC2818]. Use of this member is OPTIONAL.
	3.6. "x5t" (X.509 Certificate Thumbprint) Header Parameter		3.6. "x5t" (X.509 Certificate Thumbprint) Parameter
	The "x5t" (X.509 Certificate Thumbprint) member is a base64url		The "x5t" (X.509 Certificate Thumbprint) member is a base64url
	encoded SHA-1 thumbprint (a.k.a. digest) of the DER encoding of an		encoded SHA-1 thumbprint (a.k.a. digest) of the DER encoding of an
	X.509 certificate [RFC5280]. The key in the certificate MUST match		X.509 certificate [RFC5280]. The key in the certificate MUST match
	the bare public key represented by other members of the JWK. Use of		the bare public key represented by other members of the JWK. Use of
	this member is OPTIONAL.		this member is OPTIONAL.
	3.7. "x5c" (X.509 Certificate Chain) Parameter		3.7. "x5c" (X.509 Certificate Chain) Parameter
	The "x5c" (X.509 Certificate Chain) member contains a chain of one or		The "x5c" (X.509 Certificate Chain) member contains a chain of one or
	skipping to change at page 12, line 20 ¶		skipping to change at page 12, line 20 ¶
	must be faced by a JWS/JWE/JWK agent. Among these issues are		must be faced by a JWS/JWE/JWK agent. Among these issues are
	protecting the user's private and symmetric keys, preventing various		protecting the user's private and symmetric keys, preventing various
	attacks, and helping the user avoid mistakes such as inadvertently		attacks, and helping the user avoid mistakes such as inadvertently
	encrypting a message for the wrong recipient. The entire list of		encrypting a message for the wrong recipient. The entire list of
	security considerations is beyond the scope of this document, but		security considerations is beyond the scope of this document, but
	some significant considerations are listed here.		some significant considerations are listed here.
	A key is no more trustworthy than the method by which it was		A key is no more trustworthy than the method by which it was
	received.		received.
	Private and symmetric keys must be protected from disclosure to		Private and symmetric keys MUST be protected from disclosure to
	unintended parties. One recommended means of doing so is to encrypt		unintended parties. One recommended means of doing so is to encrypt
	JWKs or JWK Sets containing them by using the JWK or JWK Set value as		JWKs or JWK Sets containing them by using the JWK or JWK Set value as
	the plaintext of a JWE.		the plaintext of a JWE.
	The security considerations in RFC 3447 [RFC3447] and RFC 6030		The security considerations in RFC 3447 [RFC3447] and RFC 6030
	[RFC6030] about protecting private and symmetric keys also apply to		[RFC6030] about protecting private and symmetric keys also apply to
	this specification.		this specification.
	The security considerations in XML DSIG 2.0		The security considerations in XML DSIG 2.0
	[W3C.CR-xmldsig-core2-20120124], about key representations also apply		[W3C.CR-xmldsig-core2-20120124], about key representations also apply
	skipping to change at page 13, line 7 ¶		skipping to change at page 13, line 7 ¶
	[ITU.X690.1994]		[ITU.X690.1994]
	International Telecommunications Union, "Information		International Telecommunications Union, "Information
	Technology - ASN.1 encoding rules: Specification of Basic		Technology - ASN.1 encoding rules: Specification of Basic
	Encoding Rules (BER), Canonical Encoding Rules (CER) and		Encoding Rules (BER), Canonical Encoding Rules (CER) and
	Distinguished Encoding Rules (DER)", ITU-T Recommendation		Distinguished Encoding Rules (DER)", ITU-T Recommendation
	X.690, 1994.		X.690, 1994.
	[JWA] Jones, M., "JSON Web Algorithms (JWA)",		[JWA] Jones, M., "JSON Web Algorithms (JWA)",
	draft-ietf-jose-json-web-algorithms (work in progress),		draft-ietf-jose-json-web-algorithms (work in progress),
	July 2013.		September 2013.
	[JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web		[JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web
	Encryption (JWE)", draft-ietf-jose-json-web-encryption		Encryption (JWE)", draft-ietf-jose-json-web-encryption
	(work in progress), July 2013.		(work in progress), September 2013.
	[JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web		[JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web
	Signature (JWS)", draft-ietf-jose-json-web-signature (work		Signature (JWS)", draft-ietf-jose-json-web-signature (work
	in progress), July 2013.		in progress), September 2013.
	[RFC1421] Linn, J., "Privacy Enhancement for Internet Electronic		[RFC1421] Linn, J., "Privacy Enhancement for Internet Electronic
	Mail: Part I: Message Encryption and Authentication		Mail: Part I: Message Encryption and Authentication
	Procedures", RFC 1421, February 1993.		Procedures", RFC 1421, February 1993.
	[RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail		[RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
	Extensions (MIME) Part Two: Media Types", RFC 2046,		Extensions (MIME) Part Two: Media Types", RFC 2046,
	November 1996.		November 1996.
	[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate		[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
	skipping to change at page 18, line 4 ¶		skipping to change at page 18, line 4 ¶
	"k":"GawgguFyGrWKav7AX4VKUg"},		"k":"GawgguFyGrWKav7AX4VKUg"},
	{"kty":"oct",		{"kty":"oct",
	"k":"AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75		"k":"AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75
	aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow",		aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow",
	"kid":"HMAC key used in JWS A.1 example"}		"kid":"HMAC key used in JWS A.1 example"}
	]		]
	}		}
	Appendix B. Example Use of "x5c" (X.509 Certificate Chain) Parameter		Appendix B. Example Use of "x5c" (X.509 Certificate Chain) Parameter
	The following is a non-normative example of a JWK with a RSA signing		The following is an example of a JWK with a RSA signing key
	key represented both as a bare public key and as an X.509 certificate		represented both as a bare public key and as an X.509 certificate
	using the "x5c" parameter:		using the "x5c" parameter:
	{"kty":"RSA",		{"kty":"RSA",
	"use":"sig",		"use":"sig",
	"kid":"1b94c",		"kid":"1b94c",
	"n":"vrjOfz9Ccdgx5nQudyhdoR17V-IubWMeOZCwX_jj0hgAsz2J_pqYW08		"n":"vrjOfz9Ccdgx5nQudyhdoR17V-IubWMeOZCwX_jj0hgAsz2J_pqYW08
	PLbK_PdiVGKPrqzmDIsLI7sA25VEnHU1uCLNwBuUiCO11_-7dYbsr4iJmG0Q		PLbK_PdiVGKPrqzmDIsLI7sA25VEnHU1uCLNwBuUiCO11_-7dYbsr4iJmG0Q
	u2j8DsVyT1azpJC_NG84Ty5KKthuCaPod7iI7w0LK9orSMhBEwwZDCxTWq4a		u2j8DsVyT1azpJC_NG84Ty5KKthuCaPod7iI7w0LK9orSMhBEwwZDCxTWq4a
	YWAchc8t-emd9qOvWtVMDC2BXksRngh6X5bUYLy6AyHKvj-nUy1wgzjYQDwH		YWAchc8t-emd9qOvWtVMDC2BXksRngh6X5bUYLy6AyHKvj-nUy1wgzjYQDwH
	MTplCoLtU-o-8SNnZ1tmRoGE9uJkBLdh5gFENabWnU5m1ZqZPdwS-qo-meMv		MTplCoLtU-o-8SNnZ1tmRoGE9uJkBLdh5gFENabWnU5m1ZqZPdwS-qo-meMv
	skipping to change at page 19, line 19 ¶		skipping to change at page 19, line 19 ¶
	Turner.		Turner.
	Jim Schaad and Karen O'Donoghue chaired the JOSE working group and		Jim Schaad and Karen O'Donoghue chaired the JOSE working group and
	Sean Turner and Stephen Farrell served as Security area directors		Sean Turner and Stephen Farrell served as Security area directors
	during the creation of this specification.		during the creation of this specification.
	Appendix D. Document History		Appendix D. 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 ]]
			-15
			o Changes to address editorial issues #48, #64, #65, #66, and #91.
	-14		-14
	o Relaxed language introducing key parameters since some parameters		o Relaxed language introducing key parameters since some parameters
	are applicable to multiple, but not all, key types.		are applicable to multiple, but not all, key types.
	-13		-13
	o Applied spelling and grammar corrections.		o Applied spelling and grammar corrections.
	-12		-12
End of changes. 17 change blocks.
	33 lines changed or deleted		35 lines changed or added
This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/