< draft-ietf-jose-json-web-encryption-15.txt   draft-ietf-jose-json-web-encryption-16.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: March 7, 2014 RTFM Expires: March 19, 2014 RTFM
J. Hildebrand J. Hildebrand
Cisco Cisco
September 3, 2013 September 15, 2013
JSON Web Encryption (JWE) JSON Web Encryption (JWE)
draft-ietf-jose-json-web-encryption-15 draft-ietf-jose-json-web-encryption-16
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 39 skipping to change at page 1, line 39
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 March 7, 2014. This Internet-Draft will expire on March 19, 2014.
Copyright Notice Copyright Notice
Copyright (c) 2013 IETF Trust and the persons identified as the Copyright (c) 2013 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 15 skipping to change at page 2, line 15
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 5 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 5
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5
3. JSON Web Encryption (JWE) Overview . . . . . . . . . . . . . . 8 3. JSON Web Encryption (JWE) Overview . . . . . . . . . . . . . . 9
3.1. Example JWE . . . . . . . . . . . . . . . . . . . . . . . 9 3.1. Example JWE . . . . . . . . . . . . . . . . . . . . . . . 9
4. JWE Header . . . . . . . . . . . . . . . . . . . . . . . . . . 10 4. JWE Header . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.1. Reserved Header Parameter Names . . . . . . . . . . . . . 11 4.1. Registered Header Parameter Names . . . . . . . . . . . . 11
4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 11 4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 11
4.1.2. "enc" (Encryption Method) Header Parameter . . . . . . 11 4.1.2. "enc" (Encryption Method) Header Parameter . . . . . . 12
4.1.3. "zip" (Compression Algorithm) Header Parameter . . . . 12 4.1.3. "zip" (Compression Algorithm) Header Parameter . . . . 12
4.1.4. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 12 4.1.4. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 12
4.1.5. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 12 4.1.5. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 13
4.1.6. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 12 4.1.6. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 13
4.1.7. "x5t" (X.509 Certificate Thumbprint) Header 4.1.7. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header
Parameter . . . . . . . . . . . . . . . . . . . . . . 13 Parameter . . . . . . . . . . . . . . . . . . . . . . 13
4.1.8. "x5c" (X.509 Certificate Chain) Header Parameter . . . 13 4.1.8. "x5c" (X.509 Certificate Chain) Header Parameter . . . 14
4.1.9. "kid" (Key ID) Header Parameter . . . . . . . . . . . 14 4.1.9. "kid" (Key ID) Header Parameter . . . . . . . . . . . 14
4.1.10. "typ" (Type) Header Parameter . . . . . . . . . . . . 14 4.1.10. "typ" (Type) Header Parameter . . . . . . . . . . . . 14
4.1.11. "cty" (Content Type) Header Parameter . . . . . . . . 14 4.1.11. "cty" (Content Type) Header Parameter . . . . . . . . 15
4.1.12. "crit" (Critical) Header Parameter . . . . . . . . . . 15 4.1.12. "crit" (Critical) Header Parameter . . . . . . . . . . 15
4.2. Public Header Parameter Names . . . . . . . . . . . . . . 15 4.2. Public Header Parameter Names . . . . . . . . . . . . . . 16
4.3. Private Header Parameter Names . . . . . . . . . . . . . . 15 4.3. Private Header Parameter Names . . . . . . . . . . . . . . 16
5. Producing and Consuming JWEs . . . . . . . . . . . . . . . . . 16 5. Producing and Consuming JWEs . . . . . . . . . . . . . . . . . 16
5.1. Message Encryption . . . . . . . . . . . . . . . . . . . . 16 5.1. Message Encryption . . . . . . . . . . . . . . . . . . . . 16
5.2. Message Decryption . . . . . . . . . . . . . . . . . . . . 18 5.2. Message Decryption . . . . . . . . . . . . . . . . . . . . 18
5.3. String Comparison Rules . . . . . . . . . . . . . . . . . 20 5.3. String Comparison Rules . . . . . . . . . . . . . . . . . 21
6. Key Identification . . . . . . . . . . . . . . . . . . . . . . 20 6. Key Identification . . . . . . . . . . . . . . . . . . . . . . 21
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 . . . . . . . . . . . . . . . . . . 22
8. Distinguishing Between JWS and JWE Objects . . . . . . . . . . 24 8. Distinguishing Between JWS and JWE Objects . . . . . . . . . . 25
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25
9.1. Registration of JWE Header Parameter Names . . . . . . . . 25 9.1. JWE Header Parameter Names Registration . . . . . . . . . 25
9.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 25 9.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 26
10. Security Considerations . . . . . . . . . . . . . . . . . . . 26 10. Security Considerations . . . . . . . . . . . . . . . . . . . 27
11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 27 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 27
11.1. Normative References . . . . . . . . . . . . . . . . . . . 27 11.1. Normative References . . . . . . . . . . . . . . . . . . . 27
11.2. Informative References . . . . . . . . . . . . . . . . . . 28 11.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 . . . . . . . . . . . . . . . . . . . . . . 29 A.1.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 30
A.1.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 29 A.1.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 30
A.1.3. Content Encryption Key (CEK) . . . . . . . . . . . . . 30 A.1.3. Content Encryption Key (CEK) . . . . . . . . . . . . . 30
A.1.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 30 A.1.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 31
A.1.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 31 A.1.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 31
A.1.6. Initialization Vector . . . . . . . . . . . . . . . . 31 A.1.6. Initialization Vector . . . . . . . . . . . . . . . . 32
A.1.7. Additional Authenticated Data . . . . . . . . . . . . 31 A.1.7. Additional Authenticated Data . . . . . . . . . . . . 32
A.1.8. Plaintext Encryption . . . . . . . . . . . . . . . . . 31 A.1.8. Content Encryption . . . . . . . . . . . . . . . . . . 32
A.1.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 32 A.1.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 33
A.1.10. Encoded JWE Authentication Tag . . . . . . . . . . . . 32 A.1.10. Encoded JWE Authentication Tag . . . . . . . . . . . . 33
A.1.11. Complete Representation . . . . . . . . . . . . . . . 32 A.1.11. Complete Representation . . . . . . . . . . . . . . . 33
A.1.12. Validation . . . . . . . . . . . . . . . . . . . . . . 33 A.1.12. 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 . . . . . . . . . . . . . . . . . 34
A.2.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 33 A.2.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 34
A.2.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 33 A.2.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 34
A.2.3. Content Encryption Key (CEK) . . . . . . . . . . . . . 33 A.2.3. Content Encryption Key (CEK) . . . . . . . . . . . . . 34
A.2.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 34 A.2.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 34
A.2.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 35 A.2.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 35
A.2.6. Initialization Vector . . . . . . . . . . . . . . . . 35 A.2.6. Initialization Vector . . . . . . . . . . . . . . . . 36
A.2.7. Additional Authenticated Data . . . . . . . . . . . . 35 A.2.7. Additional Authenticated Data . . . . . . . . . . . . 36
A.2.8. Plaintext Encryption . . . . . . . . . . . . . . . . . 35 A.2.8. Content Encryption . . . . . . . . . . . . . . . . . . 36
A.2.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 36 A.2.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 36
A.2.10. Encoded JWE Authentication Tag . . . . . . . . . . . . 36 A.2.10. Encoded JWE Authentication Tag . . . . . . . . . . . . 37
A.2.11. Complete Representation . . . . . . . . . . . . . . . 36 A.2.11. Complete Representation . . . . . . . . . . . . . . . 37
A.2.12. Validation . . . . . . . . . . . . . . . . . . . . . . 36 A.2.12. Validation . . . . . . . . . . . . . . . . . . . . . . 37
A.3. Example JWE using AES Key Wrap and A.3. Example JWE using AES Key Wrap and
AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 37 AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 37
A.3.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 37 A.3.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 38
A.3.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 37 A.3.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 38
A.3.3. Content Encryption Key (CEK) . . . . . . . . . . . . . 37 A.3.3. Content Encryption Key (CEK) . . . . . . . . . . . . . 38
A.3.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 37 A.3.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 38
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 . . . . . . . . . . . . 38 A.3.7. Additional Authenticated Data . . . . . . . . . . . . 39
A.3.8. Plaintext Encryption . . . . . . . . . . . . . . . . . 38 A.3.8. Content Encryption . . . . . . . . . . . . . . . . . . 39
A.3.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 39 A.3.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 40
A.3.10. Encoded JWE Authentication Tag . . . . . . . . . . . . 39 A.3.10. Encoded JWE Authentication Tag . . . . . . . . . . . . 40
A.3.11. Complete Representation . . . . . . . . . . . . . . . 39 A.3.11. Complete Representation . . . . . . . . . . . . . . . 40
A.3.12. Validation . . . . . . . . . . . . . . . . . . . . . . 40 A.3.12. Validation . . . . . . . . . . . . . . . . . . . . . . 40
A.4. Example JWE Using JWE JSON Serialization . . . . . . . . . 40 A.4. Example JWE Using JWE JSON Serialization . . . . . . . . . 40
A.4.1. JWE Per-Recipient Unprotected Headers . . . . . . . . 40 A.4.1. JWE Per-Recipient Unprotected Headers . . . . . . . . 41
A.4.2. JWE Protected Header . . . . . . . . . . . . . . . . . 40 A.4.2. JWE Protected Header . . . . . . . . . . . . . . . . . 41
A.4.3. JWE Unprotected Header . . . . . . . . . . . . . . . . 41 A.4.3. JWE Unprotected Header . . . . . . . . . . . . . . . . 41
A.4.4. Complete JWE Header Values . . . . . . . . . . . . . . 41 A.4.4. Complete JWE Header Values . . . . . . . . . . . . . . 42
A.4.5. Additional Authenticated Data . . . . . . . . . . . . 41 A.4.5. Additional Authenticated Data . . . . . . . . . . . . 42
A.4.6. Plaintext Encryption . . . . . . . . . . . . . . . . . 41 A.4.6. Content Encryption . . . . . . . . . . . . . . . . . . 42
A.4.7. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 42 A.4.7. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 42
A.4.8. Encoded JWE Authentication Tag . . . . . . . . . . . . 42 A.4.8. Encoded JWE Authentication Tag . . . . . . . . . . . . 43
A.4.9. Complete JWE JSON Serialization Representation . . . . 42 A.4.9. Complete JWE JSON Serialization Representation . . . . 43
Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation . . . . 43 Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation . . . . 43
B.1. Extract MAC_KEY and ENC_KEY from Key . . . . . . . . . . . 43 B.1. Extract MAC_KEY and ENC_KEY from Key . . . . . . . . . . . 44
B.2. Encrypt Plaintext to Create Ciphertext . . . . . . . . . . 44 B.2. Encrypt Plaintext to Create Ciphertext . . . . . . . . . . 44
B.3. 64 Bit Big Endian Representation of AAD Length . . . . . . 44 B.3. 64 Bit Big Endian Representation of AAD Length . . . . . . 44
B.4. Initialization Vector Value . . . . . . . . . . . . . . . 44 B.4. Initialization Vector Value . . . . . . . . . . . . . . . 45
B.5. Create Input to HMAC Computation . . . . . . . . . . . . . 45 B.5. Create Input to HMAC Computation . . . . . . . . . . . . . 45
B.6. Compute HMAC Value . . . . . . . . . . . . . . . . . . . . 45 B.6. Compute HMAC Value . . . . . . . . . . . . . . . . . . . . 45
B.7. Truncate HMAC Value to Create Authentication Tag . . . . . 45 B.7. Truncate HMAC Value to Create Authentication Tag . . . . . 45
Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 45 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 46
Appendix D. Document History . . . . . . . . . . . . . . . . . . 46 Appendix D. Document History . . . . . . . . . . . . . . . . . . 46
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 53 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 54
1. Introduction 1. Introduction
JSON Web Encryption (JWE) represents encrypted content using JSON Web Encryption (JWE) represents encrypted content using
JavaScript Object Notation (JSON) [RFC4627] based data structures. JavaScript Object Notation (JSON) [RFC4627] based data structures.
The JWE cryptographic mechanisms encrypt and provide integrity The JWE cryptographic mechanisms encrypt and provide integrity
protection for an arbitrary sequence of octets. protection for an arbitrary sequence of octets.
Two closely related serializations for JWE objects are defined. The Two closely related serializations for JWE objects are defined. The
JWE Compact Serialization is a compact, URL-safe representation JWE Compact Serialization is a compact, URL-safe representation
skipping to change at page 5, line 35 skipping to change at page 5, line 35
specification. specification.
Names defined by this specification are short because a core goal is Names defined by this specification are short because a core goal is
for the resulting representations to be compact. for the resulting representations to be compact.
1.1. Notational Conventions 1.1. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in Key words for use in document are to be interpreted as described in Key words for use in
RFCs to Indicate Requirement Levels [RFC2119]. RFCs to Indicate Requirement Levels [RFC2119]. If these words are
used without being spelled in uppercase then they are to be
interpreted with their normal natural language meanings.
2. Terminology 2. Terminology
JSON Web Encryption (JWE) A data structure representing an encrypted JSON Web Encryption (JWE) A data structure representing an encrypted
message. The structure represents five values: the JWE Header, message. The structure represents five values: the JWE Header,
the JWE Encrypted Key, the JWE Initialization Vector, the JWE the JWE Encrypted Key, the JWE Initialization Vector, the JWE
Ciphertext, and the JWE Authentication Tag. Ciphertext, and the JWE Authentication Tag.
Authenticated Encryption with Associated Data (AEAD) An AEAD Authenticated Encryption with Associated Data (AEAD) An AEAD
algorithm is one that encrypts the Plaintext, allows Additional algorithm is one that encrypts the Plaintext, allows Additional
skipping to change at page 7, line 45 skipping to change at page 8, line 5
characters. This representation is compact and URL-safe. characters. This representation is compact and URL-safe.
JWE JSON Serialization A representation of the JWE as a JSON JWE JSON Serialization A representation of the JWE as a JSON
structure containing JWE Header, Encoded JWE Encrypted Key, structure containing JWE Header, Encoded JWE Encrypted Key,
Encoded JWE Initialization Vector, Encoded JWE Ciphertext, and Encoded JWE Initialization Vector, Encoded JWE Ciphertext, and
Encoded JWE Authentication Tag values. Unlike the JWE Compact Encoded JWE Authentication Tag values. Unlike the JWE Compact
Serialization, the JWE JSON Serialization enables the same content Serialization, the JWE JSON Serialization enables the same content
to be encrypted to multiple parties. This representation is to be encrypted to multiple parties. This representation is
neither compact nor URL-safe. neither compact nor URL-safe.
Collision Resistant Namespace A namespace that allows names to be Collision Resistant Name A name in a namespace that enables names to
allocated in a manner such that they are highly unlikely to be allocated in a manner such that they are highly unlikely to
collide with other names. Examples of Collision Resistant collide with other names. Examples of collision resistant
Namespaces include: Domain Names, Object Identifiers (OIDs) as namespaces include: Domain Names, Object Identifiers (OIDs) as
defined in the ITU-T X.660 and X.670 Recommendation series, and defined in the ITU-T X.660 and X.670 Recommendation series, and
Universally Unique IDentifiers (UUIDs) [RFC4122]. When using an Universally Unique IDentifiers (UUIDs) [RFC4122]. When using an
administratively delegated namespace, the definer of a name needs administratively delegated namespace, the definer of a name needs
to take reasonable precautions to ensure they are in control of to take reasonable precautions to ensure they are in control of
the portion of the namespace they use to define the name. the portion of the namespace they use to define the name.
StringOrURI A JSON string value, with the additional requirement StringOrURI A JSON string value, with the additional requirement
that while arbitrary string values MAY be used, any value that while arbitrary string values MAY be used, any value
containing a ":" character MUST be a URI [RFC3986]. StringOrURI containing a ":" character MUST be a URI [RFC3986]. StringOrURI
values are compared as case-sensitive strings with no values are compared as case-sensitive strings with no
skipping to change at page 11, line 9 skipping to change at page 11, line 24
Implementations are required to understand the specific header Implementations are required to understand the specific header
parameters defined by this specification that are designated as "MUST parameters defined by this specification that are designated as "MUST
be understood" and process them in the manner defined in this be understood" and process them in the manner defined in this
specification. All other header parameters defined by this specification. All other header parameters defined by this
specification that are not so designated MUST be ignored when not specification that are not so designated MUST be ignored when not
understood. Unless listed as a critical header parameter, per understood. Unless listed as a critical header parameter, per
Section 4.1.12, all header parameters not defined by this Section 4.1.12, all header parameters not defined by this
specification MUST be ignored when not understood. specification MUST be ignored when not understood.
There are three classes of Header Parameter Names: Reserved Header There are three classes of Header Parameter Names: Registered 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. Registered Header Parameter Names
The following Header Parameter Names are reserved with meanings as The following Header Parameter Names are registered in the IANA JSON
defined below. Web Signature and Encryption Header Parameters registry defined in
[JWS], with meanings as defined below.
Additional reserved Header Parameter Names can be defined via the As indicated by the common registry, JWSs and JWEs share a common
IANA JSON Web Signature and Encryption Header Parameters registry header parameter space; when a parameter is used by both
[JWS]. As indicated by the common registry, JWSs and JWEs share a
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
Encryption Key (CEK). The encrypted content is not usable if the Encryption Key (CEK). The encrypted content is not usable if the
"alg" value does not represent a supported algorithm, or if the "alg" value does not represent a supported algorithm, or if the
recipient does not have a key that can be used with that algorithm. recipient does not have a key that can be used with that algorithm.
"alg" values SHOULD either be registered in the IANA JSON Web "alg" values SHOULD either be registered in the IANA JSON Web
Signature and Encryption Algorithms registry [JWA] or be a value that Signature and Encryption Algorithms registry defined in [JWA] or be a
contains a Collision Resistant Namespace. The "alg" value is a case value that contains a Collision Resistant Name. The "alg" value is a
sensitive string containing a StringOrURI value. Use of this header case sensitive string containing a StringOrURI value. Use of this
parameter is REQUIRED. This header parameter MUST be understood by header parameter is REQUIRED. This header parameter MUST be
implementations. understood and processed by implementations.
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 defined in [JWA]; the
contents of this registry are the values defined in Section 4.1 of initial contents of this registry are the values defined in Section
the JSON Web Algorithms (JWA) [JWA] specification. 4.1 of 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 content The "enc" (encryption method) header parameter identifies the content
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 AEAD algorithm with a
specified key length. The recipient MUST reject the JWE if the "enc" specified key length. The recipient MUST reject the JWE if the "enc"
value does not represent a supported algorithm. "enc" values SHOULD value does not represent a supported algorithm. "enc" values SHOULD
either be registered in the IANA JSON Web Signature and Encryption either be registered in the IANA JSON Web Signature and Encryption
Algorithms registry [JWA] or be a value that contains a Collision Algorithms registry defined in [JWA] or be a value that contains a
Resistant Namespace. The "enc" value is a case sensitive string Collision Resistant Name. The "enc" value is a case sensitive string
containing a StringOrURI value. Use of this header parameter is containing a StringOrURI value. Use of this header parameter is
REQUIRED. This header parameter MUST be understood by REQUIRED. This header parameter MUST be understood and processed by
implementations. implementations.
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 defined in [JWA]; the
contents of this registry are the values defined in Section 4.2 of initial contents of this registry are the values defined in Section
the JSON Web Algorithms (JWA) [JWA] specification. 4.2 of the JSON Web Algorithms (JWA) [JWA] specification.
4.1.3. "zip" (Compression Algorithm) Header Parameter 4.1.3. "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. The "zip" value defined by this specification
parameter MUST be the case sensitive string "DEF". Compression is is:
performed with the DEFLATE [RFC1951] algorithm. If no "zip"
parameter is present, no compression is applied to the Plaintext o "DEF" - Compression with the DEFLATE [RFC1951] algorithm
before encryption. This header parameter MUST be integrity
protected, and therefore MUST occur only with the JWE Protected Other values MAY be used. Compression algorithm values can be
Header, when used. Use of this header parameter is OPTIONAL. This registered in the IANA JSON Web Encryption Compression Algorithm
header parameter MUST be understood by implementations. registry defined in [JWA]. The "zip" value is a case sensitive
string. If no "zip" parameter is present, no compression is applied
to the Plaintext before encryption. This header parameter MUST be
integrity protected, and therefore MUST occur only within the JWE
Protected Header, when used. Use of this header parameter is
OPTIONAL. This header parameter MUST be understood and processed by
implementations.
4.1.4. "jku" (JWK Set URL) Header Parameter 4.1.4. "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 is the key to which the JWE was encrypted; this can be used to which is the key to which the JWE was encrypted; this can be used to
determine the private key needed to decrypt the JWE. The keys MUST determine the private key needed to decrypt the JWE. The keys MUST
be encoded as a JSON Web Key Set (JWK Set) [JWK]. The protocol used be encoded as a JSON Web Key Set (JWK Set) [JWK]. The protocol used
to acquire the resource MUST provide integrity protection; an HTTP to acquire the resource MUST provide integrity protection; an HTTP
GET request to retrieve the JWK Set MUST use TLS [RFC2818] [RFC5246]; GET request to retrieve the JWK Set MUST use TLS [RFC2818] [RFC5246];
skipping to change at page 13, line 16 skipping to change at page 13, line 35
in PEM encoded form [RFC1421]. The certificate containing the public in PEM encoded form [RFC1421]. The certificate containing the public
key to which the JWE was encrypted MUST be the first certificate. key to which the JWE was encrypted MUST be the first certificate.
This MAY be followed by additional certificates, with each subsequent This MAY be followed by additional certificates, with each subsequent
certificate being the one used to certify the previous one. The certificate being the one used to certify the previous one. 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]. Use of validated, as per Section 3.1 of HTTP Over TLS [RFC2818]. Use of
this header parameter is OPTIONAL. this header parameter is OPTIONAL.
4.1.7. "x5t" (X.509 Certificate Thumbprint) Header Parameter 4.1.7. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter
The "x5t" (X.509 Certificate Thumbprint) header parameter is a The "x5t" (X.509 Certificate SHA-1 Thumbprint) header parameter is 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] containing the key to encoding of the X.509 certificate [RFC5280] containing the key to
which the JWE was encrypted; this can be used to determine the which the JWE was encrypted; this can be used to determine the
private key needed to decrypt the JWE. Use of this header parameter private key needed to decrypt the JWE. Use of this header parameter
is OPTIONAL. 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]. defined in [JWS].
4.1.8. "x5c" (X.509 Certificate Chain) Header Parameter 4.1.8. "x5c" (X.509 Certificate Chain) Header Parameter
The "x5c" (X.509 Certificate Chain) header parameter contains the The "x5c" (X.509 Certificate Chain) header parameter contains the
X.509 public key certificate or certificate chain [RFC5280] X.509 public key certificate or certificate chain [RFC5280]
containing the key to which the JWE was encrypted; this can be used containing the key to which the JWE was encrypted; this can be used
to determine the private key needed to decrypt the JWE. The to determine the private key needed to decrypt the JWE. The
certificate or certificate chain is represented as a JSON array of certificate or certificate chain is represented as a JSON array of
certificate value strings. Each string in the array is a base64 certificate value strings. Each string in the array is a base64
encoded ([RFC4648] Section 4 -- not base64url encoded) DER encoded ([RFC4648] Section 4 -- not base64url encoded) DER
skipping to change at page 14, line 21 skipping to change at page 14, line 38
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. Use of this header parameter is OPTIONAL. a string. Use of this header parameter is OPTIONAL.
When used with a JWK, the "kid" value can be used to match a JWK When used with a JWK, the "kid" value can be used to match a JWK
"kid" parameter value. "kid" parameter value.
4.1.10. "typ" (Type) Header Parameter 4.1.10. "typ" (Type) Header Parameter
The "typ" (type) header parameter MAY be used to declare the type of The "typ" (type) header parameter is used to declare the type of this
this complete JWE object in an application-specific manner in complete JWE object in an application-specific manner in contexts
contexts where this is useful to the application. This parameter has where this is useful to the application. This parameter has no
no effect upon the JWE processing. The type value "JOSE" MAY be used effect upon the JWE processing. The type value "JOSE" can be used by
by applications to indicate that this object is a JWS or JWE using applications to indicate that this object is a JWS or JWE using the
the JWS Compact Serialization or the JWE Compact Serialization. The JWS Compact Serialization or the JWE Compact Serialization. The type
type value "JOSE+JSON" MAY be used by applications to indicate that value "JOSE+JSON" can be used by applications to indicate that this
this object is a JWS or JWE using the JWS JSON Serialization or the object is a JWS or JWE using the JWS JSON Serialization or the JWE
JWE JSON Serialization. Other type values MAY be used, and if not JSON Serialization. Other type values can also be used by
understood, SHOULD be ignored. The "typ" value is a case sensitive applications. The "typ" value is a case sensitive string. Use of
string. Use of this 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. When
MIME Media Type values are used, it is RECOMMENDED that they be
spelled using the exact character case used in the MIME Media Types
registry [IANA.MediaTypes], since this field is case sensitive,
whereas MIME Media Type values are case insensitive.
"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 value Signature and Encryption Type Values registry defined in [JWS] or be
that contains a Collision Resistant Namespace. a value that contains a Collision Resistant Name.
4.1.11. "cty" (Content Type) Header Parameter 4.1.11. "cty" (Content Type) Header Parameter
The "cty" (content type) header parameter MAY be used to declare the The "cty" (content type) header parameter is used to declare the type
type of the encrypted content (the Plaintext) in an application- of the encrypted content (the Plaintext) in an application-specific
specific manner in contexts where this is useful to the application. manner in contexts where this is useful to the application. This
This parameter has no effect upon the JWE processing. Content type parameter has no effect upon the JWE processing. The "cty" value is
values that are not understood SHOULD be ignored. The "cty" value is
a case sensitive string. Use of this header parameter is OPTIONAL. a case 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.12. "crit" (Critical) Header Parameter 4.1.12. "crit" (Critical) Header Parameter
The "crit" (critical) header parameter indicates that extensions to The "crit" (critical) header parameter indicates that extensions to
[[ this specification ]] are being used that MUST be understood and [[ this specification ]] are being used that MUST be understood and
skipping to change at page 15, line 23 skipping to change at page 15, line 41
include header parameter names defined by [[ this specification ]] or include header parameter names defined by [[ this specification ]] or
by [JWA] for use with JWE, duplicate names, or names that do not by [JWA] for use with JWE, duplicate names, or names that do not
occur as header parameter names within the JWE Header in the "crit" occur as header parameter names within the JWE Header in the "crit"
list. Senders MUST not use the empty list "[]" as the "crit" value. list. Senders MUST not use the empty list "[]" as the "crit" value.
Recipients MAY reject the JWE if the critical list contains any Recipients MAY reject the JWE if the critical list contains any
header parameter names defined by [[ this specification ]] or by header parameter names defined by [[ this specification ]] or by
[JWA] for use with JWE, or any other constraints on its use are [JWA] for use with JWE, or any other constraints on its use are
violated. This header parameter MUST be integrity protected, and violated. This header parameter MUST be integrity protected, and
therefore MUST occur only with the JWE Protected Header, when used. therefore MUST occur only with the JWE Protected Header, when used.
Use of this header parameter is OPTIONAL. This header parameter MUST Use of this header parameter is OPTIONAL. This header parameter MUST
be understood by implementations. be understood and processed by implementations.
An example use, along with a hypothetical "exp" (expiration-time) An example use, along with a hypothetical "exp" (expiration-time)
field is: field is:
{"alg":"RSA-OAEP", {"alg":"RSA-OAEP",
"enc":"A256GCM", "enc":"A256GCM",
"crit":["exp"], "crit":["exp"],
"exp":1363284000 "exp":1363284000
} }
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 Public Name: a Encryption Header Parameters registry defined in [JWS] or be a Public
value that contains a Collision Resistant Namespace. In each case, Name: a value that contains a Collision Resistant Name. In each
the definer of the name or value needs to take reasonable precautions case, the definer of the name or value needs to take reasonable
to make sure they are in control of the part of the namespace they precautions to make sure they are in control of the part of the
use to define the Header Parameter Name. namespace they 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 use Header Parameter A producer and consumer of a JWE may agree to use Header Parameter
Names that are Private Names: names that are not Reserved Names Names that are Private Names: names that are not Registered Header
Section 4.1 or Public Names Section 4.2. Unlike Public Names, Parameter Names Section 4.1 or Public Header Parameter Names
Private Names are subject to collision and should be used with Section 4.2. Unlike Public Header Parameter Names, Private Header
Parameter Names are subject to collision and should be used with
caution. caution.
5. Producing and Consuming JWEs 5. Producing and Consuming JWEs
5.1. Message Encryption 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.
skipping to change at page 17, line 27 skipping to change at page 17, line 47
encoding. encoding.
14. Base64url encode the octets of the UTF-8 representation of the 14. Base64url encode the octets of the UTF-8 representation of the
JWE Protected Header to create the Encoded JWE Header. If the JWE Protected Header to create the Encoded JWE Header. If the
JWE Protected Header is not present (which can only happen when JWE Protected Header is not present (which can only happen when
using the JWE JSON Serialization and no "protected" member is using the JWE JSON Serialization and no "protected" member is
present), let the Encoded JWE Header be the empty string. present), let the Encoded JWE Header be the empty string.
15. Let the Additional Authenticated Data encryption parameter be 15. Let the Additional Authenticated Data encryption parameter be
the octets of the ASCII representation of the Encoded JWE Header the octets of the ASCII representation of the Encoded JWE Header
value. However if a top-level "aad" member is present when
using the JWE JSON Serialization, instead let the Additional
Authenticated Data encryption parameter be the octets of the
ASCII representation of the concatenation of the Encoded JWE
Header value, a period ('.') character, and the "aad" field
value. value.
16. Encrypt M using the CEK, the JWE Initialization Vector, and the 16. Encrypt M using the CEK, the JWE Initialization Vector, and the
Additional Authenticated Data value using the specified content Additional Authenticated Data value using the specified content
encryption algorithm to create the JWE Ciphertext value and the encryption algorithm to create the JWE Ciphertext value and the
JWE Authentication Tag (which is the Authentication Tag output JWE Authentication Tag (which is the Authentication Tag output
from the encryption operation). from the encryption operation).
17. Base64url encode the JWE Ciphertext to create the Encoded JWE 17. Base64url encode the JWE Ciphertext to create the Encoded JWE
Ciphertext. Ciphertext.
skipping to change at page 20, line 44 skipping to change at page 21, line 26
6. Key Identification 6. Key Identification
It is necessary for the recipient of a JWE to be able to determine It is necessary for the recipient of a JWE to be able to determine
the key that was employed for the encryption operation. The key the key that was employed for the encryption operation. The key
employed can be identified using the Header Parameter methods employed can be identified using the Header Parameter methods
described in Section 4.1 or can be identified using methods that are described in Section 4.1 or can be identified using methods that are
outside the scope of this specification. Specifically, the Header outside the scope of this specification. Specifically, the Header
Parameters "jku", "jwk", "x5u", "x5t", "x5c", and "kid" can be used Parameters "jku", "jwk", "x5u", "x5t", "x5c", and "kid" can be used
to identify the key used. These header parameters MUST be integrity to identify the key used. These header parameters MUST be integrity
protected if the information about the key that they convey is to be protected if the information that they convey is to be utilized in a
considered trusted. trust decision.
The sender SHOULD include sufficient information in the Header The sender SHOULD include sufficient information in the Header
Parameters to identify the key used, unless the application uses Parameters to identify the key used, unless the application uses
another means or convention to determine the key used. Validation of another means or convention to determine the key used. Validation of
the encrypted content fails when the key used cannot be determined. the encrypted content fails when the key used cannot be determined.
The means of exchanging any shared symmetric keys used is outside the The means of exchanging any shared symmetric keys used is outside the
scope of this specification. scope of this specification.
7. Serializations 7. Serializations
skipping to change at page 25, line 7 skipping to change at page 25, line 45
"none", it is for a JWS; if it represents a Key Encryption, Key "none", it is for a JWS; if it represents a Key Encryption, Key
Wrapping, Direct Key Agreement, Key Agreement with Key Wrapping, Wrapping, Direct Key Agreement, Key Agreement with Key Wrapping,
or Direct Encryption algorithm, it is for a JWE. or Direct Encryption algorithm, it is for a JWE.
o A JWS Header can also be distinguished from a JWE header by o A JWS Header can also be distinguished from a JWE header by
determining whether an "enc" (encryption method) member exists. determining whether an "enc" (encryption method) member exists.
If the "enc" member exists, it is a JWE; otherwise, it is a JWS. If the "enc" member exists, it is a JWE; otherwise, it is a JWS.
9. IANA Considerations 9. IANA Considerations
9.1. Registration of JWE Header Parameter Names 9.1. JWE Header Parameter Names Registration
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 defined in [JWS].
9.1.1. Registry Contents 9.1.1. Registry Contents
o Header Parameter Name: "alg" o Header Parameter Name: "alg"
o Header Parameter Usage Location(s): JWE o Header Parameter Usage Location(s): JWE
o Change Controller: IETF o Change Controller: IESG
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 Header Parameter Usage Location(s): JWE
o Change Controller: IETF o Change Controller: IESG
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: "zip" o Header Parameter Name: "zip"
o Header Parameter Usage Location(s): JWE o Header Parameter Usage Location(s): JWE
o Change Controller: IETF o Change Controller: IESG
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: "jku" o Header Parameter Name: "jku"
o Header Parameter Usage Location(s): JWE o Header Parameter Usage Location(s): JWE
o Change Controller: IETF o Change Controller: IESG
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: "jwk" o Header Parameter Name: "jwk"
o Header Parameter Usage Location(s): JWE o Header Parameter Usage Location(s): JWE
o Change Controller: IETF o Change Controller: IESG
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: "x5u" o Header Parameter Name: "x5u"
o Header Parameter Usage Location(s): JWE o Header Parameter Usage Location(s): JWE
o Change Controller: IETF o Change Controller: IESG
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: "x5t" o Header Parameter Name: "x5t"
o Header Parameter Usage Location(s): JWE o Header Parameter Usage Location(s): JWE
o Change Controller: IETF o Change Controller: IESG
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: "x5c" o Header Parameter Name: "x5c"
o Header Parameter Usage Location(s): JWE o Header Parameter Usage Location(s): JWE
o Change Controller: IETF o Change Controller: IESG
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: "kid" o Header Parameter Name: "kid"
o Header Parameter Usage Location(s): JWE o Header Parameter Usage Location(s): JWE
o Change Controller: IETF o Change Controller: IESG
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: "typ" o Header Parameter Name: "typ"
o Header Parameter Usage Location(s): JWE o Header Parameter Usage Location(s): JWE
o Change Controller: IETF o Change Controller: IESG
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: "cty" o Header Parameter Name: "cty"
o Header Parameter Usage Location(s): JWE o Header Parameter Usage Location(s): JWE
o Change Controller: IETF o Change Controller: IESG
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: "crit" o Header Parameter Name: "crit"
o Header Parameter Usage Location(s): JWE o Header Parameter Usage Location(s): JWE
o Change Controller: IETF o Change Controller: IESG
o Specification Document(s): Section 4.1.12 of [[ this document ]] o Specification Document(s): Section 4.1.12 of [[ this document ]]
10. Security Considerations 10. 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 private and symmetric keys, preventing various
attacks, and helping the user avoid mistakes such as inadvertently attacks, and helping the user avoid mistakes such as inadvertently
encrypting a message for the wrong recipient. The entire list of encrypting a message for the wrong recipient. The entire list of
security considerations is beyond the scope of this document. security considerations is beyond the scope of this document.
skipping to change at page 27, line 14 skipping to change at page 28, line 6
the encrypted content is rejected. the encrypted content is rejected.
11. References 11. References
11.1. Normative References 11.1. Normative References
[ECMAScript] [ECMAScript]
Ecma International, "ECMAScript Language Specification, Ecma International, "ECMAScript Language Specification,
5.1 Edition", ECMA 262, June 2011. 5.1 Edition", ECMA 262, June 2011.
[IANA.MediaTypes]
Internet Assigned Numbers Authority (IANA), "MIME Media
Types", 2005.
[ITU.X690.1994] [ITU.X690.1994]
International Telecommunications Union, "Information International Telecommunications Union, "Information
Technology - ASN.1 encoding rules: Specification of Basic Technology - ASN.1 encoding rules: Specification of Basic
Encoding Rules (BER), Canonical Encoding Rules (CER) and Encoding Rules (BER), Canonical Encoding Rules (CER) and
Distinguished Encoding Rules (DER)", ITU-T Recommendation Distinguished Encoding Rules (DER)", ITU-T Recommendation
X.690, 1994. X.690, 1994.
[JWA] Jones, M., "JSON Web Algorithms (JWA)", [JWA] Jones, M., "JSON Web Algorithms (JWA)",
draft-ietf-jose-json-web-algorithms (work in progress), draft-ietf-jose-json-web-algorithms (work in progress),
September 2013. September 2013.
skipping to change at page 31, line 44 skipping to change at page 32, line 35
A.1.7. Additional Authenticated Data A.1.7. Additional Authenticated Data
Let the Additional Authenticated Data encryption parameter be the Let the Additional Authenticated Data encryption parameter be the
octets of the ASCII representation of the Encoded JWE Header value. octets of the ASCII representation of the Encoded JWE Header value.
This AAD value is: This AAD value is:
[101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69,
116, 84, 48, 70, 70, 85, 67, 73, 115, 73, 109, 86, 117, 89, 121, 73, 116, 84, 48, 70, 70, 85, 67, 73, 115, 73, 109, 86, 117, 89, 121, 73,
54, 73, 107, 69, 121, 78, 84, 90, 72, 81, 48, 48, 105, 102, 81] 54, 73, 107, 69, 121, 78, 84, 90, 72, 81, 48, 48, 105, 102, 81]
A.1.8. Plaintext Encryption A.1.8. Content Encryption
Encrypt the Plaintext with AES GCM using the CEK as the encryption Encrypt the Plaintext with AES GCM using the CEK as the encryption
key, the JWE Initialization Vector, and the Additional Authenticated key, the JWE Initialization Vector, and the Additional Authenticated
Data value above, requesting a 128 bit Authentication Tag output. Data value above, requesting a 128 bit Authentication Tag output.
The resulting Ciphertext is: The resulting Ciphertext is:
[229, 236, 166, 241, 53, 191, 115, 196, 174, 43, 73, 109, 39, 122, [229, 236, 166, 241, 53, 191, 115, 196, 174, 43, 73, 109, 39, 122,
233, 96, 140, 206, 120, 52, 51, 237, 48, 11, 190, 219, 186, 80, 111, 233, 96, 140, 206, 120, 52, 51, 237, 48, 11, 190, 219, 186, 80, 111,
104, 50, 142, 47, 167, 59, 61, 181, 127, 196, 21, 40, 82, 242, 32, 104, 50, 142, 47, 167, 59, 61, 181, 127, 196, 21, 40, 82, 242, 32,
123, 143, 168, 226, 73, 216, 176, 144, 138, 247, 106, 60, 16, 205, 123, 143, 168, 226, 73, 216, 176, 144, 138, 247, 106, 60, 16, 205,
skipping to change at page 35, line 42 skipping to change at page 36, line 30
Let the Additional Authenticated Data encryption parameter be the Let the Additional Authenticated Data encryption parameter be the
octets of the ASCII representation of the Encoded JWE Header value. octets of the ASCII representation of the Encoded JWE Header value.
This AAD value is: This AAD value is:
[101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69,
120, 88, 122, 85, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 120, 88, 122, 85, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105,
74, 66, 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 74, 66, 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85,
50, 73, 110, 48] 50, 73, 110, 48]
A.2.8. Plaintext Encryption A.2.8. Content Encryption
Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as
the encryption key, the JWE Initialization Vector, and the Additional the encryption key, the JWE Initialization Vector, and the Additional
Authenticated Data value above. The steps for doing this using the Authenticated Data value above. The steps for doing this using the
values from Appendix A.3 are detailed in Appendix B. The resulting values from Appendix A.3 are detailed in Appendix B. The resulting
Ciphertext is: Ciphertext is:
[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 38, line 47 skipping to change at page 39, line 36
Let the Additional Authenticated Data encryption parameter be the Let the Additional Authenticated Data encryption parameter be the
octets of the ASCII representation of the Encoded JWE Header value. octets of the ASCII representation of the Encoded JWE Header value.
This AAD value is: This AAD value is:
[101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52,
83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66,
77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73,
110, 48] 110, 48]
A.3.8. Plaintext Encryption A.3.8. Content Encryption
Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as
the encryption key, the JWE Initialization Vector, and the Additional the encryption key, the JWE Initialization Vector, and the Additional
Authenticated Data value above. The steps for doing this using the Authenticated Data value above. The steps for doing this using the
values from this example are detailed in Appendix B. The resulting values from this example are detailed in Appendix B. The resulting
Ciphertext is: Ciphertext is:
[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 40, line 44 skipping to change at page 41, line 27
A.4.1. JWE Per-Recipient Unprotected Headers A.4.1. JWE Per-Recipient Unprotected Headers
The first recipient uses the RSAES-PKCS1-V1_5 algorithm to encrypt The first recipient uses the RSAES-PKCS1-V1_5 algorithm to encrypt
the Content Encryption Key (CEK). The second uses AES Key Wrap to the Content Encryption Key (CEK). The second uses AES Key Wrap to
encrypt the CEK. Key ID values are supplied for both keys. The two encrypt the CEK. Key ID values are supplied for both keys. The two
per-recipient header values used to represent these algorithms and per-recipient header values used to represent these algorithms and
Key IDs are: Key IDs are:
{"alg":"RSA1_5","kid":"2011-04-29"} {"alg":"RSA1_5","kid":"2011-04-29"}
and: and
{"alg":"A128KW","kid":"7"} {"alg":"A128KW","kid":"7"}
A.4.2. JWE Protected Header A.4.2. JWE Protected Header
The Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 The Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256
algorithm to produce the common JWE Ciphertext and JWE Authentication algorithm to produce the common JWE Ciphertext and JWE Authentication
Tag values. The JWE Protected Header value representing this is: Tag values. The JWE Protected Header value representing this is:
{"enc":"A128CBC-HS256"} {"enc":"A128CBC-HS256"}
skipping to change at page 41, line 30 skipping to change at page 42, line 16
Combining the per-recipient, protected, and unprotected header values Combining the per-recipient, protected, and unprotected header values
supplied, the JWE Header values used for the first and second supplied, the JWE Header values used for the first and second
recipient respectively are: recipient respectively are:
{"alg":"RSA1_5", {"alg":"RSA1_5",
"kid":"2011-04-29", "kid":"2011-04-29",
"enc":"A128CBC-HS256", "enc":"A128CBC-HS256",
"jku":"https://server.example.com/keys.jwks"} "jku":"https://server.example.com/keys.jwks"}
and: and
{"alg":"A128KW", {"alg":"A128KW",
"kid":"7", "kid":"7",
"enc":"A128CBC-HS256", "enc":"A128CBC-HS256",
"jku":"https://server.example.com/keys.jwks"} "jku":"https://server.example.com/keys.jwks"}
A.4.5. Additional Authenticated Data A.4.5. Additional Authenticated Data
Let the Additional Authenticated Data encryption parameter be the Let the Additional Authenticated Data encryption parameter be the
octets of the ASCII representation of the Encoded JWE Protected octets of the ASCII representation of the Encoded JWE Protected
Header value. This AAD value is: Header value. This AAD value is:
[101, 121, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 77, 84, 73, [101, 121, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 77, 84, 73,
52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 110, 48] 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 110, 48]
A.4.6. Plaintext Encryption A.4.6. Content Encryption
Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as
the encryption key, the JWE Initialization Vector, and the Additional the encryption key, the JWE Initialization Vector, and the Additional
Authenticated Data value above. The steps for doing this using the Authenticated Data value above. The steps for doing this using the
values from Appendix A.3 are detailed in Appendix B. The resulting values from Appendix A.3 are detailed in Appendix B. The resulting
Ciphertext is: Ciphertext is:
[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 24 skipping to change at page 46, line 39
Hardt, Jeff Hodges, Edmund Jay, James Manger, Matt Miller, Tony Hardt, Jeff Hodges, Edmund Jay, James Manger, Matt Miller, Tony
Nadalin, Axel Nennker, Emmanuel Raviart, Nat Sakimura, Jim Schaad, Nadalin, Axel Nennker, Emmanuel Raviart, Nat Sakimura, Jim Schaad,
Hannes Tschofenig, and Sean Turner. 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 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 ]]
-16
o Changes to address editorial and minor issues #163, #168, #169,
#170, #172, and #173.
-15 -15
o Clarified that it is an application decision which recipients' o Clarified that it is an application decision which recipients'
encrypted content must successfully validate for the JWE to be encrypted content must successfully validate for the JWE to be
accepted, addressing issue #35. accepted, addressing issue #35.
o Changes to address editorial issues #34, #164, and #169. o Changes to address editorial issues #34, #164, and #169.
-14 -14
 End of changes. 75 change blocks. 
156 lines changed or deleted 180 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/