< draft-ietf-jose-json-web-encryption-17.txt   draft-ietf-jose-json-web-encryption-18.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: April 10, 2014 RTFM Expires: May 16, 2014 RTFM
J. Hildebrand J. Hildebrand
Cisco Cisco
October 7, 2013 November 12, 2013
JSON Web Encryption (JWE) JSON Web Encryption (JWE)
draft-ietf-jose-json-web-encryption-17 draft-ietf-jose-json-web-encryption-18
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 April 10, 2014. This Internet-Draft will expire on May 16, 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
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
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 . . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 4 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 5
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6
3. JSON Web Encryption (JWE) Overview . . . . . . . . . . . . . . 7 3. JSON Web Encryption (JWE) Overview . . . . . . . . . . . . . . 8
3.1. Example JWE . . . . . . . . . . . . . . . . . . . . . . . 9 3.1. Example JWE . . . . . . . . . . . . . . . . . . . . . . . 10
4. JWE Header . . . . . . . . . . . . . . . . . . . . . . . . . . 11 4. JWE Header . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.1. Registered Header Parameter Names . . . . . . . . . . . . 11 4.1. Registered Header Parameter Names . . . . . . . . . . . . 12
4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 11 4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 12
4.1.2. "enc" (Encryption Method) Header Parameter . . . . . . 12 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 . . . . 13
4.1.4. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 12 4.1.4. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 13
4.1.5. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 13 4.1.5. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 13
4.1.6. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 13 4.1.6. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 14
4.1.7. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header 4.1.7. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header
Parameter . . . . . . . . . . . . . . . . . . . . . . 13 Parameter . . . . . . . . . . . . . . . . . . . . . . 14
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 . . . . . . . . . . . 13 4.1.9. "kid" (Key ID) Header Parameter . . . . . . . . . . . 14
4.1.10. "typ" (Type) Header Parameter . . . . . . . . . . . . 13 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 . . . . . . . . 14
4.1.12. "crit" (Critical) Header Parameter . . . . . . . . . . 14 4.1.12. "crit" (Critical) Header Parameter . . . . . . . . . . 15
4.2. Public Header Parameter Names . . . . . . . . . . . . . . 14 4.2. Public Header Parameter Names . . . . . . . . . . . . . . 15
4.3. Private Header Parameter Names . . . . . . . . . . . . . . 14 4.3. Private Header Parameter Names . . . . . . . . . . . . . . 15
5. Producing and Consuming JWEs . . . . . . . . . . . . . . . . . 14 5. Producing and Consuming JWEs . . . . . . . . . . . . . . . . . 15
5.1. Message Encryption . . . . . . . . . . . . . . . . . . . . 14 5.1. Message Encryption . . . . . . . . . . . . . . . . . . . . 15
5.2. Message Decryption . . . . . . . . . . . . . . . . . . . . 16 5.2. Message Decryption . . . . . . . . . . . . . . . . . . . . 17
5.3. String Comparison Rules . . . . . . . . . . . . . . . . . 19 5.3. String Comparison Rules . . . . . . . . . . . . . . . . . 20
6. Key Identification . . . . . . . . . . . . . . . . . . . . . . 19 6. Key Identification . . . . . . . . . . . . . . . . . . . . . . 20
7. Serializations . . . . . . . . . . . . . . . . . . . . . . . . 19 7. Serializations . . . . . . . . . . . . . . . . . . . . . . . . 20
7.1. JWE Compact Serialization . . . . . . . . . . . . . . . . 19 7.1. JWE Compact Serialization . . . . . . . . . . . . . . . . 20
7.2. JWE JSON Serialization . . . . . . . . . . . . . . . . . . 19 7.2. JWE JSON Serialization . . . . . . . . . . . . . . . . . . 21
8. Distinguishing Between JWS and JWE Objects . . . . . . . . . . 22 8. TLS Requirements . . . . . . . . . . . . . . . . . . . . . . . 24
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 9. Distinguishing Between JWS and JWE Objects . . . . . . . . . . 24
9.1. JWE Header Parameter Names Registration . . . . . . . . . 23 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25
9.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 23 10.1. JSON Web Signature and Encryption Header Parameters
10. Security Considerations . . . . . . . . . . . . . . . . . . . 25 Registration . . . . . . . . . . . . . . . . . . . . . . . 25
11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 25 10.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 25
11.1. Normative References . . . . . . . . . . . . . . . . . . . 25 11. Security Considerations . . . . . . . . . . . . . . . . . . . 26
11.2. Informative References . . . . . . . . . . . . . . . . . . 26 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Appendix A. JWE Examples . . . . . . . . . . . . . . . . . . . . 27 12.1. Normative References . . . . . . . . . . . . . . . . . . . 27
A.1. Example JWE using RSAES OAEP and AES GCM . . . . . . . . . 27 12.2. Informative References . . . . . . . . . . . . . . . . . . 28
A.1.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 27 Appendix A. JWE Examples . . . . . . . . . . . . . . . . . . . . 29
A.1.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 27 A.1. Example JWE using RSAES OAEP and AES GCM . . . . . . . . . 29
A.1.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 28 A.1.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 29
A.1.4. Initialization Vector . . . . . . . . . . . . . . . . 29 A.1.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 29
A.1.5. Additional Authenticated Data . . . . . . . . . . . . 29 A.1.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 30
A.1.6. Content Encryption . . . . . . . . . . . . . . . . . . 29 A.1.4. Initialization Vector . . . . . . . . . . . . . . . . 31
A.1.7. Complete Representation . . . . . . . . . . . . . . . 30 A.1.5. Additional Authenticated Data . . . . . . . . . . . . 31
A.1.8. Validation . . . . . . . . . . . . . . . . . . . . . . 30 A.1.6. Content Encryption . . . . . . . . . . . . . . . . . . 31
A.1.7. Complete Representation . . . . . . . . . . . . . . . 32
A.1.8. Validation . . . . . . . . . . . . . . . . . . . . . . 32
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 . . . . . . . . . . . . . . . . . 30 AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 32
A.2.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 31 A.2.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 33
A.2.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 31 A.2.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 33
A.2.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 31 A.2.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 33
A.2.4. Initialization Vector . . . . . . . . . . . . . . . . 33 A.2.4. Initialization Vector . . . . . . . . . . . . . . . . 35
A.2.5. Additional Authenticated Data . . . . . . . . . . . . 33 A.2.5. Additional Authenticated Data . . . . . . . . . . . . 35
A.2.6. Content Encryption . . . . . . . . . . . . . . . . . . 33 A.2.6. Content Encryption . . . . . . . . . . . . . . . . . . 35
A.2.7. Complete Representation . . . . . . . . . . . . . . . 34 A.2.7. Complete Representation . . . . . . . . . . . . . . . 36
A.2.8. Validation . . . . . . . . . . . . . . . . . . . . . . 34 A.2.8. Validation . . . . . . . . . . . . . . . . . . . . . . 36
A.3. Example JWE using AES Key Wrap and A.3. Example JWE using AES Key Wrap and
AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 34 AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 36
A.3.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 34 A.3.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 36
A.3.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 35 A.3.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 37
A.3.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 35 A.3.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 37
A.3.4. Initialization Vector . . . . . . . . . . . . . . . . 36 A.3.4. Initialization Vector . . . . . . . . . . . . . . . . 38
A.3.5. Additional Authenticated Data . . . . . . . . . . . . 36 A.3.5. Additional Authenticated Data . . . . . . . . . . . . 38
A.3.6. Content Encryption . . . . . . . . . . . . . . . . . . 36 A.3.6. Content Encryption . . . . . . . . . . . . . . . . . . 38
A.3.7. Complete Representation . . . . . . . . . . . . . . . 37 A.3.7. Complete Representation . . . . . . . . . . . . . . . 39
A.3.8. Validation . . . . . . . . . . . . . . . . . . . . . . 37 A.3.8. Validation . . . . . . . . . . . . . . . . . . . . . . 39
A.4. Example JWE using JWE JSON Serialization . . . . . . . . . 37 A.4. Example JWE using JWE JSON Serialization . . . . . . . . . 39
A.4.1. JWE Per-Recipient Unprotected Headers . . . . . . . . 38 A.4.1. JWE Per-Recipient Unprotected Headers . . . . . . . . 40
A.4.2. JWE Protected Header . . . . . . . . . . . . . . . . . 38 A.4.2. JWE Protected Header . . . . . . . . . . . . . . . . . 40
A.4.3. JWE Unprotected Header . . . . . . . . . . . . . . . . 38 A.4.3. JWE Unprotected Header . . . . . . . . . . . . . . . . 40
A.4.4. Complete JWE Header Values . . . . . . . . . . . . . . 38 A.4.4. Complete JWE Header Values . . . . . . . . . . . . . . 40
A.4.5. Additional Authenticated Data . . . . . . . . . . . . 39 A.4.5. Additional Authenticated Data . . . . . . . . . . . . 41
A.4.6. Content Encryption . . . . . . . . . . . . . . . . . . 39 A.4.6. Content Encryption . . . . . . . . . . . . . . . . . . 41
A.4.7. Complete JWE JSON Serialization Representation . . . . 39 A.4.7. Complete JWE JSON Serialization Representation . . . . 41
Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation . . . . 40 Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation . . . . 42
B.1. Extract MAC_KEY and ENC_KEY from Key . . . . . . . . . . . 40 B.1. Extract MAC_KEY and ENC_KEY from Key . . . . . . . . . . . 42
B.2. Encrypt Plaintext to Create Ciphertext . . . . . . . . . . 41 B.2. Encrypt Plaintext to Create Ciphertext . . . . . . . . . . 43
B.3. 64 Bit Big Endian Representation of AAD Length . . . . . . 41 B.3. 64 Bit Big Endian Representation of AAD Length . . . . . . 43
B.4. Initialization Vector Value . . . . . . . . . . . . . . . 41 B.4. Initialization Vector Value . . . . . . . . . . . . . . . 43
B.5. Create Input to HMAC Computation . . . . . . . . . . . . . 42 B.5. Create Input to HMAC Computation . . . . . . . . . . . . . 44
B.6. Compute HMAC Value . . . . . . . . . . . . . . . . . . . . 42 B.6. Compute HMAC Value . . . . . . . . . . . . . . . . . . . . 44
B.7. Truncate HMAC Value to Create Authentication Tag . . . . . 42 B.7. Truncate HMAC Value to Create Authentication Tag . . . . . 44
Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 42 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 44
Appendix D. Document History . . . . . . . . . . . . . . . . . . 43 Appendix D. Document History . . . . . . . . . . . . . . . . . . 45
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 51 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 53
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 9 skipping to change at page 6, line 9
ASCII(STRING) denotes the octets of the ASCII [USASCII] ASCII(STRING) denotes the octets of the ASCII [USASCII]
representation of STRING. representation of STRING.
The concatenation of two values A and B is denoted as A || B. The concatenation of two values A and B is denoted as A || B.
2. Terminology 2. Terminology
These terms defined by the JSON Web Signature (JWS) [JWS] These terms defined by the JSON Web Signature (JWS) [JWS]
specification are incorporated into this specification: "JSON Web specification are incorporated into this specification: "JSON Web
Signature (JWS)", "JSON Text Object", "Base64url Encoding", Signature (JWS)", "Base64url Encoding", "Collision-Resistant Name",
"Collision Resistant Name", and "StringOrURI". and "StringOrURI".
These terms are defined for use by this specification: These terms are defined for use by this specification:
JSON Web Encryption (JWE) A data structure representing an encrypted JSON Web Encryption (JWE) A data structure representing an encrypted
and integrity protected message. and integrity protected message.
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
Authenticated Data to be specified, and provides an integrated Authenticated Data to be specified, and provides an integrated
content integrity check over the Ciphertext and Additional content integrity check over the Ciphertext and Additional
skipping to change at page 5, line 44 skipping to change at page 6, line 44
Authentication Tag An output of an AEAD operation that ensures the Authentication Tag An output of an AEAD operation that ensures the
integrity of the Ciphertext and the Additional Authenticated Data. integrity of the Ciphertext and the Additional Authenticated Data.
Note that some algorithms may not use an Authentication Tag, in Note that some algorithms may not use an Authentication Tag, in
which case this value is the empty octet sequence. which case this value is the empty octet sequence.
Content Encryption Key (CEK) A symmetric key for the AEAD algorithm Content Encryption Key (CEK) A symmetric key for the AEAD algorithm
used to encrypt the Plaintext for the recipient to produce the used to encrypt the Plaintext for the recipient to produce the
Ciphertext and the Authentication Tag. Ciphertext and the Authentication Tag.
JWE Header A JSON Text Object (or JSON Text Objects, when using the JWE Header A JSON object (or JSON objects, when using the JWE JSON
JWE JSON Serialization) that describes the encryption operations Serialization) that describes the encryption operations applied to
applied to create the JWE Encrypted Key, the JWE Ciphertext, and create the JWE Encrypted Key, the JWE Ciphertext, and the JWE
the JWE Authentication Tag. The members of the JWE Header Authentication Tag. The members of the JWE Header object(s) are
object(s) are Header Parameters. Header Parameters.
JWE Encrypted Key The result of encrypting the Content Encryption JWE Encrypted Key The result of encrypting the Content Encryption
Key (CEK) with the intended recipient's key using the specified Key (CEK) with the intended recipient's key using the specified
algorithm. Note that for some algorithms, the JWE Encrypted Key algorithm. Note that for some algorithms, the JWE Encrypted Key
value is specified as being the empty octet sequence. value is specified as being the empty octet sequence.
JWE Initialization Vector A sequence of octets containing the JWE Initialization Vector A sequence of octets containing the
Initialization Vector used when encrypting the Plaintext. Note Initialization Vector used when encrypting the Plaintext. Note
that some algorithms may not use an Initialization Vector, in that some algorithms may not use an Initialization Vector, in
which case this value is the empty octet sequence. which case this value is the empty octet sequence.
JWE Ciphertext A sequence of octets containing the Ciphertext for a JWE Ciphertext A sequence of octets containing the Ciphertext for a
JWE. JWE.
JWE Authentication Tag A sequence of octets containing the JWE Authentication Tag A sequence of octets containing the
Authentication Tag for a JWE. Authentication Tag for a JWE.
JWE Protected Header A JSON Text Object that contains the portion of JWE Protected Header A JSON object that contains the portion of the
the JWE Header that is integrity protected. For the JWE Compact JWE Header that is integrity protected. For the JWE Compact
Serialization, this comprises the entire JWE Header. For the JWE Serialization, this comprises the entire JWE Header. For the JWE
JSON Serialization, this is one component of the JWE Header. JSON Serialization, this is one component of the JWE Header.
Header Parameter A name/value pair that is member of the JWE Header. Header Parameter A name/value pair that is member of the JWE Header.
JWE Compact Serialization A representation of the JWE as the string JWE Compact Serialization A representation of the JWE as a compact,
BASE64URL(UTF8(JWE Protected Header)) || '.' || BASE64URL(JWE URL-safe string.
Encrypted Key) || '.' || BASE64URL(JWE Initialization Vector) ||
'.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE
Authentication Tag). 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 object.
structure. Unlike the JWE Compact Serialization, the JWE JSON Unlike the JWE Compact Serialization, the JWE JSON Serialization
Serialization enables the same content to be encrypted to multiple enables the same content to be encrypted to multiple parties.
parties. This representation is neither compact nor URL-safe. This representation is neither compact nor URL-safe.
Key Management Mode A method of determining the Content Encryption Key Management Mode A method of determining the Content Encryption
Key (CEK) value to use. Each algorithm used for determining the Key (CEK) value to use. Each algorithm used for determining the
CEK value uses a specific Key Management Mode. Key Management CEK value uses a specific Key Management Mode. Key Management
Modes employed by this specification are Key Encryption, Key Modes employed by this specification are Key Encryption, Key
Wrapping, Direct Key Agreement, Key Agreement with Key Wrapping, Wrapping, Direct Key Agreement, Key Agreement with Key Wrapping,
and Direct Encryption. and Direct Encryption.
Key Encryption A Key Management Mode in which the Content Encryption Key Encryption A Key Management Mode in which the Content Encryption
Key (CEK) value is encrypted to the intended recipient using an Key (CEK) value is encrypted to the intended recipient using an
skipping to change at page 12, line 11 skipping to change at page 13, line 4
JSON Web Signature and Encryption Algorithms registry defined in JSON Web Signature and Encryption Algorithms registry defined in
[JWA]; the initial contents of this registry are the values defined [JWA]; the initial contents of this registry are the values defined
in Section 4.1 of the JSON Web Algorithms (JWA) [JWA] specification. in Section 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 defined in [JWA] or be a value that contains a Algorithms registry defined in [JWA] or be a value that contains a
Collision Resistant Name. 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. This Header Parameter MUST be
REQUIRED. This Header Parameter MUST be understood and processed by present and MUST be understood and processed by implementations.
implementations.
A list of defined "enc" values for this use can be found in the IANA A list of defined "enc" values for this use can be found in the IANA
JSON Web Signature and Encryption Algorithms registry defined in JSON Web Signature and Encryption Algorithms registry defined in
[JWA]; the initial contents of this registry are the values defined [JWA]; the initial contents of this registry are the values defined
in Section 4.2 of the JSON Web Algorithms (JWA) [JWA] specification. in Section 5.1 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. The "zip" value defined by this specification encryption, if any. The "zip" value defined by this specification
is: is:
o "DEF" - Compression with the DEFLATE [RFC1951] algorithm o "DEF" - Compression with the DEFLATE [RFC1951] algorithm
Other values MAY be used. Compression algorithm values can be Other values MAY be used. Compression algorithm values can be
registered in the IANA JSON Web Encryption Compression Algorithm registered in the IANA JSON Web Encryption Compression Algorithm
registry defined in [JWA]. The "zip" value is a case sensitive registry defined in [JWA]. The "zip" value is a case-sensitive
string. If no "zip" parameter is present, no compression is applied string. If no "zip" parameter is present, no compression is applied
to the Plaintext before encryption. This Header Parameter MUST be to the Plaintext before encryption. This Header Parameter MUST be
integrity protected, and therefore MUST occur only within the JWE integrity protected, and therefore MUST occur only within the JWE
Protected Header, when used. Use of this Header Parameter is Protected Header, when used. Use of this Header Parameter is
OPTIONAL. This Header Parameter MUST be understood and processed by OPTIONAL. This Header Parameter MUST be understood and processed by
implementations. implementations.
4.1.4. "jku" (JWK Set URL) Header Parameter 4.1.4. "jku" (JWK Set URL) Header Parameter
This parameter has the same meaning, syntax, and processing rules as This parameter has the same meaning, syntax, and processing rules as
skipping to change at page 14, line 14 skipping to change at page 15, line 8
4.1.11. "cty" (Content Type) Header Parameter 4.1.11. "cty" (Content Type) Header Parameter
This parameter has the same meaning, syntax, and processing rules as This parameter has the same meaning, syntax, and processing rules as
the "cty" Header Parameter defined in Section 4.1.9 of [JWS], except the "cty" Header Parameter defined in Section 4.1.9 of [JWS], except
that the type is of the secured content (the payload). that the type is of the secured content (the payload).
4.1.12. "crit" (Critical) Header Parameter 4.1.12. "crit" (Critical) Header Parameter
This parameter has the same meaning, syntax, and processing rules as This parameter has the same meaning, syntax, and processing rules as
the "typ" Header Parameter defined in Section 4.1.8 of [JWS], except the "crit" Header Parameter defined in Section 4.1.10 of [JWS],
that the Header Parameters referenced are the JWE Header Parameters. except that JWE Header Parameters are being referred to, rather than
JWS Header Parameters.
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 defined in [JWS] or be a Public Encryption Header Parameters registry defined in [JWS] or be a Public
Name: a value that contains a Collision Resistant Name. In each Name: a value that contains a Collision-Resistant Name. In each
case, the definer of the name or value needs to take reasonable case, the definer of the name or value needs to take reasonable
precautions to make sure they are in control of the part of the precautions to make sure they are in control of the part of the
namespace they 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
skipping to change at page 15, line 22 skipping to change at page 16, line 17
employed, use the key agreement algorithm to compute the value employed, use the key agreement algorithm to compute the value
of the agreed upon key. When Direct Key Agreement is employed, of the agreed upon key. When Direct Key Agreement is employed,
let the Content Encryption Key (CEK) be the agreed upon key. let the Content Encryption Key (CEK) be the agreed upon key.
When Key Agreement with Key Wrapping is employed, the agreed When Key Agreement with Key Wrapping is employed, the agreed
upon key will be used to wrap the CEK. upon key will be used to wrap the CEK.
4. When Key Wrapping, Key Encryption, or Key Agreement with Key 4. When Key Wrapping, Key Encryption, or Key Agreement with Key
Wrapping are employed, encrypt the CEK to the recipient and let Wrapping are employed, encrypt the CEK to the recipient and let
the result be the JWE Encrypted Key. the result be the JWE Encrypted Key.
5. Otherwise, when Direct Key Agreement or Direct Encryption are 5. When Direct Key Agreement or Direct Encryption are employed, let
employed, let the JWE Encrypted Key be the empty octet sequence. the JWE Encrypted Key be the empty octet sequence.
6. When Direct Encryption is employed, let the Content Encryption 6. When Direct Encryption is employed, let the Content Encryption
Key (CEK) be the shared symmetric key. Key (CEK) be the shared symmetric key.
7. Compute the encoded key value BASE64URL(JWE Encrypted Key). 7. Compute the encoded key value BASE64URL(JWE Encrypted Key).
8. If the JWE JSON Serialization is being used, repeat this process 8. If the JWE JSON Serialization is being used, repeat this process
for each recipient. (steps 1-7) for each recipient.
9. Generate a random JWE Initialization Vector of the correct size 9. Generate a random JWE Initialization Vector of the correct size
for the content encryption algorithm (if required for the for the content encryption algorithm (if required for the
algorithm); otherwise, let the JWE Initialization Vector be the algorithm); otherwise, let the JWE Initialization Vector be the
empty octet sequence. empty octet sequence.
10. Compute the encoded initialization vector value BASE64URL(JWE 10. Compute the encoded initialization vector value BASE64URL(JWE
Initialization Vector). Initialization Vector).
11. Compress the Plaintext if a "zip" parameter was included. 11. If a "zip" parameter was included, compress the Plaintext using
the specified compression algorithm.
12. Serialize the (compressed) Plaintext into an octet sequence M. 12. Serialize the (compressed) Plaintext into an octet sequence M.
13. Create a JWE Header containing the encryption parameters used. 13. Create the JSON object(s) containing the desired set of Header
Note that white space is explicitly allowed in the Parameters, which together comprise the JWE Header: the JWE
representation and no canonicalization need be performed before Protected Header, and if the JWE JSON Serialization is being
encoding. used, the JWE Shared Unprotected Header and the JWE Per-
Recipient Unprotected Header.
14. Compute the encoded header value BASE64URL(UTF8(JWE Protected 14. Compute the Encoded Protected Header value BASE64URL(UTF8(JWE
Header)). If the JWE Protected Header is not present (which can Protected Header)). If the JWE Protected Header is not present
only happen when using the JWE JSON Serialization and no (which can only happen when using the JWE JSON Serialization and
"protected" member is present), let this value be the empty no "protected" member is present), let this value be the empty
string. string.
15. Let the Additional Authenticated Data encryption parameter be 15. Let the Additional Authenticated Data encryption parameter be
ASCII(BASE64URL(UTF8(JWE Protected Header))). However if a JWE ASCII(Encoded Protected Header). However if a JWE AAD value is
AAD value is present when using the JWE JSON Serialization, present (which can only be the case when using the JWE JSON
instead let the Additional Authenticated Data encryption Serialization), instead let the Additional Authenticated Data
parameter be ASCII(BASE64URL(UTF8(JWE Protected Header)) || '.' encryption parameter be ASCII(Encoded Protected Header || '.' ||
|| BASE64URL(JWE AAD)). BASE64URL(JWE AAD)).
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. Compute the encoded ciphertext value BASE64URL(JWE Ciphertext). 17. Compute the encoded ciphertext value BASE64URL(JWE Ciphertext).
18. Compute the encoded authentication tag value BASE64URL(JWE 18. Compute the encoded authentication tag value BASE64URL(JWE
skipping to change at page 17, line 27 skipping to change at page 18, line 26
Authentication Tag are represented as base64url encoded values Authentication Tag are represented as base64url encoded values
in that order, separated by four period ('.') characters. The in that order, separated by four period ('.') characters. The
JWE JSON Serialization is described in Section 7.2. JWE JSON Serialization is described in Section 7.2.
2. The encoded representations of the JWE Protected Header, the JWE 2. The encoded representations of the JWE Protected Header, the JWE
Encrypted Key, the JWE Initialization Vector, the JWE Encrypted Key, the JWE Initialization Vector, the JWE
Ciphertext, the JWE Authentication Tag, and the JWE AAD MUST be Ciphertext, the JWE Authentication Tag, and the JWE AAD MUST be
successfully base64url decoded following the restriction that no successfully base64url decoded following the restriction that no
padding characters have been used. padding characters have been used.
3. The resulting UTF8 encoded JWE Protected Header MUST be a 3. The octet sequence resulting from decoding the encoded JWE
completely valid JSON object conforming to RFC 4627 [RFC4627]. Protected Header MUST be a UTF-8 encoded representation of a
completely valid JSON object conforming to RFC 4627 [RFC4627],
which is the JWE Protected Header.
4. If using the JWE Compact Serialization, let the JWE Header be 4. If using the JWE Compact Serialization, let the JWE Header be
the JWE Protected Header; otherwise, when using the JWE JSON the JWE Protected Header; otherwise, when using the JWE JSON
Serialization, let the JWE Header be the union of the members of Serialization, let the JWE Header be the union of the members of
the JWE Protected Header, the JWE Shared Unprotected Header and the JWE Protected Header, the JWE Shared Unprotected Header and
the corresponding JWE Per-Recipient Unprotected Header, all of the corresponding JWE Per-Recipient Unprotected Header, all of
which must be completely valid JSON objects. which must be completely valid JSON objects.
5. The resulting JWE Header MUST NOT contain duplicate Header 5. The resulting JWE Header MUST NOT contain duplicate Header
Parameter names. When using the JWE JSON Serialization, this Parameter names. When using the JWE JSON Serialization, this
restriction includes that the same Header Parameter name also restriction includes that the same Header Parameter name also
MUST NOT occur in distinct JSON Text Object values that together MUST NOT occur in distinct JSON object values that together
comprise the JWE Header. comprise the JWE Header.
6. The resulting JWE Header MUST be validated to only include 6. Verify that the implementation understands and can process all
parameters and values whose syntax and semantics are both fields that it is required to support, whether required by this
understood and supported or that are specified as being ignored specification, by the algorithms being used, or by the "crit"
when not understood. Header Parameter value, and that the values of those parameters
are also understood and supported.
7. Determine the Key Management Mode employed by the algorithm 7. Determine the Key Management Mode employed by the algorithm
specified by the "alg" (algorithm) Header Parameter. specified by the "alg" (algorithm) Header Parameter.
8. Verify that the JWE uses a key known to the recipient. 8. Verify that the JWE uses a key known to the recipient.
9. When Direct Key Agreement or Key Agreement with Key Wrapping are 9. When Direct Key Agreement or Key Agreement with Key Wrapping are
employed, use the key agreement algorithm to compute the value employed, use the key agreement algorithm to compute the value
of the agreed upon key. When Direct Key Agreement is employed, of the agreed upon key. When Direct Key Agreement is employed,
let the Content Encryption Key (CEK) be the agreed upon key. let the Content Encryption Key (CEK) be the agreed upon key.
skipping to change at page 18, line 30 skipping to change at page 19, line 30
encrypted to a key in that recipient's possession. It is encrypted to a key in that recipient's possession. It is
therefore normal to only be able to decrypt one of the per- therefore normal to only be able to decrypt one of the per-
recipient JWE Encrypted Key values to obtain the CEK value. To recipient JWE Encrypted Key values to obtain the CEK value. To
mitigate the attacks described in RFC 3218 [RFC3218], the mitigate the attacks described in RFC 3218 [RFC3218], the
recipient MUST NOT distinguish between format, padding, and recipient MUST NOT distinguish between format, padding, and
length errors of encrypted keys. It is strongly recommended, in length errors of encrypted keys. It is strongly recommended, in
the event of receiving an improperly formatted key, that the the event of receiving an improperly formatted key, that the
receiver substitute a randomly generated CEK and proceed to the receiver substitute a randomly generated CEK and proceed to the
next step, to mitigate timing attacks. next step, to mitigate timing attacks.
11. Otherwise, when Direct Key Agreement or Direct Encryption are 11. When Direct Key Agreement or Direct Encryption are employed,
employed, verify that the JWE Encrypted Key value is empty octet verify that the JWE Encrypted Key value is empty octet sequence.
sequence.
12. When Direct Encryption is employed, let the Content Encryption 12. When Direct Encryption is employed, let the Content Encryption
Key (CEK) be the shared symmetric key. Key (CEK) be the shared symmetric key.
13. If the JWE JSON Serialization is being used, repeat this process 13. If the JWE JSON Serialization is being used, repeat this process
for each recipient contained in the representation until the CEK (steps 1-12) for each recipient contained in the representation
value has been determined. until the CEK value has been determined.
14. Let the Additional Authenticated Data encryption parameter be 14. Compute the Encoded Protected Header value BASE64URL(UTF8(JWE
ASCII(BASE64URL(UTF8(JWE Protected Header))). However if a JWE Protected Header)). If the JWE Protected Header is not present
AAD value is present when using the JWE JSON Serialization, (which can only happen when using the JWE JSON Serialization and
instead let the Additional Authenticated Data encryption no "protected" member is present), let this value be the empty
parameter be ASCII(BASE64URL(UTF8(JWE Protected Header)) || '.' string.
|| BASE64URL(JWE AAD)).
15. Decrypt the JWE Ciphertext using the CEK, the JWE Initialization 15. Let the Additional Authenticated Data encryption parameter be
ASCII(Encoded Protected Header). However if a JWE AAD value is
present (which can only be the case when using the JWE JSON
Serialization), instead let the Additional Authenticated Data
encryption parameter be ASCII(Encoded Protected Header || '.' ||
BASE64URL(JWE AAD)).
16. Decrypt the JWE Ciphertext using the CEK, the JWE Initialization
Vector, the Additional Authenticated Data value, and the JWE Vector, the Additional Authenticated Data value, and the JWE
Authentication Tag (which is the Authentication Tag input to the Authentication Tag (which is the Authentication Tag input to the
calculation) using the specified content encryption algorithm, calculation) using the specified content encryption algorithm,
returning the decrypted plaintext and verifying the JWE returning the decrypted plaintext and verifying the JWE
Authentication Tag in the manner specified for the algorithm, Authentication Tag 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 Authentication Tag is incorrect. JWE Authentication Tag is incorrect.
16. Uncompress the decrypted plaintext if a "zip" parameter was 17. If a "zip" parameter was included, uncompress the decrypted
included. plaintext using the specified compression algorithm.
17. Output the resulting Plaintext. 18. If all the previous steps succeeded, output the resulting
Plaintext.
5.3. String Comparison Rules 5.3. String Comparison Rules
The string comparison rules for this specification are the same as The string comparison rules for this specification are the same as
those defined in Section 5.3 of [JWS]. those defined in Section 5.3 of [JWS].
6. Key Identification 6. Key Identification
The key identification methods for this specification are the same as The key identification methods for this specification are the same as
those defined in Section 6 of [JWS], except that the key being those defined in Section 6 of [JWS], except that the key being
identified is the public key to which the JWE was encrypted. identified is the public key to which the JWE was encrypted.
7. Serializations 7. Serializations
JWE objects use one of two serializations, the JWE Compact JWE objects use one of two serializations, the JWE Compact
Serialization or the JWE JSON Serialization. For general-purpose Serialization or the JWE JSON Serialization. Applications using this
implementations, both the JWE Compact Serialization and JWE JSON specification need to specify what serialization and serialization
Serialization support for the single recipient case are mandatory to features are used for that application. For instance, applications
implement; support for multiple recipients is OPTIONAL. Special- might specify that only the JWE JSON Serialization is used, that only
purpose implementations are permitted to implement only a single JWE JSON Serialization support for a single recipient is used, or
serialization, if that meets the needs of the targeted use cases. that support for multiple recipients is used. JWE implementations
only need to implement the features needed for the applications they
are designed to support.
7.1. JWE Compact Serialization 7.1. JWE Compact Serialization
The JWE Compact Serialization represents encrypted content as a The JWE Compact Serialization represents encrypted content as a
compact URL-safe string. This string is BASE64URL(UTF8(JWE Protected compact URL-safe string. This string is BASE64URL(UTF8(JWE Protected
Header)) || '.' || BASE64URL(JWE Encrypted Key) || '.' || Header)) || '.' || BASE64URL(JWE Encrypted Key) || '.' ||
BASE64URL(JWE Initialization Vector) || '.' || BASE64URL(JWE BASE64URL(JWE Initialization Vector) || '.' || BASE64URL(JWE
Ciphertext) || '.' || BASE64URL(JWE Authentication Tag). Only one Ciphertext) || '.' || BASE64URL(JWE Authentication Tag). Only one
recipient is supported by the JWE Compact Serialization. recipient is supported by the JWE Compact Serialization and it
provides no syntax to represent JWE Shared Unprotected Header, JWE
Per-Recipient Unprotected Header, or JWE AAD values.
7.2. JWE JSON Serialization 7.2. JWE JSON Serialization
The JWE JSON Serialization represents encrypted content as a JSON The JWE JSON Serialization represents encrypted content as a JSON
object. Unlike the JWE Compact Serialization, content using the JWE object. Unlike the JWE Compact Serialization, content using the JWE
JSON Serialization can be encrypted to more than one recipient. JSON Serialization can be encrypted to more than one recipient.
The representation is closely related to that used in the JWE Compact The representation is closely related to that used in the JWE Compact
Serialization, with the following differences for the JWE JSON Serialization, with the following differences for the JWE JSON
Serialization: Serialization:
skipping to change at page 20, line 21 skipping to change at page 21, line 31
o The value BASE64URL(UTF8(JWE Protected Header)), if non-empty, is o The value BASE64URL(UTF8(JWE Protected Header)), if non-empty, is
stored in the "protected" member. stored in the "protected" member.
o The value BASE64URL(UTF8(JWE Shared Unprotected Header)), if non- o The value BASE64URL(UTF8(JWE Shared Unprotected Header)), if non-
empty, is stored in the "unprotected" member. empty, is stored in the "unprotected" member.
o The value BASE64URL(JWE Initialization Vector), if non-empty, is o The value BASE64URL(JWE Initialization Vector), if non-empty, is
stored in the "iv" member. stored in the "iv" member.
o The value BASE64URL(JWE Ciphertext)is stored in the "ciphertext" o The value BASE64URL(JWE Ciphertext) is stored in the "ciphertext"
member. member.
o The value BASE64URL(JWE Authentication Tag), if non-empty, is o The value BASE64URL(JWE Authentication Tag), if non-empty, is
stored in the "tag" member. stored in the "tag" member.
o The JWE can be encrypted to multiple recipients, rather than just o The JWE can be encrypted to multiple recipients, rather than just
one. A JSON array in the "recipients" member is used to hold one. A JSON array in the "recipients" member is used to hold
values that are specific to a particular recipient, with one array values that are specific to a particular recipient, with one array
element per recipient represented. These array elements are JSON element per recipient represented. These array elements are JSON
objects. objects.
skipping to change at page 21, line 6 skipping to change at page 22, line 16
shared among all recipient computations. Header Parameters in the shared among all recipient computations. Header Parameters in the
JWE Protected Header and JWE Shared Unprotected Header values are JWE Protected Header and JWE Shared Unprotected Header values are
shared among all recipients. shared among all recipients.
o Not all Header Parameters are integrity protected. The shared o Not all Header Parameters are integrity protected. The shared
Header Parameters in the JWE Protected Header value member are Header Parameters in the JWE Protected Header value member are
integrity protected, and are base64url encoded for transmission. integrity protected, and are base64url encoded for transmission.
The per-recipient Header Parameters in the JWE Per-Recipient The per-recipient Header Parameters in the JWE Per-Recipient
Unprotected Header values and the shared Header Parameters in the Unprotected Header values and the shared Header Parameters in the
JWE Shared Unprotected Header value are not integrity protected. JWE Shared Unprotected Header value are not integrity protected.
These JSON Text Objects containing Header Parameters that are not These JSON objects containing Header Parameters that are not
integrity protected are not base64url encoded. integrity protected are not base64url encoded.
o The Header Parameter values used when creating or validating per- o The Header Parameter values used when creating or validating per-
recipient Ciphertext and Authentication Tag values are the union recipient Ciphertext and Authentication Tag values are the union
of the three sets of Header Parameter values that may be present: of the three sets of Header Parameter values that may be present:
(1) the JWE Protected Header values represented in the "protected" (1) the JWE Protected Header values represented in the "protected"
member, (2) the JWE Shared Unprotected Header values represented member, (2) the JWE Shared Unprotected Header values represented
in the "unprotected" member, and (3) the JWE Per-Recipient in the "unprotected" member, and (3) the JWE Per-Recipient
Unprotected Header values represented in the "header" member of Unprotected Header values represented in the "header" member of
the recipient's array element. The union of these sets of Header the recipient's array element. The union of these sets of Header
skipping to change at page 22, line 45 skipping to change at page 24, line 15
in potentially significant space savings if the message is large. in potentially significant space savings if the message is large.
Therefore, all Header Parameters that specify the treatment of the Therefore, all Header Parameters that specify the treatment of the
Plaintext value MUST be the same for all recipients. This primarily Plaintext value MUST be the same for all recipients. This primarily
means that the "enc" (encryption method) Header Parameter value in means that the "enc" (encryption method) Header Parameter value in
the JWE Header for each recipient and any parameters of that the JWE Header for each recipient and any parameters of that
algorithm MUST be the same. algorithm MUST be the same.
See Appendix A.4 for an example of computing a JWE using the JWE JSON See Appendix A.4 for an example of computing a JWE using the JWE JSON
Serialization. Serialization.
8. Distinguishing Between JWS and JWE Objects 8. TLS Requirements
The TLS requirements for this specification are the same as those
defined in Section 8 of [JWS].
9. Distinguishing Between JWS and JWE Objects
There are several ways of distinguishing whether an object is a JWS There are several ways of distinguishing whether an object is a JWS
or JWE object. All these methods will yield the same result for all or JWE object. All these methods will yield the same result for all
legal input values. legal input values; they may yield different results for malformed
inputs.
o If the object is using the JWS Compact Serialization or the JWE o If the object is using the JWS Compact Serialization or the JWE
Compact Serialization, the number of base64url encoded segments Compact Serialization, the number of base64url encoded segments
separated by period ('.') characters differs for JWSs and JWEs. separated by period ('.') characters differs for JWSs and JWEs.
JWSs have three segments separated by two period ('.') characters. JWSs have three segments separated by two period ('.') characters.
JWEs have five segments separated by four period ('.') characters. JWEs have five segments separated by four period ('.') characters.
o If the object is using the JWS JSON Serialization or the JWE JSON o If the object is using the JWS JSON Serialization or the JWE JSON
Serialization, the members used will be different. JWSs have a Serialization, the members used will be different. JWSs have a
"signatures" member and JWEs do not. JWEs have a "recipients" "signatures" member and JWEs do not. JWEs have a "recipients"
member and JWSs do not. member and JWSs do not.
o A JWS Header can be distinguished from a JWE header by examining o A JWS Header can be distinguished from a JWE header by examining
the "alg" (algorithm) Header Parameter value. If the value the "alg" (algorithm) Header Parameter value. If the value
represents a digital signature or MAC algorithm, or is the value represents a digital signature or MAC algorithm, or is the value
"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. (Extracting the
"alg" value to examine is straightforward when using the JWS
Compact Serialization or the JWE Compact Serialization and may be
more difficult when using the JWS JSON Serialization or the JWE
JSON Serialization.)
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 10. IANA Considerations
9.1. JWE Header Parameter Names Registration 10.1. JSON Web Signature and Encryption Header Parameters 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 defined in [JWS]. Parameters registry defined in [JWS].
9.1.1. Registry Contents 10.1.1. Registry Contents
o Header Parameter Name: "alg" o Header Parameter Name: "alg"
o Header Parameter Description: Algorithm
o Header Parameter Usage Location(s): JWE o Header Parameter Usage Location(s): JWE
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 4.1.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 Description: Encryption Method
o Header Parameter Usage Location(s): JWE o Header Parameter Usage Location(s): JWE
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 4.1.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 Description: Compression Algorithm
o Header Parameter Usage Location(s): JWE o Header Parameter Usage Location(s): JWE
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 4.1.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 Description: JWK Set URL
o Header Parameter Usage Location(s): JWE o Header Parameter Usage Location(s): JWE
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 4.1.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 Description: JSON Web Key
o Header Parameter Usage Location(s): JWE o Header Parameter Usage Location(s): JWE
o Change Controller: IESG o Change Controller: IESG
o Specification document(s): Section 4.1.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 Description: X.509 URL
o Header Parameter Usage Location(s): JWE o Header Parameter Usage Location(s): JWE
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 4.1.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 Description: X.509 Certificate SHA-1 Thumbprint
o Header Parameter Usage Location(s): JWE o Header Parameter Usage Location(s): JWE
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 4.1.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 Description: X.509 Certificate Chain
o Header Parameter Usage Location(s): JWE o Header Parameter Usage Location(s): JWE
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 4.1.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 Description: Key ID
o Header Parameter Usage Location(s): JWE o Header Parameter Usage Location(s): JWE
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 4.1.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 Description: Type
o Header Parameter Usage Location(s): JWE o Header Parameter Usage Location(s): JWE
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 4.1.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 Description: Content Type
o Header Parameter Usage Location(s): JWE o Header Parameter Usage Location(s): JWE
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 4.1.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 Description: Critical
o Header Parameter Usage Location(s): JWE o Header Parameter Usage Location(s): JWE
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 4.1.12 of [[ this document ]] o Specification Document(s): Section 4.1.12 of [[ this document ]]
10. Security Considerations 11. Security Considerations
All of the security issues faced by any cryptographic application All of the security issues faced by any cryptographic application
must be faced by a JWS/JWE/JWK agent. Among these issues are must be faced by a JWS/JWE/JWK agent. Among these issues are
protecting the user's private and symmetric keys, preventing various protecting the user's 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.
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
skipping to change at page 25, line 30 skipping to change at page 27, line 23
recipient to be used as an oracle for decrypting messages. RFC 3218 recipient to be used as an oracle for decrypting messages. RFC 3218
[RFC3218] should be consulted for specific countermeasures to attacks [RFC3218] should be consulted for specific countermeasures to attacks
on RSAES-PKCS1-V1_5. An attacker might modify the contents of the on RSAES-PKCS1-V1_5. An attacker might modify the contents of the
"alg" parameter from "RSA-OAEP" to "RSA1_5" in order to generate a "alg" parameter from "RSA-OAEP" to "RSA1_5" in order to generate a
formatting error that can be detected and used to recover the CEK formatting error that can be detected and used to recover the CEK
even if RSAES OAEP was used to encrypt the CEK. It is therefore even if RSAES OAEP was used to encrypt the CEK. It is therefore
particularly important to report all formatting errors to the CEK, particularly important to report all formatting errors to the CEK,
Additional Authenticated Data, or ciphertext as a single error when Additional Authenticated Data, or ciphertext as a single error when
the encrypted content is rejected. the encrypted content is rejected.
11. References Additionally, this type of attack can be prevented by the use of "key
tainting". This method restricts the use of a key to a limited set
of algorithms -- usually one. This means, for instance, that if the
key is marked as being for "RSA-OAEP" only, any attempt to decrypt a
message using the "RSA1_5" algorithm with that key would fail
immediately due to invalid use of the key.
11.1. Normative References 12. References
12.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.
[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),
October 2013. November 2013.
[JWK] Jones, M., "JSON Web Key (JWK)", [JWK] Jones, M., "JSON Web Key (JWK)",
draft-ietf-jose-json-web-key (work in progress), draft-ietf-jose-json-web-key (work in progress),
October 2013. November 2013.
[JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web
Signature (JWS)", draft-ietf-jose-json-web-signature (work Signature (JWS)", draft-ietf-jose-json-web-signature (work
in progress), October 2013. in progress), November 2013.
[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.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, November 2003. 10646", STD 63, RFC 3629, November 2003.
skipping to change at page 26, line 33 skipping to change at page 28, line 34
Set -- 7-bit American Standard Code for Information Set -- 7-bit American Standard Code for Information
Interchange", ANSI X3.4, 1986. Interchange", ANSI X3.4, 1986.
[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 12.2. Informative References
[I-D.mcgrew-aead-aes-cbc-hmac-sha2] [I-D.mcgrew-aead-aes-cbc-hmac-sha2]
McGrew, D. and K. Paterson, "Authenticated Encryption with McGrew, D. and K. Paterson, "Authenticated Encryption with
AES-CBC and HMAC-SHA", AES-CBC and HMAC-SHA",
draft-mcgrew-aead-aes-cbc-hmac-sha2-01 (work in progress), draft-mcgrew-aead-aes-cbc-hmac-sha2-01 (work in progress),
October 2012. October 2012.
[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
skipping to change at page 43, line 26 skipping to change at page 45, line 26
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 ]]
-18
o Updated the mandatory-to-implement (MTI) language to say that
applications using this specification need to specify what
serialization and serialization features are used for that
application, addressing issue #176.
o Changes to address editorial and minor issues #89, #135, #165,
#174, #175, #177, #179, and #180.
o Used Header Parameter Description registry field.
-17 -17
o Refined the "typ" and "cty" definitions to always be MIME Media o Refined the "typ" and "cty" definitions to always be MIME Media
Types, with the omission of "application/" prefixes recommended Types, with the omission of "application/" prefixes recommended
for brevity, addressing issue #50. for brevity, addressing issue #50.
o Updated the mandatory-to-implement (MTI) language to say that o Updated the mandatory-to-implement (MTI) language to say that
general-purpose implementations must implement the single general-purpose implementations must implement the single
recipient case for both serializations whereas special-purpose recipient case for both serializations whereas special-purpose
implementations can implement just one serialization if that meets implementations can implement just one serialization if that meets
 End of changes. 69 change blocks. 
174 lines changed or deleted 229 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/