< draft-ietf-jose-json-web-encryption-07.txt   draft-ietf-jose-json-web-encryption-08.txt >
JOSE Working Group M. Jones JOSE Working Group M. Jones
Internet-Draft Microsoft Internet-Draft Microsoft
Intended status: Standards Track E. Rescorla Intended status: Standards Track E. Rescorla
Expires: May 10, 2013 RTFM Expires: June 30, 2013 RTFM
J. Hildebrand J. Hildebrand
Cisco Cisco
November 6, 2012 December 27, 2012
JSON Web Encryption (JWE) JSON Web Encryption (JWE)
draft-ietf-jose-json-web-encryption-07 draft-ietf-jose-json-web-encryption-08
Abstract Abstract
JSON Web Encryption (JWE) is a means of representing encrypted JSON Web Encryption (JWE) is a means of representing encrypted
content using JavaScript Object Notation (JSON) data structures. content using JavaScript Object Notation (JSON) 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. Related digital signature and MAC capabilities are specification. Related digital signature and MAC capabilities are
described in the separate JSON Web Signature (JWS) specification. described in the separate JSON Web Signature (JWS) specification.
skipping to change at page 1, line 38 skipping to change at page 1, line 38
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 May 10, 2013. This Internet-Draft will expire on June 30, 2013.
Copyright Notice Copyright Notice
Copyright (c) 2012 IETF Trust and the persons identified as the Copyright (c) 2012 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 38 skipping to change at page 2, line 38
4.1.9. "x5c" (X.509 Certificate Chain) Header Parameter . . . 14 4.1.9. "x5c" (X.509 Certificate Chain) Header Parameter . . . 14
4.1.10. "kid" (Key ID) Header Parameter . . . . . . . . . . . 15 4.1.10. "kid" (Key ID) Header Parameter . . . . . . . . . . . 15
4.1.11. "typ" (Type) Header Parameter . . . . . . . . . . . . 15 4.1.11. "typ" (Type) Header Parameter . . . . . . . . . . . . 15
4.1.12. "cty" (Content Type) Header Parameter . . . . . . . . 15 4.1.12. "cty" (Content Type) Header Parameter . . . . . . . . 15
4.1.13. "apu" (Agreement PartyUInfo) Header Parameter . . . . 15 4.1.13. "apu" (Agreement PartyUInfo) Header Parameter . . . . 15
4.1.14. "apv" (Agreement PartyVInfo) Header Parameter . . . . 15 4.1.14. "apv" (Agreement PartyVInfo) Header Parameter . . . . 15
4.1.15. "epu" (Encryption PartyUInfo) Header Parameter . . . . 16 4.1.15. "epu" (Encryption PartyUInfo) Header Parameter . . . . 16
4.1.16. "epv" (Encryption PartyVInfo) Header Parameter . . . . 16 4.1.16. "epv" (Encryption PartyVInfo) Header Parameter . . . . 16
4.2. Public Header Parameter Names . . . . . . . . . . . . . . 16 4.2. Public Header Parameter Names . . . . . . . . . . . . . . 16
4.3. Private Header Parameter Names . . . . . . . . . . . . . . 16 4.3. Private Header Parameter Names . . . . . . . . . . . . . . 16
5. Message Encryption . . . . . . . . . . . . . . . . . . . . . . 16 5. Producing and Consuming JWEs . . . . . . . . . . . . . . . . . 16
6. Message Decryption . . . . . . . . . . . . . . . . . . . . . . 18 5.1. Message Encryption . . . . . . . . . . . . . . . . . . . . 16
7. CMK Encryption . . . . . . . . . . . . . . . . . . . . . . . . 19 5.2. Message Decryption . . . . . . . . . . . . . . . . . . . . 18
8. Encrypting JWEs with Cryptographic Algorithms . . . . . . . . 20 5.3. String Comparison Rules . . . . . . . . . . . . . . . . . 19
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 6. Encrypting JWEs with Cryptographic Algorithms . . . . . . . . 20
9.1. Registration of JWE Header Parameter Names . . . . . . . . 20 6.1. CMK Encryption . . . . . . . . . . . . . . . . . . . . . . 20
9.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 20 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20
9.2. JSON Web Signature and Encryption Type Values 7.1. Registration of JWE Header Parameter Names . . . . . . . . 20
7.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 21
7.2. JSON Web Signature and Encryption Type Values
Registration . . . . . . . . . . . . . . . . . . . . . . . 22 Registration . . . . . . . . . . . . . . . . . . . . . . . 22
9.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 22 7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 22
9.3. Media Type Registration . . . . . . . . . . . . . . . . . 22 7.3. Media Type Registration . . . . . . . . . . . . . . . . . 23
9.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 22 7.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 23
10. Security Considerations . . . . . . . . . . . . . . . . . . . 23 8. Security Considerations . . . . . . . . . . . . . . . . . . . 23
11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 23 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 24
11.1. Normative References . . . . . . . . . . . . . . . . . . . 23 9.1. Normative References . . . . . . . . . . . . . . . . . . . 24
11.2. Informative References . . . . . . . . . . . . . . . . . . 24 9.2. Informative References . . . . . . . . . . . . . . . . . . 25
Appendix A. JWE Examples . . . . . . . . . . . . . . . . . . . . 25 Appendix A. JWE Examples . . . . . . . . . . . . . . . . . . . . 25
A.1. Example JWE using RSAES OAEP and AES GCM . . . . . . . . . 25 A.1. Example JWE using RSAES OAEP and AES GCM . . . . . . . . . 26
A.1.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 25 A.1.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 26
A.1.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 25 A.1.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 26
A.1.3. Content Master Key (CMK) . . . . . . . . . . . . . . . 26 A.1.3. Content Master Key (CMK) . . . . . . . . . . . . . . . 26
A.1.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 26 A.1.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 26
A.1.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 28 A.1.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 29
A.1.6. Initialization Vector . . . . . . . . . . . . . . . . 28 A.1.6. Initialization Vector . . . . . . . . . . . . . . . . 29
A.1.7. "Additional Authenticated Data" Parameter . . . . . . 28 A.1.7. "Additional Authenticated Data" Parameter . . . . . . 29
A.1.8. Plaintext Encryption . . . . . . . . . . . . . . . . . 29 A.1.8. Plaintext Encryption . . . . . . . . . . . . . . . . . 30
A.1.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 29 A.1.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 30
A.1.10. Encoded JWE Integrity Value . . . . . . . . . . . . . 30 A.1.10. Encoded JWE Integrity Value . . . . . . . . . . . . . 31
A.1.11. Complete Representation . . . . . . . . . . . . . . . 30 A.1.11. Complete Representation . . . . . . . . . . . . . . . 31
A.1.12. Validation . . . . . . . . . . . . . . . . . . . . . . 30 A.1.12. Validation . . . . . . . . . . . . . . . . . . . . . . 31
A.2. Example JWE using RSAES-PKCS1-V1_5 and AES CBC . . . . . . 30 A.2. Example JWE using RSAES-PKCS1-V1_5 and AES CBC . . . . . . 31
A.2.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 31 A.2.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 32
A.2.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 31 A.2.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 32
A.2.3. Content Master Key (CMK) . . . . . . . . . . . . . . . 31 A.2.3. Content Master Key (CMK) . . . . . . . . . . . . . . . 32
A.2.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 31 A.2.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 32
A.2.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 34 A.2.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 35
A.2.6. Key Derivation . . . . . . . . . . . . . . . . . . . . 34 A.2.6. Key Derivation . . . . . . . . . . . . . . . . . . . . 35
A.2.7. Initialization Vector . . . . . . . . . . . . . . . . 34 A.2.7. Initialization Vector . . . . . . . . . . . . . . . . 35
A.2.8. Plaintext Encryption . . . . . . . . . . . . . . . . . 34 A.2.8. Plaintext Encryption . . . . . . . . . . . . . . . . . 35
A.2.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 35 A.2.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 36
A.2.10. Secured Input Value . . . . . . . . . . . . . . . . . 35 A.2.10. Secured Input Value . . . . . . . . . . . . . . . . . 36
A.2.11. JWE Integrity Value . . . . . . . . . . . . . . . . . 36 A.2.11. JWE Integrity Value . . . . . . . . . . . . . . . . . 37
A.2.12. Encoded JWE Integrity Value . . . . . . . . . . . . . 36 A.2.12. Encoded JWE Integrity Value . . . . . . . . . . . . . 37
A.2.13. Complete Representation . . . . . . . . . . . . . . . 36 A.2.13. Complete Representation . . . . . . . . . . . . . . . 37
A.2.14. Validation . . . . . . . . . . . . . . . . . . . . . . 37 A.2.14. Validation . . . . . . . . . . . . . . . . . . . . . . 38
A.3. Example JWE using AES Key Wrap and AES GCM . . . . . . . . 37 A.3. Example JWE using AES Key Wrap and AES GCM . . . . . . . . 38
A.3.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 37 A.3.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 38
A.3.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 38 A.3.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 39
A.3.3. Content Master Key (CMK) . . . . . . . . . . . . . . . 38 A.3.3. Content Master Key (CMK) . . . . . . . . . . . . . . . 39
A.3.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 38 A.3.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 39
A.3.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 38 A.3.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 39
A.3.6. Initialization Vector . . . . . . . . . . . . . . . . 38 A.3.6. Initialization Vector . . . . . . . . . . . . . . . . 39
A.3.7. "Additional Authenticated Data" Parameter . . . . . . 39 A.3.7. "Additional Authenticated Data" Parameter . . . . . . 40
A.3.8. Plaintext Encryption . . . . . . . . . . . . . . . . . 39 A.3.8. Plaintext Encryption . . . . . . . . . . . . . . . . . 40
A.3.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 39 A.3.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 40
A.3.10. Encoded JWE Integrity Value . . . . . . . . . . . . . 40 A.3.10. Encoded JWE Integrity Value . . . . . . . . . . . . . 41
A.3.11. Complete Representation . . . . . . . . . . . . . . . 40 A.3.11. Complete Representation . . . . . . . . . . . . . . . 41
A.3.12. Validation . . . . . . . . . . . . . . . . . . . . . . 40 A.3.12. Validation . . . . . . . . . . . . . . . . . . . . . . 41
A.4. Example Key Derivation for "enc" value "A128CBC+HS256" . . 40 A.4. Example Key Derivation for "enc" value "A128CBC+HS256" . . 41
A.4.1. CEK Generation . . . . . . . . . . . . . . . . . . . . 41 A.4.1. CEK Generation . . . . . . . . . . . . . . . . . . . . 42
A.4.2. CIK Generation . . . . . . . . . . . . . . . . . . . . 42 A.4.2. CIK Generation . . . . . . . . . . . . . . . . . . . . 43
A.5. Example Key Derivation for "enc" value "A256CBC+HS512" . . 44
A.5. Example Key Derivation for "enc" value "A256CBC+HS512" . . 43 A.5.1. CEK Generation . . . . . . . . . . . . . . . . . . . . 44
A.5.1. CEK Generation . . . . . . . . . . . . . . . . . . . . 43 A.5.2. CIK Generation . . . . . . . . . . . . . . . . . . . . 45
A.5.2. CIK Generation . . . . . . . . . . . . . . . . . . . . 44 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 46
Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 45 Appendix C. Open Issues . . . . . . . . . . . . . . . . . . . . . 47
Appendix C. Open Issues . . . . . . . . . . . . . . . . . . . . . 45 Appendix D. Document History . . . . . . . . . . . . . . . . . . 47
Appendix D. Document History . . . . . . . . . . . . . . . . . . 46 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 51
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 50
1. Introduction 1. Introduction
JSON Web Encryption (JWE) is a compact encryption format intended for JSON Web Encryption (JWE) is a compact encryption format intended for
space constrained environments such as HTTP Authorization headers and space constrained environments such as HTTP Authorization headers and
URI query parameters. It represents this content using JavaScript URI query parameters. It represents this content using JavaScript
Object Notation (JSON) [RFC4627] based data structures. The JWE Object Notation (JSON) [RFC4627] based data structures. The JWE
cryptographic mechanisms encrypt and provide integrity protection for cryptographic mechanisms encrypt and provide integrity protection for
arbitrary sequences of bytes. arbitrary sequences of bytes.
skipping to change at page 6, line 6 skipping to change at page 6, line 6
it. it.
Content Master Key (CMK) A key from which the CEK and CIK are Content Master Key (CMK) A key from which the CEK and CIK are
derived. When key wrapping or key encryption are employed, the derived. When key wrapping or key encryption are employed, the
CMK is randomly generated and encrypted to the recipient as the CMK is randomly generated and encrypted to the recipient as the
JWE Encrypted Key. When direct encryption with a shared symmetric JWE Encrypted Key. When direct encryption with a shared symmetric
key is employed, the CMK is the shared key. When key agreement key is employed, the CMK is the shared key. When key agreement
without key wrapping is employed, the CMK is the result of the key without key wrapping is employed, the CMK is the result of the key
agreement algorithm. agreement algorithm.
JWE Header A string representing a JSON object that describes the JSON Text Object A UTF-8 encoded text string representing a JSON
encryption operations applied to create the JWE Encrypted Key, the object; the syntax of JSON objects is defined in Section 2.2 of
JWE Ciphertext, and the JWE Integrity Value. [RFC4627].
JWE Header A JSON Text Object that describes the encryption
operations applied to create the JWE Encrypted Key, the JWE
Ciphertext, and the JWE Integrity Value.
JWE Encrypted Key When key wrapping or key encryption are employed, JWE Encrypted Key When key wrapping or key encryption are employed,
the Content Master Key (CMK) is encrypted with the intended the Content Master Key (CMK) is encrypted with the intended
recipient's key and the resulting encrypted content is recorded as recipient's key and the resulting encrypted content is recorded as
a byte array, which is referred to as the JWE Encrypted Key. a byte array, which is referred to as the JWE Encrypted Key.
Otherwise, when direct encryption with a shared or agreed upon Otherwise, when direct encryption with a shared or agreed upon
symmetric key is employed, the JWE Encrypted Key is the empty byte symmetric key is employed, the JWE Encrypted Key is the empty byte
array. array.
JWE Initialization Vector A byte array containing the Initialization JWE Initialization Vector A byte array containing the Initialization
skipping to change at page 6, line 33 skipping to change at page 6, line 37
JWE Integrity Value A byte array containing a MAC value that ensures JWE Integrity Value A byte array containing a MAC value that ensures
the integrity of the Ciphertext and the parameters used to create the integrity of the Ciphertext and the parameters used to create
it. it.
Base64url Encoding The URL- and filename-safe Base64 encoding Base64url Encoding The URL- and filename-safe Base64 encoding
described in RFC 4648 [RFC4648], Section 5, with the (non URL- described in RFC 4648 [RFC4648], Section 5, with the (non URL-
safe) '=' padding characters omitted, as permitted by Section 3.2. safe) '=' padding 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.)
Encoded JWE Header Base64url encoding of the bytes of the UTF-8 Encoded JWE Header Base64url encoding of the JWE Header.
[RFC3629] representation of the JWE Header.
Encoded JWE Encrypted Key Base64url encoding of the JWE Encrypted Encoded JWE Encrypted Key Base64url encoding of the JWE Encrypted
Key. Key.
Encoded JWE Initialization Vector Base64url encoding of the JWE Encoded JWE Initialization Vector Base64url encoding of the JWE
Initialization Vector. Initialization Vector.
Encoded JWE Ciphertext Base64url encoding of the JWE Ciphertext. Encoded JWE Ciphertext Base64url encoding of the JWE Ciphertext.
Encoded JWE Integrity Value Base64url encoding of the JWE Integrity Encoded JWE Integrity Value Base64url encoding of the JWE Integrity
Value. Value.
Header Parameter Name The name of a member of the JSON object Header Parameter Name The name of a member of the JWE Header.
representing a JWE Header.
Header Parameter Value The value of a member of the JSON object Header Parameter Value The value of a member of the JWE Header.
representing a JWE Header.
JWE Compact Serialization A representation of the JWE as the JWE Compact Serialization A representation of the JWE as the
concatenation of the Encoded JWE Header, the Encoded JWE Encrypted concatenation of the Encoded JWE Header, the Encoded JWE Encrypted
Key, the Encoded JWE Initialization Vector, the Encoded JWE Key, the Encoded JWE Initialization Vector, the Encoded JWE
Ciphertext, and the Encoded JWE Integrity Value in that order, Ciphertext, and the Encoded JWE Integrity Value in that order,
with the five strings being separated by four period ('.') with the five strings being separated by four period ('.')
characters. characters.
AEAD Algorithm An Authenticated Encryption with Associated Data Authenticated Encryption An Authenticated Encryption algorithm is
(AEAD) [RFC5116] encryption algorithm is one that provides an one that provides an integrated content integrity check.
integrated content integrity check. AEAD encryption algorithms Authenticated Encryption algorithms accept two inputs, the
accept two inputs, the plaintext and the "additional authenticated plaintext and the "additional authenticated data" value, and
data" value, and produce two outputs, the ciphertext and the produce two outputs, the ciphertext and the "authentication tag"
"authentication tag" value. AES Galois/Counter Mode (GCM) is one value. AES Galois/Counter Mode (GCM) is one such algorithm.
such algorithm.
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. For instance, collision resistance can
be achieved through administrative delegation of portions of the be achieved through administrative delegation of portions of the
namespace or through use of collision-resistant name allocation namespace or through use of collision-resistant name allocation
functions. Examples of Collision Resistant Namespaces include: functions. Examples of Collision Resistant Namespaces include:
Domain Names, Object Identifiers (OIDs) as defined in the ITU-T Domain Names, Object Identifiers (OIDs) as defined in the ITU-T
X.660 and X.670 Recommendation series, and Universally Unique X.660 and X.670 Recommendation series, and Universally Unique
IDentifiers (UUIDs) [RFC4122]. When using an administratively IDentifiers (UUIDs) [RFC4122]. When using an administratively
skipping to change at page 12, line 11 skipping to change at page 12, line 11
exists. If the "enc" member exists, it is a JWE; otherwise, it is a exists. If the "enc" member exists, it is a JWE; otherwise, it is a
JWS. Both methods will yield the same result for all legal input JWS. Both methods will yield the same result for all legal input
values. values.
There are three classes of Header Parameter Names: Reserved Header There are three classes of Header Parameter Names: Reserved Header
Parameter Names, Public Header Parameter Names, and Private Header Parameter Names, Public Header Parameter Names, and Private Header
Parameter Names. Parameter Names.
4.1. Reserved Header Parameter Names 4.1. Reserved Header Parameter Names
The following header parameter names are reserved with meanings as The following Header Parameter Names are reserved with meanings as
defined below. All the names are short because a core goal of JWE is defined below. All the names are short because a core goal of JWE is
for the representations to be compact. for the representations to be compact.
Additional reserved header parameter names MAY be defined via the Additional reserved Header Parameter Names MAY be defined via the
IANA JSON Web Signature and Encryption Header Parameters registry IANA JSON Web Signature and Encryption Header Parameters registry
[JWS]. As indicated by the common registry, JWSs and JWEs share a [JWS]. As indicated by the common registry, JWSs and JWEs share a
common header parameter space; when a parameter is used by both common header parameter space; when a parameter is used by both
specifications, its usage must be compatible between the specifications, its usage must be compatible between the
specifications. specifications.
4.1.1. "alg" (Algorithm) Header Parameter 4.1.1. "alg" (Algorithm) Header Parameter
The "alg" (algorithm) header parameter identifies the cryptographic The "alg" (algorithm) header parameter identifies the cryptographic
algorithm used to encrypt or determine the value of the Content algorithm used to encrypt or determine the value of the Content
Master Key (CMK). The algorithm specified by the "alg" value MUST be Master Key (CMK). The algorithm specified by the "alg" value MUST be
supported by the implementation and there MUST be a key for use with supported by the implementation and there MUST be a key for use with
that algorithm associated with the intended recipient or the JWE MUST that algorithm associated with the intended recipient or the JWE MUST
be rejected. "alg" values SHOULD either be registered in the IANA be rejected. "alg" values SHOULD either be registered in the IANA
JSON Web Signature and Encryption Algorithms registry [JWA] or be a JSON Web Signature and Encryption Algorithms registry [JWA] or be a
URI that contains a Collision Resistant Namespace. The "alg" value value that contains a Collision Resistant Namespace. The "alg" value
is a case sensitive string containing a StringOrURI value. This is a case sensitive string containing a StringOrURI value. Use of
header parameter is REQUIRED. this header parameter is REQUIRED.
A list of defined "alg" values can be found in the IANA JSON Web A list of defined "alg" values can be found in the IANA JSON Web
Signature and Encryption Algorithms registry [JWA]; the initial Signature and Encryption Algorithms registry [JWA]; the initial
contents of this registry are the values defined in Section 4.1 of contents of this registry are the values defined in Section 4.1 of
the JSON Web Algorithms (JWA) [JWA] specification. the JSON Web Algorithms (JWA) [JWA] specification.
4.1.2. "enc" (Encryption Method) Header Parameter 4.1.2. "enc" (Encryption Method) Header Parameter
The "enc" (encryption method) header parameter identifies the block The "enc" (encryption method) header parameter identifies the block
encryption algorithm used to encrypt the Plaintext to produce the encryption algorithm used to encrypt the Plaintext to produce the
Ciphertext. This algorithm MUST be an AEAD algorithm with a Ciphertext. This algorithm MUST be an Authenticated Encryption
specified key length. The algorithm specified by the "enc" value algorithm with a specified key length. The algorithm specified by
MUST be supported by the implementation or the JWE MUST be rejected. the "enc" value MUST be supported by the implementation or the JWE
"enc" values SHOULD either be registered in the IANA JSON Web MUST be rejected. "enc" values SHOULD either be registered in the
Signature and Encryption Algorithms registry [JWA] or be a URI that IANA JSON Web Signature and Encryption Algorithms registry [JWA] or
contains a Collision Resistant Namespace. The "enc" value is a case be a value that contains a Collision Resistant Namespace. The "enc"
sensitive string containing a StringOrURI value. This header value is a case sensitive string containing a StringOrURI value. Use
parameter is REQUIRED. of this header parameter is REQUIRED.
A list of defined "enc" values can be found in the IANA JSON Web A list of defined "enc" values can be found in the IANA JSON Web
Signature and Encryption Algorithms registry [JWA]; the initial Signature and Encryption Algorithms registry [JWA]; the initial
contents of this registry are the values defined in Section 4.2 of contents of this registry are the values defined in Section 4.2 of
the JSON Web Algorithms (JWA) [JWA] specification. the JSON Web Algorithms (JWA) [JWA] specification.
4.1.3. "epk" (Ephemeral Public Key) Header Parameter 4.1.3. "epk" (Ephemeral Public Key) Header Parameter
The "epk" (ephemeral public key) value created by the originator for The "epk" (ephemeral public key) value created by the originator for
the use in key agreement algorithms. This key is represented as a the use in key agreement algorithms. This key is represented as a
JSON Web Key [JWK] value. This header parameter is OPTIONAL, JSON Web Key [JWK] value. Use of this header parameter is OPTIONAL,
although its use is REQUIRED with some "alg" algorithms. although its use is REQUIRED with some "alg" algorithms.
4.1.4. "zip" (Compression Algorithm) Header Parameter 4.1.4. "zip" (Compression Algorithm) Header Parameter
The "zip" (compression algorithm) applied to the Plaintext before The "zip" (compression algorithm) applied to the Plaintext before
encryption, if any. If present, the value of the "zip" header encryption, if any. If present, the value of the "zip" header
parameter MUST be the case sensitive string "DEF". Compression is parameter MUST be the case sensitive string "DEF". Compression is
performed with the DEFLATE [RFC1951] algorithm. If no "zip" performed with the DEFLATE [RFC1951] algorithm. If no "zip"
parameter is present, no compression is applied to the Plaintext parameter is present, no compression is applied to the Plaintext
before encryption. This header parameter is OPTIONAL. before encryption. Use of this header parameter is OPTIONAL.
4.1.5. "jku" (JWK Set URL) Header Parameter 4.1.5. "jku" (JWK Set URL) Header Parameter
The "jku" (JWK Set URL) header parameter is a URI [RFC3986] that The "jku" (JWK Set URL) header parameter is a URI [RFC3986] that
refers to a resource for a set of JSON-encoded public keys, one of refers to a resource for a set of JSON-encoded public keys, one of
which corresponds to the key used to encrypt the JWE; this can be which corresponds to the key used to encrypt the JWE; this can be
used to determine the private key needed to decrypt the JWE. The used to determine the private key needed to decrypt the JWE. The
keys MUST be encoded as a JSON Web Key Set (JWK Set) [JWK]. The keys MUST be encoded as a JSON Web Key Set (JWK Set) [JWK]. The
protocol used to acquire the resource MUST provide integrity protocol used to acquire the resource MUST provide integrity
protection; an HTTP GET request to retrieve the certificate MUST use protection; an HTTP GET request to retrieve the certificate MUST use
TLS [RFC2818] [RFC5246]; the identity of the server MUST be TLS [RFC2818] [RFC5246]; the identity of the server MUST be
validated, as per Section 3.1 of HTTP Over TLS [RFC2818]. This validated, as per Section 3.1 of HTTP Over TLS [RFC2818]. Use of
header parameter is OPTIONAL. this header parameter is OPTIONAL.
4.1.6. "jwk" (JSON Web Key) Header Parameter 4.1.6. "jwk" (JSON Web Key) Header Parameter
The "jwk" (JSON Web Key) header parameter is a public key that The "jwk" (JSON Web Key) header parameter is a public key that
corresponds to the key used to encrypt the JWE; this can be used to corresponds to the key used to encrypt the JWE; this can be used to
determine the private key needed to decrypt the JWE. This key is determine the private key needed to decrypt the JWE. This key is
represented as a JSON Web Key [JWK]. This header parameter is represented as a JSON Web Key [JWK]. Use of this header parameter is
OPTIONAL. OPTIONAL.
4.1.7. "x5u" (X.509 URL) Header Parameter 4.1.7. "x5u" (X.509 URL) Header Parameter
The "x5u" (X.509 URL) header parameter is a URI [RFC3986] that refers The "x5u" (X.509 URL) header parameter is a URI [RFC3986] that refers
to a resource for the X.509 public key certificate or certificate to a resource for the X.509 public key certificate or certificate
chain [RFC5280] corresponding to the key used to encrypt the JWE; chain [RFC5280] corresponding to the key used to encrypt the JWE;
this can be used to determine the private key needed to decrypt the this can be used to determine the private key needed to decrypt the
JWE. The identified resource MUST provide a representation of the JWE. The identified resource MUST provide a representation of the
certificate or certificate chain that conforms to RFC 5280 [RFC5280] certificate or certificate chain that conforms to RFC 5280 [RFC5280]
in PEM encoded form [RFC1421]. The certificate containing the public in PEM encoded form [RFC1421]. The certificate containing the public
key of the entity that encrypted the JWE MUST be the first key of the entity that encrypted the JWE MUST be the first
certificate. This MAY be followed by additional certificates, with certificate. This MAY be followed by additional certificates, with
each subsequent certificate being the one used to certify the each subsequent certificate being the one used to certify the
previous one. The protocol used to acquire the resource MUST provide previous one. The protocol used to acquire the resource MUST provide
integrity protection; an HTTP GET request to retrieve the certificate integrity protection; an HTTP GET request to retrieve the certificate
MUST use TLS [RFC2818] [RFC5246]; the identity of the server MUST be MUST use TLS [RFC2818] [RFC5246]; the identity of the server MUST be
validated, as per Section 3.1 of HTTP Over TLS [RFC2818]. This validated, as per Section 3.1 of HTTP Over TLS [RFC2818]. Use of
header parameter is OPTIONAL. this header parameter is OPTIONAL.
4.1.8. "x5t" (X.509 Certificate Thumbprint) Header Parameter 4.1.8. "x5t" (X.509 Certificate Thumbprint) Header Parameter
The "x5t" (X.509 Certificate Thumbprint) header parameter provides a The "x5t" (X.509 Certificate Thumbprint) header parameter provides a
base64url encoded SHA-1 thumbprint (a.k.a. digest) of the DER base64url encoded SHA-1 thumbprint (a.k.a. digest) of the DER
encoding of the X.509 certificate [RFC5280] corresponding to the key encoding of the X.509 certificate [RFC5280] corresponding to the key
used to encrypt the JWE; this can be used to determine the private used to encrypt the JWE; this can be used to determine the private
key needed to decrypt the JWE. This header parameter is OPTIONAL. key needed to decrypt the JWE. Use of this header parameter is
OPTIONAL.
If, in the future, certificate thumbprints need to be computed using If, in the future, certificate thumbprints need to be computed using
hash functions other than SHA-1, it is suggested that additional hash functions other than SHA-1, it is suggested that additional
related header parameters be defined for that purpose. For example, related header parameters be defined for that purpose. For example,
it is suggested that a new "x5t#S256" (X.509 Certificate Thumbprint it is suggested that a new "x5t#S256" (X.509 Certificate Thumbprint
using SHA-256) header parameter could be defined by registering it in using SHA-256) header parameter could be defined by registering it in
the IANA JSON Web Signature and Encryption Header Parameters registry the IANA JSON Web Signature and Encryption Header Parameters registry
[JWS]. [JWS].
4.1.9. "x5c" (X.509 Certificate Chain) Header Parameter 4.1.9. "x5c" (X.509 Certificate Chain) Header Parameter
skipping to change at page 14, line 46 skipping to change at page 14, line 47
corresponding to the key used to encrypt the JWE; this can be used to corresponding to the key used to encrypt the JWE; this can be used to
determine the private key needed to decrypt the JWE. The certificate determine the private key needed to decrypt the JWE. The certificate
or certificate chain is represented as an array of certificate value or certificate chain is represented as an array of certificate value
strings. Each string is a base64 encoded ([RFC4648] Section 4 -- not strings. Each string is a base64 encoded ([RFC4648] Section 4 -- not
base64url encoded) DER [ITU.X690.1994] PKIX certificate value. The base64url encoded) DER [ITU.X690.1994] PKIX certificate value. The
certificate containing the public key of the entity that encrypted certificate containing the public key of the entity that encrypted
the JWE MUST be the first certificate. This MAY be followed by the JWE MUST be the first certificate. This MAY be followed by
additional certificates, with each subsequent certificate being the additional certificates, with each subsequent certificate being the
one used to certify the previous one. The recipient MUST verify the one used to certify the previous one. The recipient MUST verify the
certificate chain according to [RFC5280] and reject the JWE if any certificate chain according to [RFC5280] and reject the JWE if any
validation failure occurs. This header parameter is OPTIONAL. validation failure occurs. Use of this header parameter is OPTIONAL.
See Appendix B of [JWS] for an example "x5c" value. See Appendix B of [JWS] for an example "x5c" value.
4.1.10. "kid" (Key ID) Header Parameter 4.1.10. "kid" (Key ID) Header Parameter
The "kid" (key ID) header parameter is a hint indicating which key The "kid" (key ID) header parameter is a hint indicating which key
was used to encrypt the JWE; this can be used to determine the was used to encrypt the JWE; this can be used to determine the
private key needed to decrypt the JWE. This parameter allows private key needed to decrypt the JWE. This parameter allows
originators to explicitly signal a change of key to recipients. originators to explicitly signal a change of key to recipients.
Should the recipient be unable to locate a key corresponding to the Should the recipient be unable to locate a key corresponding to the
"kid" value, they SHOULD treat that condition as an error. The "kid" value, they SHOULD treat that condition as an error. The
interpretation of the "kid" value is unspecified. Its value MUST be interpretation of the "kid" value is unspecified. Its value MUST be
a string. This header parameter is OPTIONAL. a string. Use of this header parameter is OPTIONAL.
When used with a JWK, the "kid" value MAY be used to match a JWK When used with a JWK, the "kid" value MAY be used to match a JWK
"kid" parameter value. "kid" parameter value.
4.1.11. "typ" (Type) Header Parameter 4.1.11. "typ" (Type) Header Parameter
The "typ" (type) header parameter is used to declare the type of this The "typ" (type) header parameter is used to declare the type of this
object. The type value "JWE" MAY be used to indicate that this object. The type value "JWE" MAY be used to indicate that this
object is a JWE. The "typ" value is a case sensitive string. This object is a JWE. The "typ" value is a case sensitive string. Use of
header parameter is OPTIONAL. this header parameter is OPTIONAL.
MIME Media Type [RFC2046] values MAY be used as "typ" values. MIME Media Type [RFC2046] values MAY be used as "typ" values.
"typ" values SHOULD either be registered in the IANA JSON Web "typ" values SHOULD either be registered in the IANA JSON Web
Signature and Encryption Type Values registry [JWS] or be a URI that Signature and Encryption Type Values registry [JWS] or be a value
contains a Collision Resistant Namespace. that contains a Collision Resistant Namespace.
4.1.12. "cty" (Content Type) Header Parameter 4.1.12. "cty" (Content Type) Header Parameter
The "cty" (content type) header parameter is used to declare the type The "cty" (content type) header parameter is used to declare the type
of the encrypted content (the Plaintext). The "cty" value is a case of the encrypted content (the Plaintext). The "cty" value is a case
sensitive string. This header parameter is OPTIONAL. sensitive string. Use of this header parameter is OPTIONAL.
The values used for the "cty" header parameter come from the same The values used for the "cty" header parameter come from the same
value space as the "typ" header parameter, with the same rules value space as the "typ" header parameter, with the same rules
applying. applying.
4.1.13. "apu" (Agreement PartyUInfo) Header Parameter 4.1.13. "apu" (Agreement PartyUInfo) Header Parameter
The "apu" (agreement PartyUInfo) value for key agreement algorithms The "apu" (agreement PartyUInfo) value for key agreement algorithms
using it (such as "ECDH-ES"), represented as a base64url encoded using it (such as "ECDH-ES"), represented as a base64url encoded
string. This header parameter is OPTIONAL. string. Use of this header parameter is OPTIONAL.
4.1.14. "apv" (Agreement PartyVInfo) Header Parameter 4.1.14. "apv" (Agreement PartyVInfo) Header Parameter
The "apv" (agreement PartyVInfo) value for key agreement algorithms The "apv" (agreement PartyVInfo) value for key agreement algorithms
using it (such as "ECDH-ES"), represented as a base64url encoded using it (such as "ECDH-ES"), represented as a base64url encoded
string. This header parameter is OPTIONAL. string. Use of this header parameter is OPTIONAL.
4.1.15. "epu" (Encryption PartyUInfo) Header Parameter 4.1.15. "epu" (Encryption PartyUInfo) Header Parameter
The "epu" (encryption PartyUInfo) value for plaintext encryption The "epu" (encryption PartyUInfo) value for plaintext encryption
algorithms using it (such as "A128CBC+HS256"), represented as a algorithms using it (such as "A128CBC+HS256"), represented as a
base64url encoded string. This header parameter is OPTIONAL. base64url encoded string. Use of this header parameter is OPTIONAL.
4.1.16. "epv" (Encryption PartyVInfo) Header Parameter 4.1.16. "epv" (Encryption PartyVInfo) Header Parameter
The "epv" (encryption PartyVInfo) value for plaintext encryption The "epv" (encryption PartyVInfo) value for plaintext encryption
algorithms using it (such as "A128CBC+HS256"), represented as a algorithms using it (such as "A128CBC+HS256"), represented as a
base64url encoded string. This header parameter is OPTIONAL. base64url encoded string. Use of this header parameter is OPTIONAL.
4.2. Public Header Parameter Names 4.2. Public Header Parameter Names
Additional header parameter names can be defined by those using JWEs. Additional Header Parameter Names can be defined by those using JWEs.
However, in order to prevent collisions, any new header parameter However, in order to prevent collisions, any new Header Parameter
name SHOULD either be registered in the IANA JSON Web Signature and Name SHOULD either be registered in the IANA JSON Web Signature and
Encryption Header Parameters registry [JWS] or be a URI that contains Encryption Header Parameters registry [JWS] or be a Public Name: a
a Collision Resistant Namespace. In each case, the definer of the value that contains a Collision Resistant Namespace. In each case,
name or value needs to take reasonable precautions to make sure they the definer of the name or value needs to take reasonable precautions
are in control of the part of the namespace they use to define the to make sure they are in control of the part of the namespace they
header parameter name. use to define the Header Parameter Name.
New header parameters should be introduced sparingly, as they can New header parameters should be introduced sparingly, as they can
result in non-interoperable JWEs. result in non-interoperable JWEs.
4.3. Private Header Parameter Names 4.3. Private Header Parameter Names
A producer and consumer of a JWE may agree to any header parameter A producer and consumer of a JWE may agree to use Header Parameter
name that is not a Reserved Name Section 4.1 or a Public Name Names that are Private Names: names that are not Reserved Names
Section 4.2. Unlike Public Names, these private names are subject to Section 4.1 or Public Names Section 4.2. Unlike Public Names,
collision and should be used with caution. Private Names are subject to collision and should be used with
caution.
5. Message Encryption 5. Producing and Consuming JWEs
5.1. Message Encryption
The message encryption process is as follows. The order of the steps The message encryption process is as follows. The order of the steps
is not significant in cases where there are no dependencies between is not significant in cases where there are no dependencies between
the inputs and outputs of the steps. the inputs and outputs of the steps.
1. When key wrapping, key encryption, or key agreement with key 1. When key wrapping, key encryption, or key agreement with key
wrapping are employed, generate a random Content Master Key wrapping are employed, generate a random Content Master Key
(CMK). See RFC 4086 [RFC4086] for considerations on generating (CMK). See RFC 4086 [RFC4086] for considerations on generating
random values. The CMK MUST have a length equal to that random values. The CMK MUST have a length equal to that
required for the block encryption algorithm. required for the block encryption algorithm.
2. When key agreement is employed, use the key agreement algorithm 2. When key agreement is employed, use the key agreement algorithm
to compute the value of the agreed upon key. When key agreement to compute the value of the agreed upon key. When key agreement
without key wrapping is employed, let the Content Master Key without key wrapping is employed, let the Content Master Key
(CMK) be the agreed upon key. When key agreement with key (CMK) be the agreed upon key. When key agreement with key
wrapping is employed, the agreed upon key will be used to wrap wrapping is employed, the agreed upon key will be used to wrap
the CMK. the CMK.
3. When key wrapping, key encryption, or key agreement with key 3. When key wrapping, key encryption, or key agreement with key
wrapping are employed, encrypt the CMK for the recipient (see wrapping are employed, encrypt the CMK for the recipient (see
Section 7) and let the result be the JWE Encrypted Key. Section 6.1) and let the result be the JWE Encrypted Key.
Otherwise, when direct encryption with a shared or agreed upon Otherwise, when direct encryption with a shared or agreed upon
symmetric key is employed, let the JWE Encrypted Key be the symmetric key is employed, let the JWE Encrypted Key be the
empty byte array. empty byte array.
4. When direct encryption with a shared symmetric key is employed, 4. When direct encryption with a shared symmetric key is employed,
let the Content Master Key (CMK) be the shared key. let the Content Master Key (CMK) be the shared key.
5. Base64url encode the JWE Encrypted Key to create the Encoded JWE 5. Base64url encode the JWE Encrypted Key to create the Encoded JWE
Encrypted Key. Encrypted Key.
skipping to change at page 18, line 20 skipping to change at page 18, line 22
JWE Integrity Value. JWE Integrity Value.
16. The five encoded parts, taken together, are the result. 16. The five encoded parts, taken together, are the result.
17. The Compact Serialization of this result is the concatenation of 17. The Compact Serialization of this result is the concatenation of
the Encoded JWE Header, the Encoded JWE Encrypted Key, the the Encoded JWE Header, the Encoded JWE Encrypted Key, the
Encoded JWE Initialization Vector, the Encoded JWE Ciphertext, Encoded JWE Initialization Vector, the Encoded JWE Ciphertext,
and the Encoded JWE Integrity Value in that order, with the five and the Encoded JWE Integrity Value in that order, with the five
strings being separated by four period ('.') characters. strings being separated by four period ('.') characters.
6. Message Decryption 5.2. Message Decryption
The message decryption process is the reverse of the encryption The message decryption process is the reverse of the encryption
process. The order of the steps is not significant in cases where process. The order of the steps is not significant in cases where
there are no dependencies between the inputs and outputs of the there are no dependencies between the inputs and outputs of the
steps. If any of these steps fails, the JWE MUST be rejected. steps. If any of these steps fails, the JWE MUST be rejected.
1. Determine the Encoded JWE Header, the Encoded JWE Encrypted Key, 1. Determine the Encoded JWE Header, the Encoded JWE Encrypted Key,
the Encoded JWE Initialization Vector, the Encoded JWE the Encoded JWE Initialization Vector, the Encoded JWE
Ciphertext, and the Encoded JWE Integrity Value values contained Ciphertext, and the Encoded JWE Integrity Value values contained
in the JWE. When using the Compact Serialization, these five in the JWE. When using the Compact Serialization, these five
skipping to change at page 19, line 37 skipping to change at page 19, line 40
returning the decrypted plaintext and verifying the JWE returning the decrypted plaintext and verifying the JWE
Integrity Value in the manner specified for the algorithm, Integrity Value in the manner specified for the algorithm,
rejecting the input without emitting any decrypted output if the rejecting the input without emitting any decrypted output if the
JWE Integrity Value is incorrect. JWE Integrity Value is incorrect.
11. Uncompress the decrypted plaintext if a "zip" parameter was 11. Uncompress the decrypted plaintext if a "zip" parameter was
included. included.
12. Output the resulting Plaintext. 12. Output the resulting Plaintext.
7. CMK Encryption 5.3. String Comparison Rules
JWE supports three forms of Content Master Key (CMK) encryption:
o Asymmetric encryption under the recipient's public key.
o Symmetric encryption under a key shared between the sender and
receiver.
o Symmetric encryption under a key agreed upon between the sender Processing a JWE inevitably requires comparing known strings to
and receiver. values in JSON objects. For example, in checking what the encryption
method is, the Unicode string encoding "enc" will be checked against
the member names in the JWE Header to see if there is a matching
Header Parameter Name.
See the algorithms registered for "enc" usage in the IANA JSON Web Comparisons between JSON strings and other Unicode strings MUST be
Signature and Encryption Algorithms registry [JWA] and Section 4.1 of performed by comparing Unicode code points without normalization as
the JSON Web Algorithms (JWA) [JWA] specification for lists of specified in the String Comparison Rules in Section 5.3 of [JWS].
encryption algorithms that can be used for CMK encryption.
8. Encrypting JWEs with Cryptographic Algorithms 6. Encrypting JWEs with Cryptographic Algorithms
JWE uses cryptographic algorithms to encrypt the Plaintext and the JWE uses cryptographic algorithms to encrypt the Plaintext and the
Content Encryption Key (CMK) and to provide integrity protection for Content Encryption Key (CMK) and to provide integrity protection for
the JWE Header, JWE Encrypted Key, and JWE Ciphertext. The JSON Web the JWE Header, JWE Encrypted Key, and JWE Ciphertext. The JSON Web
Algorithms (JWA) [JWA] specification specifies a set of cryptographic Algorithms (JWA) [JWA] specification specifies a set of cryptographic
algorithms and identifiers to be used with this specification and algorithms and identifiers to be used with this specification and
defines registries for additional such algorithms. Specifically, defines registries for additional such algorithms. Specifically,
Section 4.1 specifies a set of "alg" (algorithm) header parameter Section 4.1 specifies a set of "alg" (algorithm) header parameter
values and Section 4.2 specifies a set of "enc" (encryption method) values and Section 4.2 specifies a set of "enc" (encryption method)
header parameter values intended for use this specification. It also header parameter values intended for use this specification. It also
describes the semantics and operations that are specific to these describes the semantics and operations that are specific to these
algorithms and algorithm families. algorithms.
Public keys employed for encryption can be identified using the Public keys employed for encryption can be identified using the
Header Parameter methods described in Section 4.1 or can be Header Parameter methods described in Section 4.1 or can be
distributed using methods that are outside the scope of this distributed using methods that are outside the scope of this
specification. specification.
9. IANA Considerations 6.1. CMK Encryption
9.1. Registration of JWE Header Parameter Names JWE supports three forms of Content Master Key (CMK) encryption:
o Asymmetric encryption under the recipient's public key.
o Symmetric encryption under a key shared between the sender and
receiver.
o Symmetric encryption under a key agreed upon between the sender
and receiver.
See the algorithms registered for "enc" usage in the IANA JSON Web
Signature and Encryption Algorithms registry [JWA] and Section 4.1 of
the JSON Web Algorithms (JWA) [JWA] specification for lists of
encryption algorithms that can be used for CMK encryption.
7. IANA Considerations
7.1. Registration of JWE Header Parameter Names
This specification registers the Header Parameter Names defined in This specification registers the Header Parameter Names defined in
Section 4.1 in the IANA JSON Web Signature and Encryption Header Section 4.1 in the IANA JSON Web Signature and Encryption Header
Parameters registry [JWS]. Parameters registry [JWS].
9.1.1. Registry Contents 7.1.1. Registry Contents
o Header Parameter Name: "alg" o Header Parameter Name: "alg"
o Header Parameter Usage Location(s): JWE
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.1.1 of [[ this document ]] o Specification Document(s): Section 4.1.1 of [[ this document ]]
o Header Parameter Name: "enc" o Header Parameter Name: "enc"
o Header Parameter Usage Location(s): JWE
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.1.2 of [[ this document ]] o Specification Document(s): Section 4.1.2 of [[ this document ]]
o Header Parameter Name: "epk" o Header Parameter Name: "epk"
o Header Parameter Usage Location(s): JWE
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.1.3 of [[ this document ]] o Specification Document(s): Section 4.1.3 of [[ this document ]]
o Header Parameter Name: "zip" o Header Parameter Name: "zip"
o Header Parameter Usage Location(s): JWE
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.1.4 of [[ this document ]] o Specification Document(s): Section 4.1.4 of [[ this document ]]
o Header Parameter Name: "jku" o Header Parameter Name: "jku"
o Header Parameter Usage Location(s): JWE
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.1.5 of [[ this document ]] o Specification Document(s): Section 4.1.5 of [[ this document ]]
o Header Parameter Name: "jwk" o Header Parameter Name: "jwk"
o Header Parameter Usage Location(s): JWE
o Change Controller: IETF o Change Controller: IETF
o Specification document(s): Section 4.1.6 of [[ this document ]] o Specification document(s): Section 4.1.6 of [[ this document ]]
o Header Parameter Name: "x5u" o Header Parameter Name: "x5u"
o Header Parameter Usage Location(s): JWE
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.1.7 of [[ this document ]] o Specification Document(s): Section 4.1.7 of [[ this document ]]
o Header Parameter Name: "x5t" o Header Parameter Name: "x5t"
o Header Parameter Usage Location(s): JWE
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.1.8 of [[ this document ]] o Specification Document(s): Section 4.1.8 of [[ this document ]]
o Header Parameter Name: "x5c" o Header Parameter Name: "x5c"
o Header Parameter Usage Location(s): JWE
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.1.9 of [[ this document ]] o Specification Document(s): Section 4.1.9 of [[ this document ]]
o Header Parameter Name: "kid" o Header Parameter Name: "kid"
o Header Parameter Usage Location(s): JWE
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.1.10 of [[ this document ]] o Specification Document(s): Section 4.1.10 of [[ this document ]]
o Header Parameter Name: "typ" o Header Parameter Name: "typ"
o Header Parameter Usage Location(s): JWE
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.1.11 of [[ this document ]] o Specification Document(s): Section 4.1.11 of [[ this document ]]
o Header Parameter Name: "cty" o Header Parameter Name: "cty"
o Header Parameter Usage Location(s): JWE
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.1.12 of [[ this document ]] o Specification Document(s): Section 4.1.12 of [[ this document ]]
o Header Parameter Name: "apu" o Header Parameter Name: "apu"
o Header Parameter Usage Location(s): JWE
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.1.13 of [[ this document ]] o Specification Document(s): Section 4.1.13 of [[ this document ]]
o Header Parameter Name: "apv" o Header Parameter Name: "apv"
o Header Parameter Usage Location(s): JWE
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.1.14 of [[ this document ]] o Specification Document(s): Section 4.1.14 of [[ this document ]]
o Header Parameter Name: "epu" o Header Parameter Name: "epu"
o Header Parameter Usage Location(s): JWE
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.1.15 of [[ this document ]] o Specification Document(s): Section 4.1.15 of [[ this document ]]
o Header Parameter Name: "epv" o Header Parameter Name: "epv"
o Header Parameter Usage Location(s): JWE
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.1.16 of [[ this document ]] o Specification Document(s): Section 4.1.16 of [[ this document ]]
9.2. JSON Web Signature and Encryption Type Values Registration 7.2. JSON Web Signature and Encryption Type Values Registration
9.2.1. Registry Contents 7.2.1. Registry Contents
This specification registers the "JWE" type value in the IANA JSON This specification registers the "JWE" type value in the IANA JSON
Web Signature and Encryption Type Values registry [JWS]: Web Signature and Encryption Type Values registry [JWS]:
o "typ" Header Parameter Value: "JWE" o "typ" Header Parameter Value: "JWE"
o Abbreviation for MIME Type: application/jwe o Abbreviation for MIME Type: application/jwe
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.1.11 of [[ this document ]] o Specification Document(s): Section 4.1.11 of [[ this document ]]
9.3. Media Type Registration 7.3. Media Type Registration
9.3.1. Registry Contents 7.3.1. Registry Contents
This specification registers the "application/jwe" Media Type This specification registers the "application/jwe" Media Type
[RFC2046] in the MIME Media Type registry [RFC4288] to indicate that [RFC2046] in the MIME Media Type registry [RFC4288] to indicate that
the content is a JWE using the Compact Serialization. the content is a JWE using the Compact Serialization.
o Type Name: application o Type Name: application
o Subtype Name: jwe o Subtype Name: jwe
o Required Parameters: n/a o Required Parameters: n/a
o Optional Parameters: n/a o Optional Parameters: n/a
o Encoding considerations: JWE values are encoded as a series of o Encoding considerations: JWE values are encoded as a series of
skipping to change at page 23, line 6 skipping to change at page 23, line 35
applications using encrypted JWTs applications using encrypted JWTs
o Additional Information: Magic number(s): n/a, File extension(s): o Additional Information: Magic number(s): n/a, File extension(s):
n/a, Macintosh file type code(s): n/a n/a, Macintosh file type code(s): n/a
o Person & email address to contact for further information: Michael o Person & email address to contact for further information: Michael
B. Jones, mbj@microsoft.com B. Jones, mbj@microsoft.com
o Intended Usage: COMMON o Intended Usage: COMMON
o Restrictions on Usage: none o Restrictions on Usage: none
o Author: Michael B. Jones, mbj@microsoft.com o Author: Michael B. Jones, mbj@microsoft.com
o Change Controller: IETF o Change Controller: IETF
10. Security Considerations 8. 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 key, preventing various attacks, and protecting the user's private and symmetric keys, preventing various
helping the user avoid mistakes such as inadvertently encrypting a attacks, and helping the user avoid mistakes such as inadvertently
message for the wrong recipient. The entire list of security encrypting a message for the wrong recipient. The entire list of
considerations is beyond the scope of this document, but some security considerations is beyond the scope of this document.
significant concerns are listed here.
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.CR-xmlenc-core1-20120313] also apply to JWE, XML Encryption 1.1 [W3C.CR-xmlenc-core1-20120313] also apply to JWE,
other than those that are XML specific. other than those that are XML specific.
11. References 9. References
9.1. Normative References
11.1. Normative References
[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)", November 2012. [JWA] Jones, M., "JSON Web Algorithms (JWA)",
draft-ietf-jose-json-web-algorithms (work in progress),
December 2012.
[JWK] Jones, M., "JSON Web Key (JWK)", November 2012. [JWK] Jones, M., "JSON Web Key (JWK)",
draft-ietf-jose-json-web-key (work in progress),
December 2012.
[JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web
Signature (JWS)", November 2012. Signature (JWS)", draft-ietf-jose-json-web-signature (work
in progress), December 2012.
[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.
[RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification
version 1.3", RFC 1951, May 1996. version 1.3", RFC 1951, May 1996.
[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,
skipping to change at page 24, line 29 skipping to change at page 25, line 12
[RFC4288] Freed, N. and J. Klensin, "Media Type Specifications and [RFC4288] Freed, N. and J. Klensin, "Media Type Specifications and
Registration Procedures", BCP 13, RFC 4288, December 2005. Registration Procedures", BCP 13, RFC 4288, December 2005.
[RFC4627] Crockford, D., "The application/json Media Type for [RFC4627] Crockford, D., "The application/json Media Type for
JavaScript Object Notation (JSON)", RFC 4627, July 2006. JavaScript Object Notation (JSON)", RFC 4627, July 2006.
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
Encodings", RFC 4648, October 2006. Encodings", RFC 4648, October 2006.
[RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated
Encryption", RFC 5116, January 2008.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", RFC 5246, August 2008. (TLS) Protocol Version 1.2", RFC 5246, August 2008.
[RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S.,
Housley, R., and W. Polk, "Internet X.509 Public Key Housley, R., and W. Polk, "Internet X.509 Public Key
Infrastructure Certificate and Certificate Revocation List Infrastructure Certificate and Certificate Revocation List
(CRL) Profile", RFC 5280, May 2008. (CRL) Profile", RFC 5280, May 2008.
[W3C.CR-xmlenc-core1-20120313] [W3C.CR-xmlenc-core1-20120313]
Eastlake, D., Reagle, J., Roessler, T., and F. Hirsch, Eastlake, D., Reagle, J., Roessler, T., and F. Hirsch,
"XML Encryption Syntax and Processing Version 1.1", World "XML Encryption Syntax and Processing Version 1.1", World
Wide Web Consortium CR CR-xmlenc-core1-20120313, Wide Web Consortium CR CR-xmlenc-core1-20120313,
March 2012, March 2012,
<http://www.w3.org/TR/2012/CR-xmlenc-core1-20120313>. <http://www.w3.org/TR/2012/CR-xmlenc-core1-20120313>.
11.2. Informative References 9.2. Informative References
[I-D.rescorla-jsms] [I-D.rescorla-jsms]
Rescorla, E. and J. Hildebrand, "JavaScript Message Rescorla, E. and J. Hildebrand, "JavaScript Message
Security Format", draft-rescorla-jsms-00 (work in Security Format", draft-rescorla-jsms-00 (work in
progress), March 2011. progress), March 2011.
[JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple [JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple
Encryption", September 2010. Encryption", September 2010.
[JWE-JS] Jones, M., "JSON Web Encryption JSON Serialization [JWE-JS] Jones, M., "JSON Web Encryption JSON Serialization
(JWE-JS)", November 2012. (JWE-JS)", draft-jones-jose-jwe-json-serialization (work
in progress), December 2012.
[RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally
Unique IDentifier (UUID) URN Namespace", RFC 4122, Unique IDentifier (UUID) URN Namespace", RFC 4122,
July 2005. July 2005.
[RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70,
RFC 5652, September 2009. RFC 5652, September 2009.
Appendix A. JWE Examples Appendix A. JWE Examples
skipping to change at page 30, line 37 skipping to change at page 31, line 37
O6JHkWLuAEYoe58lcxIQneyKdaYSLbV9cKqoUoFQpvKWYRHZbfszIyfsa18rmgTj O6JHkWLuAEYoe58lcxIQneyKdaYSLbV9cKqoUoFQpvKWYRHZbfszIyfsa18rmgTj
zrtLDTPnc09DSJE24aQ8w3i8RXEDthW9T1J6LsTH_vwHdwUgkI-tC2PNeGrnM-dN zrtLDTPnc09DSJE24aQ8w3i8RXEDthW9T1J6LsTH_vwHdwUgkI-tC2PNeGrnM-dN
SfzF3Y7-lwcGy0FsdXkPXytvDV7y4pZeeUiQ-0VdibIN2AjjfW60nfrPuOjepMFG SfzF3Y7-lwcGy0FsdXkPXytvDV7y4pZeeUiQ-0VdibIN2AjjfW60nfrPuOjepMFG
6BBBbR37pHcyzext9epOAQ. 6BBBbR37pHcyzext9epOAQ.
48V1_ALb6US04U3b. 48V1_ALb6US04U3b.
_e21tGGhac_peEFkLXr2dMPUZiUkrw. _e21tGGhac_peEFkLXr2dMPUZiUkrw.
7V5ZDko0v_mf2PAc4JMiUg 7V5ZDko0v_mf2PAc4JMiUg
A.1.12. Validation A.1.12. Validation
This example illustrates the process of creating a JWE with an AEAD This example illustrates the process of creating a JWE with an
algorithm. These results can be used to validate JWE decryption Authenticated Encryption algorithm. These results can be used to
implementations for these algorithms. Note that since the RSAES OAEP validate JWE decryption implementations for these algorithms. Note
computation includes random values, the encryption results above will that since the RSAES OAEP computation includes random values, the
not be completely reproducible. However, since the AES GCM encryption results above will not be completely reproducible.
computation is deterministic, the JWE Encrypted Ciphertext values However, since the AES GCM computation is deterministic, the JWE
will be the same for all encryptions performed using these inputs. Encrypted Ciphertext values will be the same for all encryptions
performed using these inputs.
A.2. Example JWE using RSAES-PKCS1-V1_5 and AES CBC A.2. Example JWE using RSAES-PKCS1-V1_5 and AES CBC
This example encrypts the plaintext "No matter where you go, there This example encrypts the plaintext "No matter where you go, there
you are." to the recipient using RSAES-PKCS1-V1_5 and AES CBC. AES you are." to the recipient using RSAES-PKCS1-V1_5 and AES CBC. AES
CBC does not have an integrated integrity check, so a separate CBC does not have an integrated integrity check, so a separate
integrity check calculation is performed using HMAC SHA-256, with integrity check calculation is performed using HMAC SHA-256, with
separate encryption and integrity keys being derived from a master separate encryption and integrity keys being derived from a master
key using the Concat KDF with the SHA-256 digest function. The key using the Concat KDF with the SHA-256 digest function. The
representation of this plaintext is: representation of this plaintext is:
skipping to change at page 37, line 19 skipping to change at page 38, line 19
2Wj3mPExxw9vbnsQDU7B4BfmhdyiflLA7Ae5ZGoVRl3A__yLPXxRjHFhpOeDp_ad 2Wj3mPExxw9vbnsQDU7B4BfmhdyiflLA7Ae5ZGoVRl3A__yLPXxRjHFhpOeDp_ad
x8NyejF5cz9yDKULugNsDMdlHeJQOMGVLYaSZt3KP6aWNSqFA1PHDg-10ceuTEtq x8NyejF5cz9yDKULugNsDMdlHeJQOMGVLYaSZt3KP6aWNSqFA1PHDg-10ceuTEtq
_vPE4-Gtev4N4K4Eudlj4Q. _vPE4-Gtev4N4K4Eudlj4Q.
AxY8DCtDaGlsbGljb3RoZQ. AxY8DCtDaGlsbGljb3RoZQ.
Rxsjg6PIExcmGSF7LnSEkDqWIKfAw1wZz2XpabV5PwQsolKwEauWYZNE9Q1hZJEZ. Rxsjg6PIExcmGSF7LnSEkDqWIKfAw1wZz2XpabV5PwQsolKwEauWYZNE9Q1hZJEZ.
8LXqMd0JLGsxMaB5uoNaMpg7uUW_p40RlaZHCwMIyzk 8LXqMd0JLGsxMaB5uoNaMpg7uUW_p40RlaZHCwMIyzk
A.2.14. Validation A.2.14. Validation
This example illustrates the process of creating a JWE with a This example illustrates the process of creating a JWE with a
composite AEAD algorithm created from a non-AEAD algorithm by adding composite Authenticated Encryption algorithm created from a non-
a separate integrity check calculation. These results can be used to Authenticated Encryption algorithm by adding a separate integrity
validate JWE decryption implementations for these algorithms. Note check calculation. These results can be used to validate JWE
that since the RSAES-PKCS1-V1_5 computation includes random values, decryption implementations for these algorithms. Note that since the
the encryption results above will not be completely reproducible. RSAES-PKCS1-V1_5 computation includes random values, the encryption
However, since the AES CBC computation is deterministic, the JWE results above will not be completely reproducible. However, since
Encrypted Ciphertext values will be the same for all encryptions the AES CBC computation is deterministic, the JWE Encrypted
performed using these inputs. Ciphertext values will be the same for all encryptions performed
using these inputs.
A.3. Example JWE using AES Key Wrap and AES GCM A.3. Example JWE using AES Key Wrap and AES GCM
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 AES Key Wrap not knowledge but imagination." to the recipient using AES Key Wrap
and AES GCM. The representation of this plaintext is: and AES GCM. The representation of this plaintext is:
[84, 104, 101, 32, 116, 114, 117, 101, 32, 115, 105, 103, 110, 32, [84, 104, 101, 32, 116, 114, 117, 101, 32, 115, 105, 103, 110, 32,
111, 102, 32, 105, 110, 116, 101, 108, 108, 105, 103, 101, 110, 99, 111, 102, 32, 105, 110, 116, 101, 108, 108, 105, 103, 101, 110, 99,
101, 32, 105, 115, 32, 110, 111, 116, 32, 107, 110, 111, 119, 108, 101, 32, 105, 115, 32, 110, 111, 116, 32, 107, 110, 111, 119, 108,
skipping to change at page 40, line 34 skipping to change at page 41, line 35
eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4R0NNIn0. eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4R0NNIn0.
pP_7AUDIQcgixVGPK9PwJr-htXV3RCxQ. pP_7AUDIQcgixVGPK9PwJr-htXV3RCxQ.
_dxQGaaYsqhhY0NZ. _dxQGaaYsqhhY0NZ.
4wxZhLkQ-F2RVzWCX3M-aIpgbUd806VnymMVwQTiVOX-apDxJ1aUhKBoWOjkbVUH 4wxZhLkQ-F2RVzWCX3M-aIpgbUd806VnymMVwQTiVOX-apDxJ1aUhKBoWOjkbVUH
VlCGaqYYXMfSvJm72kXj. VlCGaqYYXMfSvJm72kXj.
miNQayWUUQZnBDzOq6VxQw miNQayWUUQZnBDzOq6VxQw
A.3.12. Validation A.3.12. Validation
This example illustrates the process of creating a JWE with symmetric This example illustrates the process of creating a JWE with symmetric
key wrap and an AEAD algorithm. These results can be used to key wrap and an Authenticated Encryption algorithm. These results
validate JWE decryption implementations for these algorithms. Also, can be used to validate JWE decryption implementations for these
since both the AES Key Wrap and AES GCM computations are algorithms. Also, since both the AES Key Wrap and AES GCM
deterministic, the resulting JWE value will be the same for all computations are deterministic, the resulting JWE value will be the
encryptions performed using these inputs. Since the computation is same for all encryptions performed using these inputs. Since the
reproducible, these results can also be used to validate JWE computation is reproducible, these results can also be used to
encryption implementations for these algorithms. validate JWE encryption implementations for these algorithms.
A.4. Example Key Derivation for "enc" value "A128CBC+HS256" A.4. Example Key Derivation for "enc" value "A128CBC+HS256"
This example uses the Concat KDF to derive the Content Encryption Key This example uses the Concat KDF to derive the Content Encryption Key
(CEK) and Content Integrity Key (CIK) from the Content Master Key (CEK) and Content Integrity Key (CIK) from the Content Master Key
(CMK) in the manner described in Section 4.8.1 of [JWA]. In this (CMK) in the manner described in Section 4.8.1 of [JWA]. In this
example, a 256 bit CMK is used to derive a 128 bit CEK and a 256 bit example, a 256 bit CMK is used to derive a 128 bit CEK and a 256 bit
CIK. CIK.
The CMK value used is: The CMK value used is:
skipping to change at page 45, line 42 skipping to change at page 46, line 42
while utilizing simple compact JSON-based data structures. while utilizing simple compact JSON-based data structures.
Special thanks are due to John Bradley and Nat Sakimura for the Special thanks are due to John Bradley and Nat Sakimura for the
discussions that helped inform the content of this specification and discussions that helped inform the content of this specification and
to Eric Rescorla and Joe Hildebrand for allowing the reuse of text to Eric Rescorla and Joe Hildebrand for allowing the reuse of text
from [I-D.rescorla-jsms] in this document. from [I-D.rescorla-jsms] in this document.
Thanks to Axel Nennker, Emmanuel Raviart, Brian Campbell, and Edmund Thanks to Axel Nennker, Emmanuel Raviart, Brian Campbell, and Edmund
Jay for validating the examples in this specification. Jay for validating the examples in this specification.
This specification is the work of the JOSE Working Group, which
includes dozens of active and dedicated participants. In particular,
the following individuals contributed ideas, feedback, and wording
that influenced this specification:
Richard Barnes, John Bradley, Brian Campbell, Breno de Medeiros, Dick
Hardt, Jeff Hodges, Edmund Jay, James Manger, Tony Nadalin, Axel
Nennker, Emmanuel Raviart, 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 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 C. Open Issues Appendix C. Open Issues
[[ to be removed by the RFC editor before publication as an RFC ]] [[ to be removed by the RFC editor before publication as an RFC ]]
The following items remain to be considered or done in this draft: The following items remain to be considered or done in this draft:
o Should we define optional nonce, timestamp, and/or uninterpreted o Should all header fields continue to be required to be understood
string header parameter(s)? by implementations using them or should a means of declaring that
specific header fields may be safely ignored if not understood
should be defined?
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 ]]
-08
o Replaced uses of the term "AEAD" with "Authenticated Encryption",
since the term AEAD in the RFC 5116 sense implied the use of a
particular data representation, rather than just referring to the
class of algorithms that perform authenticated encryption with
associated data.
o Applied editorial improvements suggested by Jeff Hodges and Hannes
Tschofenig. Many of these simplified the terminology used.
o Clarified statements of the form "This header parameter is
OPTIONAL" to "Use of this header parameter is OPTIONAL".
o Added a Header Parameter Usage Location(s) field to the IANA JSON
Web Signature and Encryption Header Parameters registry.
o Added seriesInfo information to Internet Draft references.
-07 -07
o Added a data length prefix to PartyUInfo and PartyVInfo values. o Added a data length prefix to PartyUInfo and PartyVInfo values.
o Updated values for example AES CBC calculations. o Updated values for example AES CBC calculations.
o Made several local editorial changes to clean up loose ends left o Made several local editorial changes to clean up loose ends left
over from to the decision to only support block encryption methods over from to the decision to only support block encryption methods
providing integrity. One of these changes was to explicitly state providing integrity. One of these changes was to explicitly state
that the "enc" (encryption method) algorithm must be an AEAD that the "enc" (encryption method) algorithm must be an
algorithm with a specified key length. Authenticated Encryption algorithm with a specified key length.
-06 -06
o Removed the "int" and "kdf" parameters and defined the new o Removed the "int" and "kdf" parameters and defined the new
composite AEAD algorithms "A128CBC+HS256" and "A256CBC+HS512" to composite Authenticated Encryption algorithms "A128CBC+HS256" and
replace the former uses of AES CBC, which required the use of "A256CBC+HS512" to replace the former uses of AES CBC, which
separate integrity and key derivation functions. required the use of separate integrity and key derivation
functions.
o Included additional values in the Concat KDF calculation -- the o Included additional values in the Concat KDF calculation -- the
desired output size and the algorithm value, and optionally desired output size and the algorithm value, and optionally
PartyUInfo and PartyVInfo values. Added the optional header PartyUInfo and PartyVInfo values. Added the optional header
parameters "apu" (agreement PartyUInfo), "apv" (agreement parameters "apu" (agreement PartyUInfo), "apv" (agreement
PartyVInfo), "epu" (encryption PartyUInfo), and "epv" (encryption PartyVInfo), "epu" (encryption PartyUInfo), and "epv" (encryption
PartyVInfo). Updated the KDF examples accordingly. PartyVInfo). Updated the KDF examples accordingly.
o Promoted Initialization Vector from being a header parameter to o Promoted Initialization Vector from being a header parameter to
being a top-level JWE element. This saves approximately 16 bytes being a top-level JWE element. This saves approximately 16 bytes
skipping to change at page 47, line 51 skipping to change at page 49, line 33
o Applied editorial suggestions. o Applied editorial suggestions.
-03 -03
o Added the "kdf" (key derivation function) header parameter to o Added the "kdf" (key derivation function) header parameter to
provide crypto agility for key derivation. The default KDF provide crypto agility for key derivation. The default KDF
remains the Concat KDF with the SHA-256 digest function. remains the Concat KDF with the SHA-256 digest function.
o Reordered encryption steps so that the Encoded JWE Header is o Reordered encryption steps so that the Encoded JWE Header is
always created before it is needed as an input to the AEAD always created before it is needed as an input to the
"additional authenticated data" parameter. Authenticated Encryption "additional authenticated data"
parameter.
o Added the "cty" (content type) header parameter for declaring type o Added the "cty" (content type) header parameter for declaring type
information about the secured content, as opposed to the "typ" information about the secured content, as opposed to the "typ"
(type) header parameter, which declares type information about (type) header parameter, which declares type information about
this object. this object.
o Moved description of how to determine whether a header is for a o Moved description of how to determine whether a header is for a
JWS or a JWE from the JWT spec to the JWE spec. JWS or a JWE from the JWT spec to the JWE spec.
o Added complete encryption examples for both AEAD and non-AEAD o Added complete encryption examples for both Authenticated
algorithms. Encryption and non-Authenticated Encryption algorithms.
o Added complete key derivation examples. o Added complete key derivation examples.
o Added "Collision Resistant Namespace" to the terminology section. o Added "Collision Resistant Namespace" to the terminology section.
o Reference ITU.X690.1994 for DER encoding. o Reference ITU.X690.1994 for DER encoding.
o Added Registry Contents sections to populate registry values. o Added Registry Contents sections to populate registry values.
o Numerous editorial improvements. o Numerous editorial improvements.
-02 -02
o When using AEAD algorithms (such as AES GCM), use the "additional o When using Authenticated Encryption algorithms (such as AES GCM),
authenticated data" parameter to provide integrity for the header, use the "additional authenticated data" parameter to provide
encrypted key, and ciphertext and use the resulting integrity for the header, encrypted key, and ciphertext and use
"authentication tag" value as the JWE Integrity Value. the resulting "authentication tag" value as the JWE Integrity
Value.
o Defined KDF output key sizes. o Defined KDF output key sizes.
o Generalized text to allow key agreement to be employed as an o Generalized text to allow key agreement to be employed as an
alternative to key wrapping or key encryption. alternative to key wrapping or key encryption.
o Changed compression algorithm from gzip to DEFLATE. o Changed compression algorithm from gzip to DEFLATE.
o Clarified that it is an error when a "kid" value is included and o Clarified that it is an error when a "kid" value is included and
no matching key is found. no matching key is found.
skipping to change at page 49, line 9 skipping to change at page 50, line 42
o Clarified the relationship between "typ" header parameter values o Clarified the relationship between "typ" header parameter values
and MIME types. and MIME types.
o Registered application/jwe MIME type and "JWE" typ header o Registered application/jwe MIME type and "JWE" typ header
parameter value. parameter value.
o Simplified JWK terminology to get replace the "JWK Key Object" and o Simplified JWK terminology to get replace the "JWK Key Object" and
"JWK Container Object" terms with simply "JSON Web Key (JWK)" and "JWK Container Object" terms with simply "JSON Web Key (JWK)" and
"JSON Web Key Set (JWK Set)" and to eliminate potential confusion "JSON Web Key Set (JWK Set)" and to eliminate potential confusion
between single keys and sets of keys. As part of this change, the between single keys and sets of keys. As part of this change, the
header parameter name for a public key value was changed from Header Parameter Name for a public key value was changed from
"jpk" (JSON Public Key) to "jwk" (JSON Web Key). "jpk" (JSON Public Key) to "jwk" (JSON Web Key).
o Added suggestion on defining additional header parameters such as o Added suggestion on defining additional header parameters such as
"x5t#S256" in the future for certificate thumbprints using hash "x5t#S256" in the future for certificate thumbprints using hash
algorithms other than SHA-1. algorithms other than SHA-1.
o Specify RFC 2818 server identity validation, rather than RFC 6125 o Specify RFC 2818 server identity validation, rather than RFC 6125
(paralleling the same decision in the OAuth specs). (paralleling the same decision in the OAuth specs).
o Generalized language to refer to Message Authentication Codes o Generalized language to refer to Message Authentication Codes
(MACs) rather than Hash-based Message Authentication Codes (HMACs) (MACs) rather than Hash-based Message Authentication Codes (HMACs)
unless in a context specific to HMAC algorithms. unless in a context specific to HMAC algorithms.
o Reformatted to give each header parameter its own section heading. o Reformatted to give each header parameter its own section heading.
-01 -01
o Added an integrity check for non-AEAD algorithms. o Added an integrity check for non-Authenticated Encryption
algorithms.
o Added "jpk" and "x5c" header parameters for including JWK public o Added "jpk" and "x5c" header parameters for including JWK public
keys and X.509 certificate chains directly in the header. keys and X.509 certificate chains directly in the header.
o Clarified that this specification is defining the JWE Compact o Clarified that this specification is defining the JWE Compact
Serialization. Referenced the new JWE-JS spec, which defines the Serialization. Referenced the new JWE-JS spec, which defines the
JWE JSON Serialization. JWE JSON Serialization.
o Added text "New header parameters should be introduced sparingly o Added text "New header parameters should be introduced sparingly
since an implementation that does not understand a parameter MUST since an implementation that does not understand a parameter MUST
 End of changes. 90 change blocks. 
212 lines changed or deleted 284 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/