JOSE Working Group M. Jones
Internet-Draft Microsoft
Intended status: Standards Track J. Hildebrand
Expires: April 17, 2015 Cisco
October 14, 2014
JSON Web Encryption (JWE)
draft-ietf-jose-json-web-encryption-34
Abstract
JSON Web Encryption (JWE) represents encrypted content using
JavaScript Object Notation (JSON) based data structures.
Cryptographic algorithms and identifiers for use with this
specification are described in the separate JSON Web Algorithms (JWA)
specification and IANA registries defined by that specification.
Related digital signature and MAC capabilities are described in the
separate JSON Web Signature (JWS) specification.
Status of this Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on April 17, 2015.
Copyright Notice
Copyright (c) 2014 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
Jones & Hildebrand Expires April 17, 2015 [Page 1]
Internet-Draft JWE October 2014
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 5
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6
3. JSON Web Encryption (JWE) Overview . . . . . . . . . . . . . . 8
3.1. JWE Compact Serialization Overview . . . . . . . . . . . . 9
3.2. JWE JSON Serialization Overview . . . . . . . . . . . . . 9
3.3. Example JWE . . . . . . . . . . . . . . . . . . . . . . . 10
4. JOSE Header . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.1. Registered Header Parameter Names . . . . . . . . . . . . 11
4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 12
4.1.2. "enc" (Encryption Algorithm) Header Parameter . . . . 12
4.1.3. "zip" (Compression Algorithm) Header Parameter . . . . 12
4.1.4. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 13
4.1.5. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 13
4.1.6. "kid" (Key ID) Header Parameter . . . . . . . . . . . 13
4.1.7. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 13
4.1.8. "x5c" (X.509 Certificate Chain) Header Parameter . . . 13
4.1.9. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header
Parameter . . . . . . . . . . . . . . . . . . . . . . 14
4.1.10. "x5t#S256" (X.509 Certificate SHA-256 Thumbprint)
Header Parameter . . . . . . . . . . . . . . . . . . . 14
4.1.11. "typ" (Type) Header Parameter . . . . . . . . . . . . 14
4.1.12. "cty" (Content Type) Header Parameter . . . . . . . . 14
4.1.13. "crit" (Critical) Header Parameter . . . . . . . . . . 14
4.2. Public Header Parameter Names . . . . . . . . . . . . . . 14
4.3. Private Header Parameter Names . . . . . . . . . . . . . . 15
5. Producing and Consuming JWEs . . . . . . . . . . . . . . . . . 15
5.1. Message Encryption . . . . . . . . . . . . . . . . . . . . 15
5.2. Message Decryption . . . . . . . . . . . . . . . . . . . . 17
5.3. String Comparison Rules . . . . . . . . . . . . . . . . . 20
6. Key Identification . . . . . . . . . . . . . . . . . . . . . . 20
7. Serializations . . . . . . . . . . . . . . . . . . . . . . . . 20
7.1. JWE Compact Serialization . . . . . . . . . . . . . . . . 20
7.2. JWE JSON Serialization . . . . . . . . . . . . . . . . . . 21
8. TLS Requirements . . . . . . . . . . . . . . . . . . . . . . . 23
9. Distinguishing between JWS and JWE Objects . . . . . . . . . . 23
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24
10.1. JSON Web Signature and Encryption Header Parameters
Registration . . . . . . . . . . . . . . . . . . . . . . . 24
10.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 24
11. Security Considerations . . . . . . . . . . . . . . . . . . . 26
Jones & Hildebrand Expires April 17, 2015 [Page 2]
Internet-Draft JWE October 2014
11.1. Key Entropy and Random Values . . . . . . . . . . . . . . 26
11.2. Key Protection . . . . . . . . . . . . . . . . . . . . . . 27
11.3. Using Matching Algorithm Strengths . . . . . . . . . . . . 27
11.4. Adaptive Chosen-Ciphertext Attacks . . . . . . . . . . . . 27
11.5. Timing Attacks . . . . . . . . . . . . . . . . . . . . . . 27
12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 28
12.1. Normative References . . . . . . . . . . . . . . . . . . . 28
12.2. Informative References . . . . . . . . . . . . . . . . . . 28
Appendix A. JWE Examples . . . . . . . . . . . . . . . . . . . . 30
A.1. Example JWE using RSAES OAEP and AES GCM . . . . . . . . . 30
A.1.1. JOSE Header . . . . . . . . . . . . . . . . . . . . . 30
A.1.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 30
A.1.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 31
A.1.4. Initialization Vector . . . . . . . . . . . . . . . . 32
A.1.5. Additional Authenticated Data . . . . . . . . . . . . 32
A.1.6. Content Encryption . . . . . . . . . . . . . . . . . . 32
A.1.7. Complete Representation . . . . . . . . . . . . . . . 33
A.1.8. Validation . . . . . . . . . . . . . . . . . . . . . . 33
A.2. Example JWE using RSAES-PKCS1-V1_5 and
AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 33
A.2.1. JOSE Header . . . . . . . . . . . . . . . . . . . . . 34
A.2.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 34
A.2.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 34
A.2.4. Initialization Vector . . . . . . . . . . . . . . . . 36
A.2.5. Additional Authenticated Data . . . . . . . . . . . . 36
A.2.6. Content Encryption . . . . . . . . . . . . . . . . . . 36
A.2.7. Complete Representation . . . . . . . . . . . . . . . 37
A.2.8. Validation . . . . . . . . . . . . . . . . . . . . . . 37
A.3. Example JWE using AES Key Wrap and
AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 37
A.3.1. JOSE Header . . . . . . . . . . . . . . . . . . . . . 38
A.3.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 38
A.3.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 38
A.3.4. Initialization Vector . . . . . . . . . . . . . . . . 39
A.3.5. Additional Authenticated Data . . . . . . . . . . . . 39
A.3.6. Content Encryption . . . . . . . . . . . . . . . . . . 39
A.3.7. Complete Representation . . . . . . . . . . . . . . . 40
A.3.8. Validation . . . . . . . . . . . . . . . . . . . . . . 40
A.4. Example JWE using JWE JSON Serialization . . . . . . . . . 40
A.4.1. JWE Per-Recipient Unprotected Headers . . . . . . . . 41
A.4.2. JWE Protected Header . . . . . . . . . . . . . . . . . 41
A.4.3. JWE Unprotected Header . . . . . . . . . . . . . . . . 41
A.4.4. Complete JOSE Header Values . . . . . . . . . . . . . 41
A.4.5. Additional Authenticated Data . . . . . . . . . . . . 42
A.4.6. Content Encryption . . . . . . . . . . . . . . . . . . 42
A.4.7. Complete JWE JSON Serialization Representation . . . . 42
Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation . . . . 43
B.1. Extract MAC_KEY and ENC_KEY from Key . . . . . . . . . . . 43
Jones & Hildebrand Expires April 17, 2015 [Page 3]
Internet-Draft JWE October 2014
B.2. Encrypt Plaintext to Create Ciphertext . . . . . . . . . . 44
B.3. 64 Bit Big Endian Representation of AAD Length . . . . . . 44
B.4. Initialization Vector Value . . . . . . . . . . . . . . . 45
B.5. Create Input to HMAC Computation . . . . . . . . . . . . . 45
B.6. Compute HMAC Value . . . . . . . . . . . . . . . . . . . . 45
B.7. Truncate HMAC Value to Create Authentication Tag . . . . . 45
Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 45
Appendix D. Document History . . . . . . . . . . . . . . . . . . 46
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 57
Jones & Hildebrand Expires April 17, 2015 [Page 4]
Internet-Draft JWE October 2014
1. Introduction
JSON Web Encryption (JWE) represents encrypted content using
JavaScript Object Notation (JSON) [RFC7159] based data structures.
The JWE cryptographic mechanisms encrypt and provide integrity
protection for an arbitrary sequence of octets.
Two closely related serializations for JWE objects are defined. The
JWE Compact Serialization is a compact, URL-safe representation
intended for space constrained environments such as HTTP
Authorization headers and URI query parameters. The JWE JSON
Serialization represents JWE objects as JSON objects and enables the
same content to be encrypted to multiple parties. Both share the
same cryptographic underpinnings.
Cryptographic algorithms and identifiers for use with this
specification are described in the separate JSON Web Algorithms (JWA)
[JWA] specification and IANA registries defined by that
specification. Related digital signature and MAC capabilities are
described in the separate JSON Web Signature (JWS) [JWS]
specification.
Names defined by this specification are short because a core goal is
for the resulting representations to be compact.
1.1. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in Key
words for use in RFCs to Indicate Requirement Levels [RFC2119]. If
these words are used without being spelled in uppercase then they are
to be interpreted with their normal natural language meanings.
BASE64URL(OCTETS) denotes the base64url encoding of OCTETS, per
Section 2 of [JWS].
UTF8(STRING) denotes the octets of the UTF-8 [RFC3629] representation
of STRING.
ASCII(STRING) denotes the octets of the ASCII [USASCII]
representation of STRING.
The concatenation of two values A and B is denoted as A || B.
Jones & Hildebrand Expires April 17, 2015 [Page 5]
Internet-Draft JWE October 2014
2. Terminology
These terms defined by the JSON Web Signature (JWS) [JWS]
specification are incorporated into this specification: "JSON Web
Signature (JWS)", "Base64url Encoding", "Collision-Resistant Name",
"Header Parameter", "JOSE Header", and "StringOrURI".
These terms defined by the Internet Security Glossary, Version 2
[RFC4949] are incorporated into this specification: "Ciphertext" and
"Plaintext".
These terms are defined by this specification:
JSON Web Encryption (JWE)
A data structure representing an encrypted and integrity protected
message.
Authenticated Encryption with Associated Data (AEAD)
An AEAD algorithm is one that encrypts the Plaintext, allows
Additional Authenticated Data to be specified, and provides an
integrated content integrity check over the Ciphertext and
Additional Authenticated Data. AEAD algorithms accept two inputs,
the Plaintext and the Additional Authenticated Data value, and
produce two outputs, the Ciphertext and the Authentication Tag
value. AES Galois/Counter Mode (GCM) is one such algorithm.
Additional Authenticated Data (AAD)
An input to an AEAD operation that is integrity protected but not
encrypted.
Authentication Tag
An output of an AEAD operation that ensures the integrity of the
Ciphertext and the Additional Authenticated Data. Note that some
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 used to encrypt the
Plaintext to produce the Ciphertext and the Authentication Tag.
JWE Encrypted Key
Encrypted Content Encryption Key (CEK) value. Note that for some
algorithms, the JWE Encrypted Key value is specified as being the
empty octet sequence.
Jones & Hildebrand Expires April 17, 2015 [Page 6]
Internet-Draft JWE October 2014
JWE Initialization Vector
Initialization vector value used when encrypting the plaintext.
Note that some algorithms may not use an Initialization Vector, in
which case this value is the empty octet sequence.
JWE AAD
Additional value to be integrity protected by the authenticated
encryption operation. This can only be present when using the JWE
JSON Serialization. (Note that this can also be achieved when
using either serialization by including the AAD value as an
integrity protected Header Parameter value, but at the cost of the
value being double base64url encoded.)
JWE Ciphertext
Ciphertext value resulting from authenticated encryption of the
plaintext with additional authenticated data.
JWE Authentication Tag
Authentication Tag value resulting from authenticated encryption
of the plaintext with additional authenticated data.
JWE Protected Header
JSON object that contains the 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 JOSE Header. For
the JWE JSON Serialization, this is one component of the JOSE
Header.
JWE Shared Unprotected Header
JSON object that contains the 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 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 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. The JWE JSON
Serialization enables the same content to be encrypted to multiple
parties. This representation is neither optimized for compactness
nor URL-safe.
Jones & Hildebrand Expires April 17, 2015 [Page 7]
Internet-Draft JWE October 2014
Key Management Mode
A method of determining the Content Encryption Key (CEK) value to
use. Each algorithm used for determining the CEK value uses a
specific Key Management Mode. Key Management Modes employed by
this specification are Key Encryption, Key Wrapping, Direct Key
Agreement, Key Agreement with Key Wrapping, and Direct Encryption.
Key Encryption
A Key Management Mode in which the Content Encryption Key (CEK)
value is encrypted to the intended recipient using an asymmetric
encryption algorithm.
Key Wrapping
A Key Management Mode in which the Content Encryption Key (CEK)
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 algorithm is used
to agree upon the Content Encryption Key (CEK) value.
Key Agreement with Key Wrapping
A Key Management Mode in which a key agreement algorithm is used
to agree upon a symmetric key used to encrypt the Content
Encryption Key (CEK) value to the intended recipient using a
symmetric key wrapping algorithm.
Direct Encryption
A Key Management Mode in which the Content Encryption Key (CEK)
value used is the secret symmetric key value shared between the
parties.
3. JSON Web Encryption (JWE) Overview
JWE represents encrypted content using JSON data structures and
base64url encoding. These JSON data structures MAY contain white
space and/or line breaks. A JWE represents these logical values
(each of which is defined in Section 2):
o JOSE Header
o JWE Encrypted Key
o JWE Initialization Vector
o JWE AAD
o JWE Ciphertext
o JWE Authentication Tag
For a JWE object, the JOSE Header members are the union of the
Jones & Hildebrand Expires April 17, 2015 [Page 8]
Internet-Draft JWE October 2014
members of these values (each of which is defined in Section 2):
o JWE Protected Header
o JWE Shared Unprotected Header
o JWE Per-Recipient Unprotected Header
JWE utilizes authenticated encryption to ensure the confidentiality
and integrity of the Plaintext and the integrity of the JWE Protected
Header and the JWE AAD.
This document defines two serializations for JWE objects: a compact,
URL-safe serialization called the JWE Compact Serialization and a
JSON serialization called the JWE JSON Serialization. In both
serializations, the JWE Protected Header, JWE Encrypted Key, JWE
Initialization Vector, JWE Ciphertext, and JWE Authentication Tag are
base64url encoded, since JSON lacks a way to directly represent
arbitrary octet sequences. When present, the JWE AAD is also
base64url encoded.
3.1. JWE Compact Serialization Overview
In the JWE Compact Serialization, no JWE Shared Unprotected Header or
JWE Per-Recipient Unprotected Header are used. In this case, the
JOSE Header and the JWE Protected Header are the same.
In the JWE Compact Serialization, a JWE object is represented as the
concatenation:
BASE64URL(UTF8(JWE Protected Header)) || '.' ||
BASE64URL(JWE Encrypted Key) || '.' ||
BASE64URL(JWE Initialization Vector) || '.' ||
BASE64URL(JWE Ciphertext) || '.' ||
BASE64URL(JWE Authentication Tag)
See Section 7.1 for more information about the JWE Compact
Serialization.
3.2. JWE JSON Serialization Overview
In the JWE JSON Serialization, one or more of the JWE Protected
Header, JWE Shared Unprotected Header, and JWE Per-Recipient
Unprotected Header MUST be present. In this case, the members of the
JOSE Header are the union of the members of the JWE Protected Header,
JWE Shared Unprotected Header, and JWE Per-Recipient Unprotected
Header values that are present.
In the JWE JSON Serialization, a JWE object is represented as the
combination of these eight values,
Jones & Hildebrand Expires April 17, 2015 [Page 9]
Internet-Draft JWE October 2014
BASE64URL(UTF8(JWE Protected Header)),
JWE Shared Unprotected Header,
JWE Per-Recipient Unprotected Header,
BASE64URL(JWE Encrypted Key),
BASE64URL(JWE Initialization Vector),
BASE64URL(JWE Ciphertext),
BASE64URL(JWE Authentication Tag), and
BASE64URL(JWE AAD),
with the six base64url encoded result strings and the two unprotected
JSON object values being represented as members within a JSON object.
The inclusion of some of these values is OPTIONAL. The JWE JSON
Serialization can also encrypt the plaintext to multiple recipients.
See Section 7.2 for more information about the JWE JSON
Serialization.
3.3. Example JWE
This example encrypts the plaintext "The true sign of intelligence is
not knowledge but imagination." to the recipient.
The following example JWE Protected Header declares that:
o the Content Encryption Key is encrypted to the recipient using the
RSAES OAEP [RFC3447] algorithm to produce the JWE Encrypted Key
and
o authenticated encryption is performed on the Plaintext using the
AES GCM [AES,