JSON Web Encryption (JWE)
Extracted elements (29)
Header parameter names are intentionally kept short because a core design goal is compact representations. This is explicitly stated: 'Names defined by this specification are short because a core goal is for the resulting representations to be compact.'
The JWE JSON Serialization uses the same cryptographic computations as the JWE Compact Serialization: each per-recipient JWE Encrypted Key is identical to what would be computed in Compact Serialization for the same parameters, and all recipients share the same ciphertext and Authentication Tag, yielding significant space savings for large messages.
Two serializations are defined with different trade-offs: the JWE Compact Serialization is compact and URL-safe for use in HTTP headers and URI query parameters, while the JWE JSON Serialization is a full JSON object enabling encryption to multiple recipients, at the cost of compactness and URL-safety.
JWE implementations only need to implement the serialization features required by the applications they support. Applications using JWE must specify which serialization and features are used, such as single-recipient-only or multi-recipient JSON Serialization.
JWS and JWE objects can be distinguished by segment count in compact serialization (JWS has 3 segments/2 periods; JWE has 5 segments/4 periods), by JSON member presence ('payload' for JWS, 'ciphertext' for JWE), or by the 'alg' value (signature/MAC/none → JWS; key management algorithm → JWE). Presence of 'enc' member also signals JWE.
During decryption, if there is no recipient for which all decryption steps succeeded, the JWE MUST be considered invalid. In the multi-recipient case, the encrypted content for at least one recipient MUST successfully validate.
Even if a JWE can be successfully decrypted, unless the algorithms used are acceptable to the application, it SHOULD consider the JWE to be invalid. Algorithm acceptability is an application-level decision.
In multi-recipient JWE JSON Serialization, all Header Parameters that specify the treatment of the plaintext MUST be the same for all recipients. Specifically, the 'enc' Header Parameter value and any algorithm parameters MUST be identical across all per-recipient JOSE Headers.
The CEK MUST have a length equal to that required for the content encryption algorithm, both when generating it during encryption (step 2) and when decrypting it during decryption (step 9).
The 'enc' Header Parameter MUST identify an AEAD algorithm with a specified key length, and MUST be present in every JWE. Implementations MUST understand and process it; the encrypted content is not usable if the algorithm is unsupported.
The JOSE Header MUST NOT contain duplicate Header Parameter names. When using JWE JSON Serialization, the same Header Parameter name MUST NOT occur across the JWE Protected Header, JWE Shared Unprotected Header, and JWE Per-Recipient Unprotected Header — the three sets must be disjoint.
The JWE Authentication Tag MUST be validated during decryption, and the implementation MUST reject the input without emitting any decrypted output if the Authentication Tag is incorrect.
To mitigate timing attacks (per RFC 3218), the recipient MUST NOT distinguish between format, padding, and length errors of encrypted keys. Upon receiving an improperly formatted key, it is strongly recommended the recipient substitute a randomly generated CEK and proceed to the next step.
When using the JWE JSON Serialization, at least one of the 'header', 'protected', and 'unprotected' members MUST be present so that 'alg' and 'enc' Header Parameter values are conveyed for each recipient computation.
When 'zip' is used, it MUST occur only within the JWE Protected Header so that the compression algorithm selection is integrity protected by the authenticated encryption operation.
Five Key Management Modes are defined: Key Encryption (CEK encrypted with asymmetric algorithm), Key Wrapping (CEK encrypted with symmetric wrap), Direct Key Agreement (CEK agreed upon via key agreement), Key Agreement with Key Wrapping (agreed key wraps CEK), and Direct Encryption (shared symmetric key used directly as CEK).
JWE AAD (Additional Authenticated Data) is an extra value integrity-protected by the AEAD operation but not encrypted. It can only be present in the JWE JSON Serialization. The AAD encryption parameter is formed as ASCII(Encoded Protected Header) or, if JWE AAD is present, ASCII(Encoded Protected Header || '.' || BASE64URL(JWE AAD)).
The 'alg' (Algorithm) Header Parameter identifies the cryptographic algorithm used to encrypt or determine the value of the Content Encryption Key (CEK). If the 'alg' value does not represent a supported algorithm or the recipient lacks the appropriate key, the encrypted content is not usable.
The Content Encryption Key (CEK) is a symmetric key for the AEAD algorithm used to encrypt the plaintext. For Key Encryption, Key Wrapping, and Key Agreement with Key Wrapping modes, the CEK is randomly generated; for Direct Encryption, the CEK is the shared symmetric key itself.
The 'enc' (Encryption Algorithm) Header Parameter identifies the AEAD content encryption algorithm used to produce the ciphertext and Authentication Tag from the plaintext. It MUST be an AEAD algorithm with a specified key length; this parameter MUST be present and MUST be understood and processed by implementations.
The 'zip' (Compression Algorithm) Header Parameter specifies an algorithm applied to the plaintext before encryption. The value 'DEF' denotes DEFLATE compression. When used, 'zip' MUST occur only within the JWE Protected Header so it is integrity protected. Use is OPTIONAL but MUST be understood and processed.
RFC 7516 registers JWE-specific Header Parameter names ('alg', 'enc', 'zip', 'jku', 'jwk', 'kid', 'x5u', 'x5c', 'x5t', 'x5t#S256', 'typ', 'cty', 'crit') in the IANA 'JSON Web Signature and Encryption Header Parameters' registry established by RFC 7515 (JWS).
Algorithms of matching strengths should be used together. When AES Key Wrap is used, the same key size should be used for AES GCM. If key encryption and content encryption algorithms differ, the effective security is determined by the weaker algorithm.
Implementations performing encryption must protect the key encryption key and the Content Encryption Key. Compromise of the key encryption key may result in disclosure of all content protected with that key; compromise of the CEK may expose the associated encrypted content.
JWE implementations must guard against adaptive chosen-ciphertext attacks. All formatting errors related to CEK, AAD, or ciphertext MUST be reported as a single unified error to prevent oracle attacks. Restricting a key to a single algorithm (e.g., 'RSA-OAEP' only) prevents downgrade attacks that substitute 'RSA1_5'.
Random values must be cryptographically strong for CEKs and Initialization Vectors. CEK and IV randomness quality directly affect the security of encrypted content; RFC 4086 guidance on generating random values applies.
The Flattened JWE JSON Serialization optimizes the general syntax for single-recipient use by removing the 'recipients' array and placing 'header' and 'encrypted_key' directly at the top level alongside 'ciphertext'. The 'recipients' member MUST NOT be present in this form.
The General JWE JSON Serialization is a JSON object with members: 'protected' (BASE64URL of JWE Protected Header), 'unprotected' (JWE Shared Unprotected Header), 'recipients' (array with per-recipient 'header' and 'encrypted_key'), 'iv', 'aad', 'ciphertext', and 'tag'. All base64url-encoded fields use their respective JWE component values.
The JWE Compact Serialization encodes a JWE as five base64url-encoded segments separated by four period characters: BASE64URL(UTF8(JWE Protected Header)) || '.' || BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE Authentication Tag). Only one recipient is supported and no unprotected headers or AAD can be represented.