Skip to main content

3. JSON Web Encryption (JWE) Overview

JWE represents encrypted content using JSON data structures and base64url encoding. These JSON data structures MAY contain whitespace and/or line breaks before or after any JSON values or structural characters, in accordance with Section 2 of RFC 7159 [RFC7159]. A JWE represents the following logical values (each of which is defined in Section 2):

  • JOSE Header
  • JWE Encrypted Key
  • JWE Initialization Vector
  • JWE AAD
  • JWE Ciphertext
  • JWE Authentication Tag

For a JWE, the JOSE Header members are the union of the members of these values (each of which is defined in Section 2):

  • JWE Protected Header
  • JWE Shared Unprotected Header
  • 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 JWEs: 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 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 is represented as a JSON object containing some or all of these eight members:

  • "protected", with the value BASE64URL(UTF8(JWE Protected Header))
  • "unprotected", with the value JWE Shared Unprotected Header
  • "header", with the value JWE Per-Recipient Unprotected Header
  • "encrypted_key", with the value BASE64URL(JWE Encrypted Key)
  • "iv", with the value BASE64URL(JWE Initialization Vector)
  • "ciphertext", with the value BASE64URL(JWE Ciphertext)
  • "tag", with the value BASE64URL(JWE Authentication Tag)
  • "aad", with the value BASE64URL(JWE AAD)

The six base64url-encoded result strings and the two unprotected JSON object values are 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:

  • The Content Encryption Key is encrypted to the recipient using the RSAES-OAEP [RFC3447] algorithm to produce the JWE Encrypted Key.
  • Authenticated encryption is performed on the plaintext using the AES GCM [AES] [NIST.800-38D] algorithm with a 256-bit key to produce the ciphertext and the Authentication Tag.
{"alg":"RSA-OAEP","enc":"A256GCM"}

Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected Header)) gives this value:

eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ

The remaining steps to finish creating this JWE are:

  • Generate a random Content Encryption Key (CEK).
  • Encrypt the CEK with the recipient's public key using the RSAES-OAEP algorithm to produce the JWE Encrypted Key.
  • Base64url encode the JWE Encrypted Key.
  • Generate a random JWE Initialization Vector.
  • Base64url encode the JWE Initialization Vector.
  • Let the Additional Authenticated Data encryption parameter be ASCII(BASE64URL(UTF8(JWE Protected Header))).
  • Perform authenticated encryption on the plaintext with the AES GCM algorithm using the CEK as the encryption key, the JWE Initialization Vector, and the Additional Authenticated Data value, requesting a 128-bit Authentication Tag output.
  • Base64url encode the ciphertext.
  • Base64url encode the Authentication Tag.
  • Assemble the final representation: The Compact Serialization of this result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE Authentication Tag).

The final result in this example (with line breaks for display purposes only) is:

eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ.
OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe
ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb
Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV
mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8
1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi
6UklfCpIMfIjf7iGdXKHzg.
48V1_ALb6US04U3b.
5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji
SdiwkIr3ajwQzaBtQD_A.
XFBoMYUZodetZdvTiFvSkQ

See Appendix A.1 for the complete details of computing this JWE. See Appendix A for additional examples, including examples using the JWE JSON Serialization in Sections A.4 and A.5.

Last updated on