RFC 7516#

RFC7516 defines JSON Web Encryption (JWE), a specification for representing encrypted content using JSON-based data structures. It describes how to encrypt arbitrary payloads, including how keys are managed, how encryption parameters are represented, and how JWE objects are serialized.

Definition#

RFC 7516 specifies the complete framework for creating and decrypting JSON Web Encryption (JWE) objects. The specification defines:

JWE Header#

The JWE Header is a JSON object that specifies metadata describing how the payload is encrypted and how the Content Encryption Key (CEK) is managed. RFC 7516 defines a registry of header parameters, including:

  • alg — the key management algorithm used to encrypt or wrap the CEK (required)

  • enc — the content encryption algorithm used to protect the payload (required)

  • jwk / jku — a JSON Web Key or URL pointing to a key set

  • kid — a key identifier to help recipients locate the correct key

  • zip — indicates that the plaintext is compressed before encryption

  • apu / apv — agreement PartyU/PartyV info for ECDH-based algorithms

  • typ and cty — type and content-type hints

  • crit — critical header parameters that must be understood

In the compact serialization format, the header is Base64URL-encoded as the first segment of the JWE.

In JSON serialization, it may appear as either a protected or unprotected header, similar to JWS.

Compact Serialization#

The compact serialization format represents a JWE as a single, period-separated string consisting of five Base64URL-encoded parts:

<protected-header>.<encrypted-key>.<iv>.<ciphertext>.<tag>

Each part has a specific meaning:

  • protected-header — metadata describing algorithms and parameters

  • encrypted-key — the CEK encrypted or wrapped with the recipient's key

  • iv — initialization vector for the content encryption algorithm

  • ciphertext — the encrypted payload

  • tag — the authentication tag for AEAD algorithms

Compact serialization is designed for simple and compact transmission and supports exactly one recipient.

JSON Serialization#

The JSON serialization format expresses a JWE as a JSON object and supports more complex use cases than compact serialization. It is used when:

  • encrypting for multiple recipients

  • including per-recipient header parameters

  • debugging or inspecting encryption metadata

A JSON-serialized JWE typically includes the following fields:

  • protected — a Base64URL-encoded header shared across recipients

  • unprotected — an unprotected shared header (optional)

  • iv — the initialization vector

  • ciphertext — the encrypted payload

  • tag — the authentication tag

  • recipients — an array of recipient objects, each containing:

    • header — per-recipient unprotected header (optional)

    • encrypted_key — a CEK encrypted for that recipient

JSON serialization enables multi-recipient encrypted messages and greater flexibility than the compact format.

Implementation#

All features defined in RFC 7516 are fully implemented in joserfc.

Private modules#

The underlying implementation can be found in the private module joserfc/_rfc7516:

  • JWE algorithms base models

  • Compact Serialization: encryption and decryption

  • JSON Serialization: encryption and decryption

Public exports#

These internals are re-exported through the public API in joserfc.jwe. You should always use joserfc.jwe for creating, encrypting, decrypting, and validating JWEs, and avoid importing from the private module directly.