< draft-ietf-jose-json-web-encryption-27.txt		draft-ietf-jose-json-web-encryption-28.txt >
	JOSE Working Group M. Jones		JOSE Working Group M. Jones
	Internet-Draft Microsoft		Internet-Draft Microsoft
	Intended status: Standards Track J. Hildebrand		Intended status: Standards Track J. Hildebrand
	Expires: December 12, 2014 Cisco		Expires: December 22, 2014 Cisco
	June 10, 2014		June 20, 2014
	JSON Web Encryption (JWE)		JSON Web Encryption (JWE)
	draft-ietf-jose-json-web-encryption-27		draft-ietf-jose-json-web-encryption-28
	Abstract		Abstract
	JSON Web Encryption (JWE) represents encrypted content using		JSON Web Encryption (JWE) represents encrypted content using
	JavaScript Object Notation (JSON) based data structures.		JavaScript Object Notation (JSON) based data structures.
	Cryptographic algorithms and identifiers for use with this		Cryptographic algorithms and identifiers for use with this
	specification are described in the separate JSON Web Algorithms (JWA)		specification are described in the separate JSON Web Algorithms (JWA)
	specification and IANA registries defined by that specification.		specification and IANA registries defined by that specification.
	Related digital signature and MAC capabilities are described in the		Related digital signature and MAC capabilities are described in the
	separate JSON Web Signature (JWS) specification.		separate JSON Web Signature (JWS) specification.
	skipping to change at page 1, line 37 ¶		skipping to change at page 1, line 37 ¶
	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 December 12, 2014.		This Internet-Draft will expire on December 22, 2014.
	Copyright Notice		Copyright Notice
	Copyright (c) 2014 IETF Trust and the persons identified as the		Copyright (c) 2014 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 49 ¶		skipping to change at page 2, line 49 ¶
	7. Serializations . . . . . . . . . . . . . . . . . . . . . . . . 21		7. Serializations . . . . . . . . . . . . . . . . . . . . . . . . 21
	7.1. JWE Compact Serialization . . . . . . . . . . . . . . . . 21		7.1. JWE Compact Serialization . . . . . . . . . . . . . . . . 21
	7.2. JWE JSON Serialization . . . . . . . . . . . . . . . . . . 21		7.2. JWE JSON Serialization . . . . . . . . . . . . . . . . . . 21
	8. TLS Requirements . . . . . . . . . . . . . . . . . . . . . . . 24		8. TLS Requirements . . . . . . . . . . . . . . . . . . . . . . . 24
	9. Distinguishing between JWS and JWE Objects . . . . . . . . . . 24		9. Distinguishing between JWS and JWE Objects . . . . . . . . . . 24
	10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25		10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25
	10.1. JSON Web Signature and Encryption Header Parameters		10.1. JSON Web Signature and Encryption Header Parameters
	Registration . . . . . . . . . . . . . . . . . . . . . . . 25		Registration . . . . . . . . . . . . . . . . . . . . . . . 25
	10.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 25		10.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 25
	11. Security Considerations . . . . . . . . . . . . . . . . . . . 27		11. Security Considerations . . . . . . . . . . . . . . . . . . . 27
	11.1. Adaptive Chosen-Ciphertext Attacks . . . . . . . . . . . . 27		11.1. Using Matching Algorithm Strengths . . . . . . . . . . . . 27
	11.2. Timing Attacks . . . . . . . . . . . . . . . . . . . . . . 28		11.2. Adaptive Chosen-Ciphertext Attacks . . . . . . . . . . . . 27
			11.3. Timing Attacks . . . . . . . . . . . . . . . . . . . . . . 28
	12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 28		12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 28
	12.1. Normative References . . . . . . . . . . . . . . . . . . . 28		12.1. Normative References . . . . . . . . . . . . . . . . . . . 28
	12.2. Informative References . . . . . . . . . . . . . . . . . . 29		12.2. Informative References . . . . . . . . . . . . . . . . . . 29
	Appendix A. JWE Examples . . . . . . . . . . . . . . . . . . . . 29		Appendix A. JWE Examples . . . . . . . . . . . . . . . . . . . . 30
	A.1. Example JWE using RSAES OAEP and AES GCM . . . . . . . . . 29		A.1. Example JWE using RSAES OAEP and AES GCM . . . . . . . . . 30
	A.1.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 30		A.1.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 30
	A.1.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 30		A.1.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 30
	A.1.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 30		A.1.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 30
	A.1.4. Initialization Vector . . . . . . . . . . . . . . . . 32		A.1.4. Initialization Vector . . . . . . . . . . . . . . . . 32
	A.1.5. Additional Authenticated Data . . . . . . . . . . . . 32		A.1.5. Additional Authenticated Data . . . . . . . . . . . . 32
	A.1.6. Content Encryption . . . . . . . . . . . . . . . . . . 32		A.1.6. Content Encryption . . . . . . . . . . . . . . . . . . 32
	A.1.7. Complete Representation . . . . . . . . . . . . . . . 33		A.1.7. Complete Representation . . . . . . . . . . . . . . . 33
	A.1.8. Validation . . . . . . . . . . . . . . . . . . . . . . 33		A.1.8. Validation . . . . . . . . . . . . . . . . . . . . . . 33
	A.2. Example JWE using RSAES-PKCS1-V1_5 and		A.2. Example JWE using RSAES-PKCS1-V1_5 and
	AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 33		AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 33
	skipping to change at page 10, line 42 ¶		skipping to change at page 10, line 42 ¶
	In the JWE JSON Serialization, a JWE object is represented as the		In the JWE JSON Serialization, a JWE object is represented as the
	combination of these eight values,		combination of these eight values,
	BASE64URL(UTF8(JWE Protected Header)),		BASE64URL(UTF8(JWE Protected Header)),
	JWE Shared Unprotected Header,		JWE Shared Unprotected Header,
	JWE Per-Recipient Unprotected Header,		JWE Per-Recipient Unprotected Header,
	BASE64URL(JWE Encrypted Key),		BASE64URL(JWE Encrypted Key),
	BASE64URL(JWE Initialization Vector),		BASE64URL(JWE Initialization Vector),
	BASE64URL(JWE Ciphertext),		BASE64URL(JWE Ciphertext),
	BASE64URL(JWE Authentication Tag), and		BASE64URL(JWE Authentication Tag), and
	BASE64URL(JWE AAD),		BASE64URL(JWE AAD),
	with the six base64url encoding result strings and the two		with the six base64url encoded result strings and the two unprotected
	unprotected JSON object values being represented as members within a		JSON object values being represented as members within a JSON object.
	JSON object. The inclusion of some of these values is OPTIONAL. The		The inclusion of some of these values is OPTIONAL. The JWE JSON
	JWE JSON Serialization can also encrypt the plaintext to multiple		Serialization can also encrypt the plaintext to multiple recipients.
	recipients. See Section 7.2 for more information about the JWE JSON		See Section 7.2 for more information about the JWE JSON
	Serialization.		Serialization.
	JWE utilizes authenticated encryption to ensure the confidentiality		JWE utilizes authenticated encryption to ensure the confidentiality
	and integrity of the Plaintext and the integrity of the JWE Protected		and integrity of the Plaintext and the integrity of the JWE Protected
	Header and the JWE AAD.		Header and the JWE AAD.
	3.1. Example JWE		3.1. Example JWE
	This example encrypts the plaintext "The true sign of intelligence is		This example encrypts the plaintext "The true sign of intelligence is
	not knowledge but imagination." to the recipient using RSAES OAEP for		not knowledge but imagination." to the recipient using RSAES OAEP for
	skipping to change at page 15, line 36 ¶		skipping to change at page 15, line 36 ¶
	This parameter has the same meaning, syntax, and processing rules as		This parameter has the same meaning, syntax, and processing rules as
	the "x5t#S256" Header Parameter defined in Section 4.1.8 of [JWS],		the "x5t#S256" Header Parameter defined in Section 4.1.8 of [JWS],
	except that the certificate referenced by the thumbprint contains the		except that the certificate referenced by the thumbprint contains the
	public key to which the JWE was encrypted; this can be used to		public key to which the JWE was encrypted; this can be used to
	determine the private key needed to decrypt the JWE.		determine the private key needed to decrypt the JWE.
	4.1.11. "typ" (Type) Header Parameter		4.1.11. "typ" (Type) Header Parameter
	This parameter has the same meaning, syntax, and processing rules as		This parameter has the same meaning, syntax, and processing rules as
	the "typ" Header Parameter defined in Section 4.1.9 of [JWS], except		the "typ" Header Parameter defined in Section 4.1.9 of [JWS], except
	that the type is of this complete JWE object.		that the type is that of this complete JWE object.
	4.1.12. "cty" (Content Type) Header Parameter		4.1.12. "cty" (Content Type) Header Parameter
	This parameter has the same meaning, syntax, and processing rules as		This parameter has the same meaning, syntax, and processing rules as
	the "cty" Header Parameter defined in Section 4.1.10 of [JWS], except		the "cty" Header Parameter defined in Section 4.1.10 of [JWS], except
	that the type is of the secured content (the plaintext).		that the type is that of the secured content (the plaintext).
	4.1.13. "crit" (Critical) Header Parameter		4.1.13. "crit" (Critical) Header Parameter
	This parameter has the same meaning, syntax, and processing rules as		This parameter has the same meaning, syntax, and processing rules as
	the "crit" Header Parameter defined in Section 4.1.11 of [JWS],		the "crit" Header Parameter defined in Section 4.1.11 of [JWS],
	except that JWE Header Parameters are being referred to, rather than		except that JWE Header Parameters are being referred to, rather than
	JWS Header Parameters.		JWS Header Parameters.
	4.2. Public Header Parameter Names		4.2. Public Header Parameter Names
	skipping to change at page 20, line 14 ¶		skipping to change at page 20, line 14 ¶
	10. When Key Wrapping, Key Encryption, or Key Agreement with Key		10. When Key Wrapping, Key Encryption, or Key Agreement with Key
	Wrapping are employed, decrypt the JWE Encrypted Key to produce		Wrapping are employed, decrypt the JWE Encrypted Key to produce
	the Content Encryption Key (CEK). The CEK MUST have a length		the Content Encryption Key (CEK). The CEK MUST have a length
	equal to that required for the content encryption algorithm.		equal to that required for the content encryption algorithm.
	Note that when there are multiple recipients, each recipient		Note that when there are multiple recipients, each recipient
	will only be able decrypt any JWE Encrypted Key values that were		will only be able decrypt any JWE Encrypted Key values that were
	encrypted to a key in that recipient's possession. It is		encrypted to a key in that recipient's possession. It is
	therefore normal to only be able to decrypt one of the per-		therefore normal to only be able to decrypt one of the per-
	recipient JWE Encrypted Key values to obtain the CEK value.		recipient JWE Encrypted Key values to obtain the CEK value.
	Also, see Section 11.2 for security considerations on mitigating		Also, see Section 11.3 for security considerations on mitigating
	timing attacks.		timing attacks.
	11. When Direct Key Agreement or Direct Encryption are employed,		11. When Direct Key Agreement or Direct Encryption are employed,
	verify that the JWE Encrypted Key value is empty octet sequence.		verify that the JWE Encrypted Key value is empty octet sequence.
	12. When Direct Encryption is employed, let the Content Encryption		12. When Direct Encryption is employed, let the Content Encryption
	Key (CEK) be the shared symmetric key.		Key (CEK) be the shared symmetric key.
	13. If the JWE JSON Serialization is being used, repeat this process		13. If the JWE JSON Serialization is being used, repeat this process
	(steps 4-12) for each recipient contained in the representation		(steps 4-12) for each recipient contained in the representation
	skipping to change at page 27, line 25 ¶		skipping to change at page 27, line 25 ¶
	o Header Parameter Name: "crit"		o Header Parameter Name: "crit"
	o Header Parameter Description: Critical		o Header Parameter Description: Critical
	o Header Parameter Usage Location(s): JWE		o Header Parameter Usage Location(s): JWE
	o Change Controller: IESG		o Change Controller: IESG
	o Specification Document(s): Section 4.1.13 of [[ this document ]]		o Specification Document(s): Section 4.1.13 of [[ this document ]]
	11. Security Considerations		11. Security Considerations
	All of the security issues faced by any cryptographic application		All of the security issues faced by any cryptographic application
	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 asymmetric private and symmetric secret keys,
	attacks, and helping the user avoid mistakes such as inadvertently		preventing various attacks, and helping avoid mistakes such as
	encrypting a message for the wrong recipient. The entire list of		inadvertently encrypting a message to the wrong recipient. The
	security considerations is beyond the scope of this document.		entire list of security considerations is beyond the scope of this
			document.
	All the security considerations in the JWS specification also apply		All the security considerations in the JWS specification also apply
	to this specification. Likewise, all the security considerations in		to this specification. Likewise, all the security considerations in
	XML Encryption 1.1 [W3C.REC-xmlenc-core1-20130411] also apply, other		XML Encryption 1.1 [W3C.REC-xmlenc-core1-20130411] also apply, other
	than those that are XML specific.		than those that are XML specific.
	11.1. Adaptive Chosen-Ciphertext Attacks		11.1. Using Matching Algorithm Strengths
			Algorithms of matching strengths should be used together whenever
			possible. For instance, when AES Key Wrap is used with a given key
			size, using the same key size is recommended when AES GCM is also
			used.
			11.2. Adaptive Chosen-Ciphertext Attacks
	When decrypting, particular care must be taken not to allow the JWE		When decrypting, particular care must be taken not to allow the JWE
	recipient to be used as an oracle for decrypting messages. RFC 3218		recipient to be used as an oracle for decrypting messages. RFC 3218
	[RFC3218] should be consulted for specific countermeasures to attacks		[RFC3218] should be consulted for specific countermeasures to attacks
	on RSAES-PKCS1-V1_5. An attacker might modify the contents of the		on RSAES-PKCS1-V1_5. An attacker might modify the contents of the
	"alg" parameter from "RSA-OAEP" to "RSA1_5" in order to generate a		"alg" parameter from "RSA-OAEP" to "RSA1_5" in order to generate a
	formatting error that can be detected and used to recover the CEK		formatting error that can be detected and used to recover the CEK
	even if RSAES OAEP was used to encrypt the CEK. It is therefore		even if RSAES OAEP was used to encrypt the CEK. It is therefore
	particularly important to report all formatting errors to the CEK,		particularly important to report all formatting errors to the CEK,
	Additional Authenticated Data, or ciphertext as a single error when		Additional Authenticated Data, or ciphertext as a single error when
	the encrypted content is rejected.		the encrypted content is rejected.
	Additionally, this type of attack can be prevented by the use of "key		Additionally, this type of attack can be prevented by the use of "key
	tainting". This method restricts the use of a key to a limited set		tainting". This method restricts the use of a key to a limited set
	of algorithms -- usually one. This means, for instance, that if the		of algorithms -- usually one. This means, for instance, that if the
	key is marked as being for "RSA-OAEP" only, any attempt to decrypt a		key is marked as being for "RSA-OAEP" only, any attempt to decrypt a
	message using the "RSA1_5" algorithm with that key would fail		message using the "RSA1_5" algorithm with that key would fail
	immediately due to invalid use of the key.		immediately due to invalid use of the key.
	11.2. Timing Attacks		11.3. Timing Attacks
	To mitigate the attacks described in RFC 3218 [RFC3218], the		To mitigate the attacks described in RFC 3218 [RFC3218], the
	recipient MUST NOT distinguish between format, padding, and length		recipient MUST NOT distinguish between format, padding, and length
	errors of encrypted keys. It is strongly recommended, in the event		errors of encrypted keys. It is strongly recommended, in the event
	of receiving an improperly formatted key, that the receiver		of receiving an improperly formatted key, that the receiver
	substitute a randomly generated CEK and proceed to the next step, to		substitute a randomly generated CEK and proceed to the next step, to
	mitigate timing attacks.		mitigate timing attacks.
	12. References		12. References
	skipping to change at page 43, line 38 ¶		skipping to change at page 43, line 38 ¶
	"Mz-VPPyU4RlcuYv1IwIvzw"		"Mz-VPPyU4RlcuYv1IwIvzw"
	}		}
	Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation		Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation
	This example shows the steps in the AES_128_CBC_HMAC_SHA_256		This example shows the steps in the AES_128_CBC_HMAC_SHA_256
	authenticated encryption computation using the values from the		authenticated encryption computation using the values from the
	example in Appendix A.3. As described where this algorithm is		example in Appendix A.3. As described where this algorithm is
	defined in Sections 5.2 and 5.2.3 of JWA, the AES_CBC_HMAC_SHA2		defined in Sections 5.2 and 5.2.3 of JWA, the AES_CBC_HMAC_SHA2
	family of algorithms are implemented using Advanced Encryption		family of algorithms are implemented using Advanced Encryption
	Standard (AES) in Cipher Block Chaining (CBC) mode with PKCS #5		Standard (AES) in Cipher Block Chaining (CBC) mode with PKCS #7
	padding to perform the encryption and an HMAC SHA-2 function to		padding to perform the encryption and an HMAC SHA-2 function to
	perform the integrity calculation - in this case, HMAC SHA-256.		perform the integrity calculation - in this case, HMAC SHA-256.
	B.1. Extract MAC_KEY and ENC_KEY from Key		B.1. Extract MAC_KEY and ENC_KEY from Key
	The 256 bit AES_128_CBC_HMAC_SHA_256 key K used in this example		The 256 bit AES_128_CBC_HMAC_SHA_256 key K used in this example
	(using JSON array notation) is:		(using JSON array notation) is:
	[4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106,		[4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106,
	206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156,		206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156,
	skipping to change at page 44, line 22 ¶		skipping to change at page 44, line 22 ¶
	[107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 44,		[107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 44,
	207]		207]
	Note that the MAC key comes before the encryption key in the input		Note that the MAC key comes before the encryption key in the input
	key K; this is in the opposite order of the algorithm names in the		key K; this is in the opposite order of the algorithm names in the
	identifiers "AES_128_CBC_HMAC_SHA_256" and "A128CBC-HS256".		identifiers "AES_128_CBC_HMAC_SHA_256" and "A128CBC-HS256".
	B.2. Encrypt Plaintext to Create Ciphertext		B.2. Encrypt Plaintext to Create Ciphertext
	Encrypt the Plaintext with AES in Cipher Block Chaining (CBC) mode		Encrypt the Plaintext with AES in Cipher Block Chaining (CBC) mode
	using PKCS #5 padding using the ENC_KEY above. The Plaintext in this		using PKCS #7 padding using the ENC_KEY above. The Plaintext in this
	example is:		example is:
	[76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32,		[76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32,
	112, 114, 111, 115, 112, 101, 114, 46]		112, 114, 111, 115, 112, 101, 114, 46]
	The encryption result is as follows, which is the Ciphertext output:		The encryption result is as follows, which is the Ciphertext output:
	[40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6,		[40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6,
	75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143,		75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143,
	112, 56, 102]		112, 56, 102]
	skipping to change at page 46, line 32 ¶		skipping to change at page 46, line 32 ¶
	Nat Sakimura, Jim Schaad, Hannes Tschofenig, and Sean Turner.		Nat Sakimura, Jim Schaad, Hannes Tschofenig, and Sean 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, Stephen Farrell, and Kathleen Moriarty served as		Sean Turner, Stephen Farrell, and Kathleen Moriarty served as
	Security area directors during the creation of this specification.		Security area directors 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 ]]
			-28
			o Specified the use of PKCS #7 padding with AES CBC, rather than
			PKCS #5. (PKCS #7 is a superset of PKCS #5, and is appropriate
			for the 16 octet blocks used by AES CBC.)
			o Revised the introduction to the Security Considerations section.
			Also moved a security consideration item here from the JWA draft.
	-27		-27
	o Described additional security considerations.		o Described additional security considerations.
	o Added the "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) header		o Added the "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) header
	parameter.		parameter.
	-26		-26
	o Noted that octet sequences are depicted using JSON array notation.		o Noted that octet sequences are depicted using JSON array notation.
End of changes. 15 change blocks.
	25 lines changed or deleted		42 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/