< draft-ietf-jose-json-web-encryption-21.txt   draft-ietf-jose-json-web-encryption-22.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: August 18, 2014 RTFM Expires: September 3, 2014 RTFM
J. Hildebrand J. Hildebrand
Cisco Cisco
February 14, 2014 March 2, 2014
JSON Web Encryption (JWE) JSON Web Encryption (JWE)
draft-ietf-jose-json-web-encryption-21 draft-ietf-jose-json-web-encryption-22
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 August 18, 2014. This Internet-Draft will expire on September 3, 2014.
Copyright Notice Copyright Notice
Copyright (c) 2014 IETF Trust and the persons identified as the Copyright (c) 2014 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 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 . . . . . . . . . . . . . . . . . . . . . . . . . 6 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6
3. JSON Web Encryption (JWE) Overview . . . . . . . . . . . . . . 8 3. JSON Web Encryption (JWE) Overview . . . . . . . . . . . . . . 9
3.1. Example JWE . . . . . . . . . . . . . . . . . . . . . . . 10 3.1. Example JWE . . . . . . . . . . . . . . . . . . . . . . . 11
4. JWE Header . . . . . . . . . . . . . . . . . . . . . . . . . . 12 4. JWE Header . . . . . . . . . . . . . . . . . . . . . . . . . . 12
4.1. Registered Header Parameter Names . . . . . . . . . . . . 12 4.1. Registered Header Parameter Names . . . . . . . . . . . . 13
4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 13 4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 13
4.1.2. "enc" (Encryption Algorithm) Header Parameter . . . . 13 4.1.2. "enc" (Encryption Algorithm) Header Parameter . . . . 13
4.1.3. "zip" (Compression Algorithm) Header Parameter . . . . 13 4.1.3. "zip" (Compression Algorithm) Header Parameter . . . . 13
4.1.4. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 14 4.1.4. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 14
4.1.5. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 14 4.1.5. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 14
4.1.6. "kid" (Key ID) Header Parameter . . . . . . . . . . . 14 4.1.6. "kid" (Key ID) Header Parameter . . . . . . . . . . . 14
4.1.7. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 14 4.1.7. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 14
4.1.8. "x5c" (X.509 Certificate Chain) Header Parameter . . . 14 4.1.8. "x5c" (X.509 Certificate Chain) Header Parameter . . . 15
4.1.9. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header 4.1.9. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header
Parameter . . . . . . . . . . . . . . . . . . . . . . 15 Parameter . . . . . . . . . . . . . . . . . . . . . . 15
4.1.10. "typ" (Type) Header Parameter . . . . . . . . . . . . 15 4.1.10. "typ" (Type) Header Parameter . . . . . . . . . . . . 15
4.1.11. "cty" (Content Type) Header Parameter . . . . . . . . 15 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 . . . . . . . . . . . . . . 15
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 . . . . . . . . . . . . . . . . . . 21
8. TLS Requirements . . . . . . . . . . . . . . . . . . . . . . . 24 8. TLS Requirements . . . . . . . . . . . . . . . . . . . . . . . 24
9. Distinguishing between JWS and JWE Objects . . . . . . . . . . 24 9. Distinguishing between JWS and JWE Objects . . . . . . . . . . 24
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25
10.1. JSON Web Signature and Encryption Header Parameters 10.1. JSON Web Signature and Encryption Header Parameters
Registration . . . . . . . . . . . . . . . . . . . . . . . 25 Registration . . . . . . . . . . . . . . . . . . . . . . . 25
10.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 25 10.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 25
11. Security Considerations . . . . . . . . . . . . . . . . . . . 27 11. Security Considerations . . . . . . . . . . . . . . . . . . . 27
12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 27 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 28
12.1. Normative References . . . . . . . . . . . . . . . . . . . 27 12.1. Normative References . . . . . . . . . . . . . . . . . . . 28
12.2. Informative References . . . . . . . . . . . . . . . . . . 28 12.2. Informative References . . . . . . . . . . . . . . . . . . 28
Appendix A. JWE Examples . . . . . . . . . . . . . . . . . . . . 29 Appendix A. JWE Examples . . . . . . . . . . . . . . . . . . . . 29
A.1. Example JWE using RSAES OAEP and AES GCM . . . . . . . . . 29 A.1. Example JWE using RSAES OAEP and AES GCM . . . . . . . . . 29
A.1.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 29 A.1.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 29
A.1.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 30 A.1.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 30
A.1.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 30 A.1.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 30
A.1.4. Initialization Vector . . . . . . . . . . . . . . . . 31 A.1.4. Initialization Vector . . . . . . . . . . . . . . . . 31
A.1.5. Additional Authenticated Data . . . . . . . . . . . . 31 A.1.5. Additional Authenticated Data . . . . . . . . . . . . 31
A.1.6. Content Encryption . . . . . . . . . . . . . . . . . . 31 A.1.6. Content Encryption . . . . . . . . . . . . . . . . . . 32
A.1.7. Complete Representation . . . . . . . . . . . . . . . 32 A.1.7. Complete Representation . . . . . . . . . . . . . . . 32
A.1.8. Validation . . . . . . . . . . . . . . . . . . . . . . 32 A.1.8. Validation . . . . . . . . . . . . . . . . . . . . . . 33
A.2. Example JWE using RSAES-PKCS1-V1_5 and A.2. Example JWE using RSAES-PKCS1-V1_5 and
AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 33 AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 33
A.2.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 33 A.2.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 33
A.2.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 33 A.2.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 34
A.2.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 33 A.2.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 34
A.2.4. Initialization Vector . . . . . . . . . . . . . . . . 35 A.2.4. Initialization Vector . . . . . . . . . . . . . . . . 35
A.2.5. Additional Authenticated Data . . . . . . . . . . . . 35 A.2.5. Additional Authenticated Data . . . . . . . . . . . . 35
A.2.6. Content Encryption . . . . . . . . . . . . . . . . . . 35 A.2.6. Content Encryption . . . . . . . . . . . . . . . . . . 35
A.2.7. Complete Representation . . . . . . . . . . . . . . . 36 A.2.7. Complete Representation . . . . . . . . . . . . . . . 36
A.2.8. Validation . . . . . . . . . . . . . . . . . . . . . . 36 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 . . . . . . . . . . . . . . . . . 36 AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 37
A.3.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 36 A.3.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 37
A.3.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 37 A.3.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 37
A.3.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 37 A.3.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 37
A.3.4. Initialization Vector . . . . . . . . . . . . . . . . 38 A.3.4. Initialization Vector . . . . . . . . . . . . . . . . 38
A.3.5. Additional Authenticated Data . . . . . . . . . . . . 38 A.3.5. Additional Authenticated Data . . . . . . . . . . . . 38
A.3.6. Content Encryption . . . . . . . . . . . . . . . . . . 38 A.3.6. Content Encryption . . . . . . . . . . . . . . . . . . 38
A.3.7. Complete Representation . . . . . . . . . . . . . . . 39 A.3.7. Complete Representation . . . . . . . . . . . . . . . 39
A.3.8. Validation . . . . . . . . . . . . . . . . . . . . . . 39 A.3.8. Validation . . . . . . . . . . . . . . . . . . . . . . 39
A.4. Example JWE using JWE JSON Serialization . . . . . . . . . 39 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 . . . . . . . . 40
A.4.2. JWE Protected Header . . . . . . . . . . . . . . . . . 40 A.4.2. JWE Protected Header . . . . . . . . . . . . . . . . . 40
A.4.3. JWE Unprotected Header . . . . . . . . . . . . . . . . 40 A.4.3. JWE Unprotected Header . . . . . . . . . . . . . . . . 41
A.4.4. Complete JWE Header Values . . . . . . . . . . . . . . 40 A.4.4. Complete JWE Header Values . . . . . . . . . . . . . . 41
A.4.5. Additional Authenticated Data . . . . . . . . . . . . 41 A.4.5. Additional Authenticated Data . . . . . . . . . . . . 41
A.4.6. Content Encryption . . . . . . . . . . . . . . . . . . 41 A.4.6. Content Encryption . . . . . . . . . . . . . . . . . . 41
A.4.7. Complete JWE JSON Serialization Representation . . . . 41 A.4.7. Complete JWE JSON Serialization Representation . . . . 42
Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation . . . . 42 Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation . . . . 42
B.1. Extract MAC_KEY and ENC_KEY from Key . . . . . . . . . . . 42 B.1. Extract MAC_KEY and ENC_KEY from Key . . . . . . . . . . . 43
B.2. Encrypt Plaintext to Create Ciphertext . . . . . . . . . . 43 B.2. Encrypt Plaintext to Create Ciphertext . . . . . . . . . . 43
B.3. 64 Bit Big Endian Representation of AAD Length . . . . . . 43 B.3. 64 Bit Big Endian Representation of AAD Length . . . . . . 44
B.4. Initialization Vector Value . . . . . . . . . . . . . . . 43 B.4. Initialization Vector Value . . . . . . . . . . . . . . . 44
B.5. Create Input to HMAC Computation . . . . . . . . . . . . . 44 B.5. Create Input to HMAC Computation . . . . . . . . . . . . . 44
B.6. Compute HMAC Value . . . . . . . . . . . . . . . . . . . . 44 B.6. Compute HMAC Value . . . . . . . . . . . . . . . . . . . . 44
B.7. Truncate HMAC Value to Create Authentication Tag . . . . . 44 B.7. Truncate HMAC Value to Create Authentication Tag . . . . . 44
Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 44 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 45
Appendix D. Document History . . . . . . . . . . . . . . . . . . 45 Appendix D. Document History . . . . . . . . . . . . . . . . . . 45
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 54 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) [I-D.ietf-json-rfc4627bis] based JavaScript Object Notation (JSON) [RFC7158] based data structures.
data structures. The JWE cryptographic mechanisms encrypt and The JWE cryptographic mechanisms encrypt and provide integrity
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
intended for space constrained environments such as HTTP intended for space constrained environments such as HTTP
Authorization headers and URI query parameters. The JWE JSON Authorization headers and URI query parameters. The JWE JSON
Serialization represents JWE objects as JSON objects and enables the Serialization represents JWE objects as JSON objects and enables the
same content to be encrypted to multiple parties. Both share the same content to be encrypted to multiple parties. Both share the
same cryptographic underpinnings. same cryptographic underpinnings.
Cryptographic algorithms and identifiers for use with this Cryptographic algorithms and identifiers for use with this
skipping to change at page 5, line 33 skipping to change at page 5, line 33
specification. Related digital signature and MAC capabilities are specification. Related digital signature and MAC capabilities are
described in the separate JSON Web Signature (JWS) [JWS] described in the separate JSON Web Signature (JWS) [JWS]
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", "NOT RECOMMENDED", "MAY", and
document are to be interpreted as described in Key words for use in "OPTIONAL" in this document are to be interpreted as described in Key
RFCs to Indicate Requirement Levels [RFC2119]. If these words are words for use in RFCs to Indicate Requirement Levels [RFC2119]. If
used without being spelled in uppercase then they are to be these words are used without being spelled in uppercase then they are
interpreted with their normal natural language meanings. to be interpreted with their normal natural language meanings.
BASE64URL(OCTETS) denotes the base64url encoding of OCTETS, per BASE64URL(OCTETS) denotes the base64url encoding of OCTETS, per
Section 2. Section 2.
UTF8(STRING) denotes the octets of the UTF-8 [RFC3629] representation UTF8(STRING) denotes the octets of the UTF-8 [RFC3629] representation
of STRING. of STRING.
ASCII(STRING) denotes the octets of the ASCII [USASCII] ASCII(STRING) denotes the octets of the ASCII [USASCII]
representation of STRING. representation of STRING.
skipping to change at page 6, line 14 skipping to change at page 6, line 14
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)", "Base64url Encoding", "Collision-Resistant Name", Signature (JWS)", "Base64url Encoding", "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)
and integrity protected message. A data structure representing an encrypted and integrity protected
message.
Authenticated Encryption with Associated Data (AEAD) An AEAD Authenticated Encryption with Associated Data (AEAD)
algorithm is one that encrypts the Plaintext, allows Additional An AEAD algorithm is one that encrypts the Plaintext, allows
Authenticated Data to be specified, and provides an integrated Additional Authenticated Data to be specified, and provides an
content integrity check over the Ciphertext and Additional integrated content integrity check over the Ciphertext and
Authenticated Data. AEAD algorithms accept two inputs, the Additional Authenticated Data. AEAD algorithms accept two inputs,
Plaintext and the Additional Authenticated Data value, and produce the Plaintext and the Additional Authenticated Data value, and
two outputs, the Ciphertext and the Authentication Tag value. AES produce two outputs, the Ciphertext and the Authentication Tag
Galois/Counter Mode (GCM) is one such algorithm. value. AES Galois/Counter Mode (GCM) is one such algorithm.
Plaintext The sequence of octets to be encrypted -- a.k.a., the Plaintext
message. The plaintext can contain an arbitrary sequence of The sequence of octets to be encrypted -- a.k.a., the message.
octets. The plaintext can contain an arbitrary sequence of octets.
Ciphertext An encrypted representation of the Plaintext. Ciphertext
An encrypted representation of the Plaintext.
Additional Authenticated Data (AAD) An input to an AEAD operation Additional Authenticated Data (AAD)
that is integrity protected but not encrypted. An input to an AEAD operation that is integrity protected but not
encrypted.
Authentication Tag An output of an AEAD operation that ensures the Authentication Tag
integrity of the Ciphertext and the Additional Authenticated Data. An output of an AEAD operation that ensures the integrity of the
Note that some algorithms may not use an Authentication Tag, in Ciphertext and the Additional Authenticated Data. Note that some
which case this value is the empty octet sequence. algorithms may not use an Authentication Tag, in which case this
value is the empty octet sequence.
Content Encryption Key (CEK) A symmetric key for the AEAD algorithm Content Encryption Key (CEK)
used to encrypt the Plaintext for the recipient to produce the A symmetric key for the AEAD algorithm used to encrypt the
Ciphertext and the Authentication Tag. Plaintext for the recipient to produce the Ciphertext and the
Authentication Tag.
JWE Header JSON object containing the parameters describing the JWE Header
cryptographic operations and parameters employed. The JWE Header JSON object containing the parameters describing the cryptographic
members are the union of the members of the JWE Protected Header, operations and parameters employed. The JWE Header members are
the JWE Shared Unprotected Header, and the JWE Per-Recipient the union of the members of the JWE Protected Header, the JWE
Unprotected Header. The members of the JWE Header are Header Shared Unprotected Header, and the JWE Per-Recipient Unprotected
Parameters. Header. The members of the JWE Header are Header Parameters.
JWE Encrypted Key Encrypted Content Encryption Key (CEK) value. JWE Encrypted Key
Note that for some algorithms, the JWE Encrypted Key value is Encrypted Content Encryption Key (CEK) value. Note that for some
specified as being the empty octet sequence. algorithms, the JWE Encrypted Key value is specified as being the
empty octet sequence.
JWE Initialization Vector Initialization Vector value used when JWE Initialization Vector
encrypting the plaintext. Note that some algorithms may not use Initialization Vector value used when encrypting the plaintext.
an Initialization Vector, in which case this value is the empty Note that some algorithms may not use an Initialization Vector, in
octet sequence. which case this value is the empty octet sequence.
JWE AAD Additional value to be integrity protected by the JWE AAD
authenticated encryption operation. This can only be present when Additional value to be integrity protected by the authenticated
using the JWE JSON Serialization. (Note that this can also be encryption operation. This can only be present when using the JWE
achieved when using either serialization by including the AAD JSON Serialization. (Note that this can also be achieved when
value as an integrity protected Header Parameter value, but at the using either serialization by including the AAD value as an
cost of the value being double base64url encoded.) integrity protected Header Parameter value, but at the cost of the
value being double base64url encoded.)
JWE Ciphertext Ciphertext value resulting from authenticated JWE Ciphertext
encryption of the plaintext with additional associated data. Ciphertext value resulting from authenticated encryption of the
plaintext with additional associated data.
JWE Authentication Tag Authentication Tag value resulting from JWE Authentication Tag
authenticated encryption of the plaintext with additional Authentication Tag value resulting from authenticated encryption
associated data. of the plaintext with additional associated data.
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 Protected Header JSON object that contains the JWE Header JWE Protected Header
Parameters that are integrity protected by the authenticated JSON object that contains the JWE Header Parameters that are
encryption operation. These parameters apply to all recipients of integrity protected by the authenticated encryption operation.
the JWE. For the JWE Compact Serialization, this comprises the These parameters apply to all recipients of the JWE. For the JWE
entire JWE Header. For the JWE JSON Serialization, this is one Compact Serialization, this comprises the entire JWE Header. For
component of the JWE Header. the JWE JSON Serialization, this is one component of the JWE
Header.
JWE Shared Unprotected Header JSON object that contains the JWE JWE Shared Unprotected Header
Header Parameters that apply to all recipients of the JWE that are JSON object that contains the JWE Header Parameters that apply to
all recipients of the JWE that are not integrity protected. This
can only be present when using the JWE JSON Serialization.
JWE Per-Recipient Unprotected Header
JSON object that contains JWE Header Parameters that apply to a
single recipient of the JWE. These Header Parameter values are
not integrity protected. This can only be present when using the not integrity protected. This can only be present when using the
JWE JSON Serialization. JWE JSON Serialization.
JWE Per-Recipient Unprotected Header JSON object that contains JWE JWE Compact Serialization
Header Parameters that apply to a single recipient of the JWE. A representation of the JWE as a compact, URL-safe string.
These Header Parameter values are not integrity protected. This
can only be present when using the JWE JSON Serialization.
JWE Compact Serialization A representation of the JWE as a compact,
URL-safe string.
JWE JSON Serialization A representation of the JWE as a JSON object. JWE JSON Serialization
The JWE JSON Serialization enables the same content to be A representation of the JWE as a JSON object. The JWE JSON
encrypted to multiple parties. This representation is neither Serialization enables the same content to be encrypted to multiple
optimized for compactness nor URL-safe. parties. This representation is neither optimized for compactness
nor URL-safe.
Key Management Mode A method of determining the Content Encryption Key Management Mode
Key (CEK) value to use. Each algorithm used for determining the A method of determining the Content Encryption Key (CEK) value to
CEK value uses a specific Key Management Mode. Key Management use. Each algorithm used for determining the CEK value uses a
Modes employed by this specification are Key Encryption, Key specific Key Management Mode. Key Management Modes employed by
Wrapping, Direct Key Agreement, Key Agreement with Key Wrapping, this specification are Key Encryption, Key Wrapping, Direct Key
and Direct Encryption. Agreement, Key Agreement with Key Wrapping, and Direct Encryption.
Key Encryption A Key Management Mode in which the Content Encryption Key Encryption
Key (CEK) value is encrypted to the intended recipient using an A Key Management Mode in which the Content Encryption Key (CEK)
asymmetric encryption algorithm. value is encrypted to the intended recipient using an asymmetric
encryption algorithm.
Key Wrapping A Key Management Mode in which the Content Encryption Key Wrapping
Key (CEK) value is encrypted to the intended recipient using a A Key Management Mode in which the Content Encryption Key (CEK)
symmetric key wrapping algorithm. value is encrypted to the intended recipient using a symmetric key
wrapping algorithm.
Direct Key Agreement A Key Management Mode in which a key agreement Direct Key Agreement
algorithm is used to agree upon the Content Encryption Key (CEK) A Key Management Mode in which a key agreement algorithm is used
value. to agree upon the Content Encryption Key (CEK) value.
Key Agreement with Key Wrapping A Key Management Mode in which a key Key Agreement with Key Wrapping
agreement algorithm is used to agree upon a symmetric key used to A Key Management Mode in which a key agreement algorithm is used
encrypt the Content Encryption Key (CEK) value to the intended to agree upon a symmetric key used to encrypt the Content
recipient using a symmetric key wrapping algorithm. Encryption Key (CEK) value to the intended recipient using a
symmetric key wrapping algorithm.
Direct Encryption A Key Management Mode in which the Content Direct Encryption
Encryption Key (CEK) value used is the secret symmetric key value A Key Management Mode in which the Content Encryption Key (CEK)
shared between the parties. value used is the secret symmetric key value shared between the
parties.
3. JSON Web Encryption (JWE) Overview 3. JSON Web Encryption (JWE) Overview
JWE represents encrypted content using JSON data structures and JWE represents encrypted content using JSON data structures and
base64url encoding. A JWE represents these logical values: base64url encoding. A JWE represents these logical values:
JWE Header JSON object containing the parameters describing the JWE Header
cryptographic operations and parameters employed. The JWE Header JSON object containing the parameters describing the cryptographic
members are the union of the members of the JWE Protected Header, operations and parameters employed. The JWE Header members are
the JWE Shared Unprotected Header, and the JWE Per-Recipient the union of the members of the JWE Protected Header, the JWE
Unprotected Header, as described below. Shared Unprotected Header, and the JWE Per-Recipient Unprotected
Header, as described below.
JWE Encrypted Key Encrypted Content Encryption Key (CEK) value. JWE Encrypted Key
Encrypted Content Encryption Key (CEK) value.
JWE Initialization Vector Initialization Vector value used when JWE Initialization Vector
encrypting the plaintext. Initialization Vector value used when encrypting the plaintext.
JWE AAD Additional value to be integrity protected by the JWE AAD
authenticated encryption operation. Additional value to be integrity protected by the authenticated
encryption operation.
JWE Ciphertext Ciphertext value resulting from authenticated JWE Ciphertext
encryption of the plaintext with additional associated data. Ciphertext value resulting from authenticated encryption of the
plaintext with additional associated data.
JWE Authentication Tag Authentication Tag value resulting from JWE Authentication Tag
authenticated encryption of the plaintext with additional Authentication Tag value resulting from authenticated encryption
associated data. of the plaintext with additional associated data.
The JWE Header represents the combination of these logical values: The JWE Header represents the combination of these logical values:
JWE Protected Header JSON object that contains the JWE Header JWE Protected Header
Parameters that are integrity protected by the authenticated JSON object that contains the JWE Header Parameters that are
encryption operation. These parameters apply to all recipients of integrity protected by the authenticated encryption operation.
the JWE. These parameters apply to all recipients of the JWE.
JWE Shared Unprotected Header JSON object that contains the JWE JWE Shared Unprotected Header
Header Parameters that apply to all recipients of the JWE that are JSON object that contains the JWE Header Parameters that apply to
not integrity protected. all recipients of the JWE that are not integrity protected.
JWE Per-Recipient Unprotected Header JSON object that contains JWE JWE Per-Recipient Unprotected Header
Header Parameters that apply to a single recipient of the JWE. JSON object that contains JWE Header Parameters that apply to a
These Header Parameter values are not integrity protected. single recipient of the JWE. These Header Parameter values are
not integrity protected.
This document defines two serializations for JWE objects: a compact, This document defines two serializations for JWE objects: a compact,
URL-safe serialization called the JWE Compact Serialization and a URL-safe serialization called the JWE Compact Serialization and a
JSON serialization called the JWE JSON Serialization. In both JSON serialization called the JWE JSON Serialization. In both
serializations, the JWE Protected Header, JWE Encrypted Key, JWE serializations, the JWE Protected Header, JWE Encrypted Key, JWE
Initialization Vector, JWE Ciphertext, and JWE Authentication Tag are Initialization Vector, JWE Ciphertext, and JWE Authentication Tag are
base64url encoded for transmission, since JSON lacks a way to base64url encoded for transmission, since JSON lacks a way to
directly represent octet sequences. When present, the JWE AAD is directly represent octet sequences. When present, the JWE AAD is
also base64url encoded for transmission. also base64url encoded for transmission.
skipping to change at page 18, line 46 skipping to change at page 19, line 8
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 octet sequence resulting from decoding the encoded JWE 3. The octet sequence resulting from decoding the encoded JWE
Protected Header MUST be a UTF-8 encoded representation of a Protected Header MUST be a UTF-8 encoded representation of a
completely valid JSON object conforming to completely valid JSON object conforming to [RFC7158], which is
[I-D.ietf-json-rfc4627bis], which is the JWE Protected Header. 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
skipping to change at page 21, line 38 skipping to change at page 22, line 5
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. Content using the JWE JSON Serialization can be encrypted to object. Content using the JWE JSON Serialization can be encrypted to
more than one recipient. This representation is neither optimized more than one recipient. This representation is neither optimized
for compactness nor URL-safe. for compactness nor URL-safe.
The following members are defined for use in top-level JSON objects The following members are defined for use in top-level JSON objects
used for the JWE JSON Serialization: used for the JWE JSON Serialization:
protected The "protected" member MUST be present and contain the protected
value BASE64URL(UTF8(JWE Protected Header)) when the JWE Protected The "protected" member MUST be present and contain the value
BASE64URL(UTF8(JWE Protected Header)) when the JWE Protected
Header value is non-empty; otherwise, it MUST be absent. These Header value is non-empty; otherwise, it MUST be absent. These
Header Parameter values are integrity protected. Header Parameter values are integrity protected.
unprotected The "unprotected" member MUST be present and contain the unprotected
value JWE Shared Unprotected Header when the JWE Shared The "unprotected" member MUST be present and contain the value JWE
Unprotected Header value is non-empty; otherwise, it MUST be Shared Unprotected Header when the JWE Shared Unprotected Header
absent. This value is represented as an unencoded JSON object, value is non-empty; otherwise, it MUST be absent. This value is
rather than as a string. These Header Parameter values are not represented as an unencoded JSON object, rather than as a string.
integrity protected. These Header Parameter values are not integrity protected.
iv The "iv" member MUST be present and contain the value iv
The "iv" member MUST be present and contain the value
BASE64URL(JWE Initialization Vector) when the JWE Initialization BASE64URL(JWE Initialization Vector) when the JWE Initialization
Vector value is non-empty; otherwise, it MUST be absent. Vector value is non-empty; otherwise, it MUST be absent.
aad The "aad" member MUST be present and contain the value aad
The "aad" member MUST be present and contain the value
BASE64URL(JWE AAD)) when the JWE AAD value is non-empty; BASE64URL(JWE AAD)) when the JWE AAD value is non-empty;
otherwise, it MUST be absent. A JWE AAD value can be included to otherwise, it MUST be absent. A JWE AAD value can be included to
supply a base64url encoded value to be integrity protected but not supply a base64url encoded value to be integrity protected but not
encrypted. encrypted.
ciphertext The "ciphertext" member MUST be present and contain the ciphertext
value BASE64URL(JWE Ciphertext). The "ciphertext" member MUST be present and contain the value
BASE64URL(JWE Ciphertext).
tag The "tag" member MUST be present and contain the value tag
The "tag" member MUST be present and contain the value
BASE64URL(JWE Authentication Tag) when the JWE Authentication Tag BASE64URL(JWE Authentication Tag) when the JWE Authentication Tag
value is non-empty; otherwise, it MUST be absent. value is non-empty; otherwise, it MUST be absent.
recipients The "recipients" member value MUST be an array of JSON recipients
objects. Each object contains information specific to a single The "recipients" member value MUST be an array of JSON objects.
recipient. This member MUST be present, even if the array Each object contains information specific to a single recipient.
elements contain only the empty JSON object "{}" (which can happen This member MUST be present, even if the array elements contain
when all Header Parameter values are shared between all recipients only the empty JSON object "{}" (which can happen when all Header
and when no encrypted key is used, such as when doing Direct Parameter values are shared between all recipients and when no
Encryption). encrypted key is used, such as when doing Direct Encryption).
The following members are defined for use in the JSON objects that The following members are defined for use in the JSON objects that
are elements of the "recipients" array: are elements of the "recipients" array:
header The "header" member MUST be present and contain the value JWE header
Per-Recipient Unprotected Header when the JWE Per-Recipient The "header" member MUST be present and contain the value JWE Per-
Recipient Unprotected Header when the JWE Per-Recipient
Unprotected Header value is non-empty; otherwise, it MUST be Unprotected Header value is non-empty; otherwise, it MUST be
absent. This value is represented as an unencoded JSON object, absent. This value is represented as an unencoded JSON object,
rather than as a string. These Header Parameter values are not rather than as a string. These Header Parameter values are not
integrity protected. integrity protected.
encrypted_key The "encrypted_key" member MUST be present and contain encrypted_key
the value BASE64URL(JWE Encrypted Key) when the JWE Encrypted Key The "encrypted_key" member MUST be present and contain the value
value is non-empty; otherwise, it MUST be absent. BASE64URL(JWE Encrypted Key) when the JWE Encrypted Key value is
non-empty; otherwise, it MUST be absent.
At least one of the "header", "protected", and "unprotected" members At least one of the "header", "protected", and "unprotected" members
MUST be present so that "alg" and "enc" Header Parameter values are MUST be present so that "alg" and "enc" Header Parameter values are
conveyed for each recipient computation. conveyed for each recipient computation.
Additional members can be present in both the JSON objects defined Additional members can be present in both the JSON objects defined
above; if not understood by implementations encountering them, they above; if not understood by implementations encountering them, they
MUST be ignored. MUST be ignored.
Some Header Parameters, including the "alg" parameter, can be shared Some Header Parameters, including the "alg" parameter, can be shared
skipping to change at page 27, line 39 skipping to change at page 28, line 4
the encrypted content is rejected. the encrypted content is rejected.
Additionally, this type of attack can be prevented by the use of "key Additionally, this type of attack can be prevented by the use of "key
tainting". This method restricts the use of a key to a limited set tainting". This method restricts the use of a key to a limited set
of algorithms -- usually one. This means, for instance, that if the of algorithms -- usually one. This means, for instance, that if the
key is marked as being for "RSA-OAEP" only, any attempt to decrypt a key is marked as being for "RSA-OAEP" only, any attempt to decrypt a
message using the "RSA1_5" algorithm with that key would fail message using the "RSA1_5" algorithm with that key would fail
immediately due to invalid use of the key. immediately due to invalid use of the key.
12. References 12. References
12.1. Normative 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.
[I-D.ietf-json-rfc4627bis]
Bray, T., "The JSON Data Interchange Format",
draft-ietf-json-rfc4627bis-10 (work in progress),
December 2013.
[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),
February 2014. March 2014.
[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),
February 2014. March 2014.
[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), February 2014. in progress), March 2014.
[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.
[RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S.,
Housley, R., and W. Polk, "Internet X.509 Public Key Housley, R., and W. Polk, "Internet X.509 Public Key
Infrastructure Certificate and Certificate Revocation List Infrastructure Certificate and Certificate Revocation List
(CRL) Profile", RFC 5280, May 2008. (CRL) Profile", RFC 5280, May 2008.
[RFC7158] Bray, T., "The JavaScript Object Notation (JSON) Data
Interchange Format", RFC 7158, March 2014.
[USASCII] American National Standards Institute, "Coded Character [USASCII] American National Standards Institute, "Coded Character
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.
12.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),
skipping to change at page 45, line 26 skipping to change at page 45, line 44
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 ]]
-21 -22
o Corrected RFC 2119 terminology usage.
o Replaced references to draft-ietf-json-rfc4627bis with RFC 7158.
-21
o Changed some references from being normative to informative, o Changed some references from being normative to informative,
addressing issue #90. addressing issue #90.
o Applied review comments to the JSON Serialization section, o Applied review comments to the JSON Serialization section,
addressing issue #178. addressing issue #178.
-20 -20
o Made terminology definitions more consistent, addressing issue o Made terminology definitions more consistent, addressing issue
#165. #165.
 End of changes. 73 change blocks. 
186 lines changed or deleted 216 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/