Introduction
Signed tokens protect integrity but do not hide their payload. When claims contain information that intermediaries or browser users should not read, JSON Web Encryption provides confidentiality and integrity in a standardized token format.
JWE is used in financial integrations, identity protocols, encrypted API messages and nested tokens. The utily.tools JWE Manipulator exposes each compact segment and supports encryption or decryption with compatible keys for controlled debugging.
Key management plus authenticated encryption
A compact JWE has five Base64url segments: protected header, encrypted key, initialization vector, ciphertext and authentication tag. The protected header is visible but authenticated. The ciphertext contains the encrypted plaintext, and the tag detects modification.
The alg header identifies how the content-encryption key is established or wrapped. The enc header identifies the symmetric authenticated-encryption algorithm applied to the plaintext. This separation allows RSA-OAEP, ECDH-ES or direct symmetric keys to work with AES-GCM or AES-CBC-HMAC content encryption.
Technical foundations and behavior
Encryption creates or derives a content-encryption key, generates a unique IV, authenticates the encoded protected header as additional authenticated data and emits ciphertext plus tag. Decryption must authenticate before releasing plaintext.
Key-management algorithms
RSA-OAEP encrypts a randomly generated content key with an RSA public key. ECDH-ES derives key material from an ephemeral and recipient EC key agreement. In direct mode, the shared symmetric key is itself the content key, so the encrypted-key segment is empty.
AES-GCM requirements
GCM provides encryption and authentication together. Reusing an IV with the same key can catastrophically reveal relationships between plaintexts and undermine authentication, so IV generation must be unique and normally random.
Nested JWT and operational policy
A signed JWT may be encrypted as JWE so the recipient can verify origin after decryption. Applications must still validate algorithms, keys, claims and size limits, and should avoid detailed decryption errors that become cryptographic oracles.
Real-world applications
Confidential identity claims
An identity provider encrypts sensitive claims so only the relying party holding the private key can read them.
Partner API payloads
A sender encrypts a small structured message for a partner while retaining a portable standards-based envelope.
Debugging algorithm mismatch
Inspecting alg, enc and key type explains why an RSA key cannot decrypt an ECDH token or why an unsupported curve fails.
Standards and deeper technical reference
RFC 7516 and the five compact segments
JWE was standardized by the IETF JOSE working group in RFC 7516. Compact Serialization is protected-header.encrypted-key.iv.ciphertext.authentication-tag, with each value base64url-encoded. The protected header is authenticated as Additional Authenticated Data, so changing alg, enc or protected key identifiers invalidates the tag.
The content encryption key (CEK) encrypts the plaintext using the enc algorithm. The alg algorithm protects, derives or agrees upon that CEK. Keeping these roles separate supports multiple key-management models and, in JSON Serialization, multiple recipients sharing one encrypted payload.
| Segment | Contains | Validation concern |
|---|---|---|
| Protected header | UTF-8 JSON with alg, enc and optional parameters | Must be authenticated and all critical parameters understood |
| Encrypted key | Protected CEK, or empty for direct modes | Interpretation depends on alg |
| Initialization vector | Nonce or IV required by enc | Length must match the algorithm and uniqueness rules |
| Ciphertext | Encrypted plaintext | Length can leak information even when contents remain secret |
| Authentication tag | AEAD integrity result | Verify before releasing any plaintext |
Key-management algorithms versus content encryption
Common alg families include dir for direct symmetric keys, AES Key Wrap, RSA-OAEP, ECDH-ES key agreement, AES-GCM key wrap and PBES2 password-based wrapping. RSA1_5 remains registered for compatibility but RFC 8725 says to avoid RSA PKCS #1 v1.5 encryption and prefer OAEP. ECDH-ES requires validation of received public keys and careful ephemeral-key handling.
The enc values A128GCM and A256GCM use AES-GCM authenticated encryption. A128CBC-HS256 and A256CBC-HS512 compose AES-CBC with HMAC under precisely split key material. Never substitute plain CBC or perform decryption before tag verification. A nonce repeated with the same GCM key can destroy confidentiality and authentication.
Compact, flattened and general JSON serializations
Compact JWE supports one recipient and no separate unprotected header or external AAD field. Flattened JSON Serialization supports one recipient with richer header placement. General JSON Serialization supports multiple recipients, each with its own encrypted key and recipient header, while sharing ciphertext, IV and tag.
Only protected header parameters are integrity-protected. Security decisions such as alg and enc should be protected, and duplicated parameter names across protected, shared-unprotected and per-recipient headers must be rejected. Compression with zip=DEF can reveal secrets through ciphertext length when attacker-controlled and secret text are compressed together.
Safe decryption order
Select an expected application profile before processing; enforce serialization and algorithm allowlists; resolve only trusted keys; validate all key and IV lengths; recover or derive the CEK; authenticate the protected header and ciphertext; release plaintext only after the tag succeeds; then decompress if explicitly allowed and parse the nested content.
Nested sign-and-encrypt content requires validation of both layers. Decrypting a JWE does not authenticate the business issuer unless the selected key-management profile provides that assurance, and a nested JWS signature must not be skipped.
Primary specifications and references
- RFC 7516: JSON Web EncryptionIETF / RFC Editor
- RFC 7518: JSON Web AlgorithmsIETF / RFC Editor
- RFC 8725: JWT Best Current PracticesIETF / RFC Editor
- IANA JOSE algorithm registryInternet Assigned Numbers Authority
Conclusion
JWE combines key management and authenticated symmetric encryption in a compact, interoperable format. Its five segments expose the information needed for recipients while protecting the plaintext and detecting tampering.
I recommend JWE only when token-level encryption is genuinely required; TLS remains mandatory and simpler designs are easier to operate. Use the utily.tools JWE Manipulator in safe test scenarios, then read the JWT and certificate articles for the trust infrastructure around it.