< draft-ietf-jose-json-web-encryption-19.txt   draft-ietf-jose-json-web-encryption-20.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: July 2, 2014 RTFM Expires: July 24, 2014 RTFM
J. Hildebrand J. Hildebrand
Cisco Cisco
December 29, 2013 January 20, 2014
JSON Web Encryption (JWE) JSON Web Encryption (JWE)
draft-ietf-jose-json-web-encryption-19 draft-ietf-jose-json-web-encryption-20
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 July 2, 2014. This Internet-Draft will expire on July 24, 2014.
Copyright Notice Copyright Notice
Copyright (c) 2013 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
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 . . . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . 8
3.1. Example JWE . . . . . . . . . . . . . . . . . . . . . . . 10 3.1. Example JWE . . . . . . . . . . . . . . . . . . . . . . . 10
4. JWE Header . . . . . . . . . . . . . . . . . . . . . . . . . . 11 4. JWE Header . . . . . . . . . . . . . . . . . . . . . . . . . . 12
4.1. Registered Header Parameter Names . . . . . . . . . . . . 12 4.1. Registered Header Parameter Names . . . . . . . . . . . . 12
4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 12 4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 12
4.1.2. "enc" (Encryption Algorithm) Header Parameter . . . . 12 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 . . . . . . . . . 13 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 . . . . . . . . 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 . . . 14
4.1.9. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header 4.1.9. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header
Parameter . . . . . . . . . . . . . . . . . . . . . . 14 Parameter . . . . . . . . . . . . . . . . . . . . . . 14
4.1.10. "typ" (Type) Header Parameter . . . . . . . . . . . . 14 4.1.10. "typ" (Type) Header Parameter . . . . . . . . . . . . 14
4.1.11. "cty" (Content Type) Header Parameter . . . . . . . . 14 4.1.11. "cty" (Content Type) Header Parameter . . . . . . . . 15
4.1.12. "crit" (Critical) Header Parameter . . . . . . . . . . 15 4.1.12. "crit" (Critical) Header Parameter . . . . . . . . . . 15
4.2. Public Header Parameter Names . . . . . . . . . . . . . . 15 4.2. Public Header Parameter Names . . . . . . . . . . . . . . 15
4.3. Private Header Parameter Names . . . . . . . . . . . . . . 15 4.3. Private Header Parameter Names . . . . . . . . . . . . . . 15
5. Producing and Consuming JWEs . . . . . . . . . . . . . . . . . 15 5. Producing and Consuming JWEs . . . . . . . . . . . . . . . . . 15
5.1. Message Encryption . . . . . . . . . . . . . . . . . . . . 15 5.1. Message Encryption . . . . . . . . . . . . . . . . . . . . 15
5.2. Message Decryption . . . . . . . . . . . . . . . . . . . . 17 5.2. Message Decryption . . . . . . . . . . . . . . . . . . . . 17
5.3. String Comparison Rules . . . . . . . . . . . . . . . . . 20 5.3. String Comparison Rules . . . . . . . . . . . . . . . . . 20
6. Key Identification . . . . . . . . . . . . . . . . . . . . . . 20 6. Key Identification . . . . . . . . . . . . . . . . . . . . . . 20
7. Serializations . . . . . . . . . . . . . . . . . . . . . . . . 20 7. Serializations . . . . . . . . . . . . . . . . . . . . . . . . 20
7.1. JWE Compact Serialization . . . . . . . . . . . . . . . . 20 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 . . . . . . . . . . . . . . . . . . . 26 11. Security Considerations . . . . . . . . . . . . . . . . . . . 27
12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 27 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 27
12.1. Normative References . . . . . . . . . . . . . . . . . . . 27 12.1. Normative References . . . . . . . . . . . . . . . . . . . 27
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) . . . . . . . . . . . . . 29 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 . . . . . . . . . . . . . . . . . . 31
A.1.7. Complete Representation . . . . . . . . . . . . . . . 32 A.1.7. Complete Representation . . . . . . . . . . . . . . . 32
A.1.8. Validation . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . 32 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) . . . . . . . . . . . . . 33
A.2.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 33 A.2.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 33
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 . . . . . . . . . . . . . . . . . 36
skipping to change at page 5, line 8 skipping to change at page 5, line 8
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 . . . . . . . . . . . . . . . . . . 44
Appendix D. Document History . . . . . . . . . . . . . . . . . . 45 Appendix D. Document History . . . . . . . . . . . . . . . . . . 45
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 53 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) [I-D.ietf-json-rfc4627bis] based
The JWE cryptographic mechanisms encrypt and provide integrity data structures. The JWE cryptographic mechanisms encrypt and
protection for an arbitrary sequence of octets. provide integrity 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 6, 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 object (or JSON objects, when using the JWE JSON JWE Header JSON object containing the parameters describing the
Serialization) that describes the encryption operations applied to cryptographic operations and parameters employed. The JWE Header
create the JWE Encrypted Key, the JWE Ciphertext, and the JWE members are the union of the members of the JWE Protected Header,
Authentication Tag. The members of the JWE Header object(s) are the JWE Shared Unprotected Header, and the JWE Per-Recipient
Header Parameters. Unprotected Header. The members of the JWE Header are Header
Parameters.
JWE Encrypted Key The result of encrypting the Content Encryption JWE Encrypted Key Encrypted Content Encryption Key (CEK) value.
Key (CEK) with the intended recipient's key using the specified Note that for some algorithms, the JWE Encrypted Key value is
algorithm. Note that for some algorithms, the JWE Encrypted Key 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 Initialization Vector value used when
Initialization Vector used when encrypting the Plaintext. Note encrypting the plaintext. Note that some algorithms may not use
that some algorithms may not use an Initialization Vector, in an Initialization Vector, in which case this value is the empty
which case this value is the empty octet sequence. octet sequence.
JWE Ciphertext A sequence of octets containing the Ciphertext for a JWE AAD Additional value to be integrity protected by the
JWE. authenticated encryption operation. This can only be present when
using the JWE JSON Serialization.
JWE Authentication Tag A sequence of octets containing the JWE Ciphertext Ciphertext value resulting from authenticated
Authentication Tag for a JWE. encryption of the plaintext with additional associated data.
JWE Protected Header A JSON object that contains the portion of the JWE Authentication Tag Authentication Tag value resulting from
JWE Header that is integrity protected. For the JWE Compact authenticated encryption of the plaintext with additional
Serialization, this comprises the entire JWE Header. For the JWE associated data.
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 Protected Header JSON object that contains the JWE Header
Parameters that are integrity protected by the authenticated
encryption operation. These parameters apply to all recipients of
the JWE. For the JWE Compact Serialization, this comprises the
entire JWE Header. For the JWE JSON Serialization, this is one
component of the JWE Header.
JWE Shared Unprotected Header 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.
This value is 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, JWE Compact Serialization A representation of the JWE as a compact,
URL-safe string. URL-safe string.
JWE JSON Serialization A representation of the JWE as a JSON object. JWE JSON Serialization A representation of the JWE as a JSON object.
Unlike the JWE Compact Serialization, the JWE JSON Serialization The JWE JSON Serialization enables the same content to be
enables the same content to be encrypted to multiple parties. encrypted to multiple parties. This representation is neither
This representation is neither compact nor URL-safe. optimized for compactness 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 8, line 34 skipping to change at page 9, line 5
cryptographic operations and parameters employed. The JWE Header cryptographic operations and parameters employed. The JWE Header
members are the union of the members of the JWE Protected Header, members are the union of the members of the JWE Protected Header,
the JWE Shared Unprotected Header, and the JWE Per-Recipient the JWE Shared Unprotected Header, and the JWE Per-Recipient
Unprotected Header, as described below. 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 Initialization Vector value used when
encrypting the plaintext. encrypting the plaintext.
JWE AAD Additional value to be integrity protected by the
authenticated encryption operation.
JWE Ciphertext Ciphertext value resulting from authenticated JWE Ciphertext Ciphertext value resulting from authenticated
encryption of the plaintext. encryption of the plaintext with additional associated data.
JWE Authentication Tag Authentication Tag value resulting from JWE Authentication Tag Authentication Tag value resulting from
authenticated encryption of the plaintext with additional authenticated encryption of the plaintext with additional
associated data. associated data.
JWE AAD Additional value to be integrity protected by the
authenticated encryption operation.
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 containing some of the parameters JWE Protected Header JSON object that contains the JWE Header
describing the cryptographic operations and parameters employed. Parameters that are integrity protected by the authenticated
These parameters apply to all recipients of the JWE. This value encryption operation. These parameters apply to all recipients of
is integrity protected in the digital signature or MAC calculation the JWE.
of the JWE Signature.
JWE Shared Unprotected Header JSON object containing some of the JWE Shared Unprotected Header JSON object that contains the JWE
parameters describing the cryptographic operations and parameters Header Parameters that apply to all recipients of the JWE that are
employed. These parameters apply to all recipients of the JWE. not integrity protected.
This value is not integrity protected in the authenticated
encryption operation.
JWE Per-Recipient Unprotected Header JSON object containing some of JWE Per-Recipient Unprotected Header JSON object that contains JWE
the parameters describing the cryptographic operations and Header Parameters that apply to a single recipient of the JWE.
parameters employed. These parameters apply to a single recipient This value is not integrity protected.
of the JWE. This value is not integrity protected in the
authenticated encryption operation.
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 28 skipping to change at page 18, line 32
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 RFC 4627 [RFC4627], completely valid JSON object conforming to
which is the JWE Protected Header. [I-D.ietf-json-rfc4627bis], 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
skipping to change at page 21, line 10 skipping to change at page 21, line 19
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 and it recipient is supported by the JWE Compact Serialization and it
provides no syntax to represent JWE Shared Unprotected Header, JWE provides no syntax to represent JWE Shared Unprotected Header, JWE
Per-Recipient Unprotected Header, or JWE AAD values. 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. Content using the JWE JSON Serialization can be encrypted to
JSON Serialization can be encrypted to more than one recipient. more than one recipient. This representation is neither optimized
for compactness nor URL-safe.
The representation is closely related to that used in the JWE Compact
Serialization, with the following differences for the JWE JSON
Serialization:
o Values in the JWE JSON Serialization are represented as members of The following members are defined for use in top-level JSON objects
a JSON object, rather than as base64url encoded strings separated used for the JWE JSON Serialization:
by period ('.') characters. (However binary values and values
that are integrity protected are still base64url encoded.)
o The value BASE64URL(UTF8(JWE Protected Header)), if non-empty, is protected The value BASE64URL(UTF8(JWE Protected Header)), if non-
stored in the "protected" member. empty, is stored in the "protected" member.
o The value BASE64URL(UTF8(JWE Shared Unprotected Header)), if non- unprotected The value BASE64URL(UTF8(JWE Shared Unprotected
empty, is stored in the "unprotected" member. Header)), if non-empty, is stored in the "unprotected" member. If
present, a JWE Shared Unprotected Header value is represented as
an unencoded JSON object, rather than as a string.
o The value BASE64URL(JWE Initialization Vector), if non-empty, is iv 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" aad A JWE AAD value can be included to supply a base64url encoded
member.
o The value BASE64URL(JWE Authentication Tag), if non-empty, is
stored in the "tag" member.
o The JWE can be encrypted to multiple recipients, rather than just
one. A JSON array in the "recipients" member is used to hold
values that are specific to a particular recipient, with one array
element per recipient represented. These array elements are JSON
objects.
o Each value BASE64URL(JWE Encrypted Key), if non-empty, is stored
in the "encrypted_key" member of a JSON object that is an element
of the "recipients" array.
o Some Header Parameter values, such as the "alg" value and
parameters used for selecting keys, can also differ for different
recipient computations. JWE Per-Recipient Unprotected Header
values, if present, are stored in the "header" members of the same
JSON objects that are elements of the "recipients" array.
o Some Header Parameters, including the "alg" parameter, can be
shared among all recipient computations. Header Parameters in the
JWE Protected Header and JWE Shared Unprotected Header values are
shared among all recipients.
o Not all Header Parameters are integrity protected. The shared
Header Parameters in the JWE Protected Header value member are
integrity protected, and are base64url encoded for transmission.
The per-recipient Header Parameters in the JWE Per-Recipient
Unprotected Header values and the shared Header Parameters in the
JWE Shared Unprotected Header value are not integrity protected.
These JSON objects containing Header Parameters that are not
integrity protected are not base64url encoded.
o The Header Parameter values used when creating or validating per-
recipient Ciphertext and Authentication Tag values are the union
of the three sets of Header Parameter values that may be present:
(1) the JWE Protected Header values represented in the "protected"
member, (2) the JWE Shared Unprotected Header values represented
in the "unprotected" member, and (3) the JWE Per-Recipient
Unprotected Header values represented in the "header" member of
the recipient's array element. The union of these sets of Header
Parameters comprises the JWE Header. The Header Parameter names
in the three locations MUST be disjoint.
o A JWE AAD value can be included to supply a base64url encoded
value to be integrity protected but not encrypted. (Note that value to be integrity protected but not encrypted. (Note that
this can also be achieved when using either serialization by this can also be achieved when using either serialization by
including the AAD value as a protected Header Parameter value, but including the AAD value as a protected Header Parameter value, but
at the cost of the value being double base64url encoded.) If a at the cost of the value being double base64url encoded.) If a
JWE AAD value is present, the value BASE64URL(JWE AAD)) is stored JWE AAD value is present, the value BASE64URL(JWE AAD)) is stored
in the "aad" member. in the "aad" member.
o The "recipients" array MUST always be present, even if the array ciphertext The value BASE64URL(JWE Ciphertext) is stored in the
elements contain only the empty JSON object "{}" (which can happen "ciphertext" member.
when all Header Parameter values are shared between all recipients
and when no encrypted key is used, such as when doing Direct
Encryption).
The syntax of a JWE using the JWE JSON Serialization is as follows: tag The value BASE64URL(JWE Authentication Tag), if non-empty, is
stored in the "tag" member.
{"protected":<integrity-protected shared header contents>", recipients A JSON array in the "recipients" member is used to hold
"unprotected":<non-integrity-protected shared header contents>", values that are specific to a particular recipient, with one array
"recipients":[ element per recipient represented. These array elements are JSON
{"header":"<per-recipient unprotected header 1 contents>", objects, as specified below.
"encrypted_key":"<encrypted key 1 contents>"},
...
{"header":"<per-recipient unprotected header N contents>",
"encrypted_key":"<encrypted key N contents>"}],
"aad":"<additional authenticated data contents>",
"iv":"<initialization vector contents>",
"ciphertext":"<ciphertext contents>",
"tag":"<authentication tag contents>"
}
Of these members, only the "ciphertext" member MUST be present. The The following members are defined for use in the JSON objects that
"iv", "tag", and "encrypted_key" members MUST be present when are elements of the "recipients" array:
header Each JWE Per-Recipient Unprotected Header value, if non-
empty, is stored in the "header" member. If present, a JWE Per-
Recipient Unprotected Header value is represented as an unencoded
JSON object, rather than as a string.
encrypted_key Each value BASE64URL(JWE Encrypted Key), if non-empty,
is stored in the "encrypted_key" member.
Of these members of the two JSON objects defined above, only the
"ciphertext" and "recipients" members MUST be present. The
"recipients" array MUST always be present, even if the array elements
contain only the empty JSON object "{}" (which can happen when all
Header Parameter values are shared between all recipients and when no
encrypted key is used, such as when doing Direct Encryption).
The "iv", "tag", and "encrypted_key" members MUST be present when
corresponding JWE Initialization Vector, JWE Authentication Tag, and corresponding JWE Initialization Vector, JWE Authentication Tag, and
JWE Encrypted Key values are non-empty. The "recipients" member MUST JWE Encrypted Key values are non-empty. The "recipients" member MUST
be present when any "header" or "encrypted_key" members are needed be present when any "header" or "encrypted_key" members are needed
for recipients. At least one of the "header", "protected", and for recipients. At least one of the "header", "protected", and
"unprotected" members MUST be present so that "alg" and "enc" Header "unprotected" members MUST be present so that "alg" and "enc" Header
Parameter values are conveyed for each recipient computation. Parameter values are conveyed for each recipient computation.
Additional members can be present in both the JSON objects defined
above; if not understood by implementations encountering them, they
MUST be ignored.
Some Header Parameters, including the "alg" parameter, can be shared
among all recipient computations. Header Parameters in the JWE
Protected Header and JWE Shared Unprotected Header values are shared
among all recipients.
Not all Header Parameters are integrity protected. The shared Header
Parameters in the JWE Protected Header value member are integrity
protected, and are base64url encoded for transmission. The per-
recipient Header Parameters in the JWE Per-Recipient Unprotected
Header values and the shared Header Parameters in the JWE Shared
Unprotected Header value are not integrity protected. These JSON
objects containing Header Parameters that are not integrity protected
are not base64url encoded.
The Header Parameter values used when creating or validating per-
recipient Ciphertext and Authentication Tag values are the union of
the three sets of Header Parameter values that may be present: (1)
the JWE Protected Header values represented in the "protected"
member, (2) the JWE Shared Unprotected Header values represented in
the "unprotected" member, and (3) the JWE Per-Recipient Unprotected
Header values represented in the "header" member of the recipient's
array element. The union of these sets of Header Parameters
comprises the JWE Header. The Header Parameter names in the three
locations MUST be disjoint.
The contents of the JWE Encrypted Key, JWE Initialization Vector, JWE The contents of the JWE Encrypted Key, JWE Initialization Vector, JWE
Ciphertext, and JWE Authentication Tag values are exactly as defined Ciphertext, and JWE Authentication Tag values are exactly as defined
in the rest of this specification. They are interpreted and in the rest of this specification. They are interpreted and
validated in the same manner, with each corresponding JWE Encrypted validated in the same manner, with each corresponding JWE Encrypted
Key, JWE Initialization Vector, JWE Ciphertext, JWE Authentication Key, JWE Initialization Vector, JWE Ciphertext, JWE Authentication
Tag, and set of Header Parameter values being created and validated Tag, and set of Header Parameter values being created and validated
together. The JWE Header values used are the union of the Header together. The JWE Header values used are the union of the Header
Parameters in the JWE Protected Header, JWE Shared Unprotected Parameters in the JWE Protected Header, JWE Shared Unprotected
Header, and corresponding JWE Per-Recipient Unprotected Header Header, and corresponding JWE Per-Recipient Unprotected Header
values, as described earlier. values, as described earlier.
skipping to change at page 24, line 4 skipping to change at page 23, line 39
Compact Serialization. This has the desirable property that each JWE Compact Serialization. This has the desirable property that each JWE
Encrypted Key value in the "recipients" array is identical to the Encrypted Key value in the "recipients" array is identical to the
value that would have been computed for the same parameter in the JWE value that would have been computed for the same parameter in the JWE
Compact Serialization. Likewise, the JWE Ciphertext and JWE Compact Serialization. Likewise, the JWE Ciphertext and JWE
Authentication Tag values match those produced for the JWE Compact Authentication Tag values match those produced for the JWE Compact
Serialization, provided that the JWE Protected Header value (which Serialization, provided that the JWE Protected Header value (which
represents the integrity-protected Header Parameter values) matches represents the integrity-protected Header Parameter values) matches
that used in the JWE Compact Serialization. that used in the JWE Compact Serialization.
All recipients use the same JWE Protected Header, JWE Initialization All recipients use the same JWE Protected Header, JWE Initialization
Vector, JWE Ciphertext, and JWE Authentication Tag values, resulting Vector, JWE Ciphertext, and JWE Authentication Tag values, when
in potentially significant space savings if the message is large. present, resulting in potentially significant space savings if the
Therefore, all Header Parameters that specify the treatment of the message is large. Therefore, all Header Parameters that specify the
Plaintext value MUST be the same for all recipients. This primarily treatment of the Plaintext value MUST be the same for all recipients.
means that the "enc" (encryption algorithm) Header Parameter value in This primarily means that the "enc" (encryption algorithm) Header
the JWE Header for each recipient and any parameters of that Parameter value in the JWE Header for each recipient and any
algorithm MUST be the same. parameters of that algorithm MUST be the same.
In summary, the syntax of a JWE using the JWE JSON Serialization is
as follows:
{"protected":"<integrity-protected shared header contents>",
"unprotected":<non-integrity-protected shared header contents>,
"recipients":[
{"header":<per-recipient unprotected header 1 contents>,
"encrypted_key":"<encrypted key 1 contents>"},
...
{"header":<per-recipient unprotected header N contents>,
"encrypted_key":"<encrypted key N contents>"}],
"aad":"<additional authenticated data contents>",
"iv":"<initialization vector contents>",
"ciphertext":"<ciphertext contents>",
"tag":"<authentication tag contents>"
}
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. TLS Requirements 8. TLS Requirements
The TLS requirements for this specification are the same as those The TLS requirements for this specification are the same as those
defined in Section 8 of [JWS]. defined in Section 8 of [JWS].
9. Distinguishing between JWS and JWE Objects 9. Distinguishing between JWS and JWE Objects
skipping to change at page 27, line 38 skipping to change at page 27, line 46
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),
December 2013. January 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),
December 2013. January 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), December 2013. in progress), January 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.
[RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness
Requirements for Security", BCP 106, RFC 4086, June 2005. Requirements for Security", BCP 106, RFC 4086, June 2005.
[RFC4627] Crockford, D., "The application/json Media Type for
JavaScript Object Notation (JSON)", RFC 4627, July 2006.
[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.
[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.
[W3C.CR-xmlenc-core1-20120313] [W3C.CR-xmlenc-core1-20120313]
skipping to change at page 45, 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 ]]
-20
o Made terminology definitions more consistent, addressing issue
#165.
o Restructured the JSON Serialization section to call out the
parameters used in hanging lists, addressing issue #178.
o Replaced references to RFC 4627 with draft-ietf-json-rfc4627bis,
addressing issue #90.
-19 -19
o Reordered the key selection parameters. o Reordered the key selection parameters.
-18 -18
o Updated the mandatory-to-implement (MTI) language to say that o Updated the mandatory-to-implement (MTI) language to say that
applications using this specification need to specify what applications using this specification need to specify what
serialization and serialization features are used for that serialization and serialization features are used for that
application, addressing issue #176. application, addressing issue #176.
 End of changes. 47 change blocks. 
158 lines changed or deleted 185 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/