# RFC7516: JSON Web Encryption

This section contains the generic implementation of RFC7516. Find how to use it in JWE Guide.

## API Reference

class authlib.jose.JsonWebEncryption(algorithms=None, private_headers=None)
  REGISTERED_HEADER_PARAMETER_NAMES = frozenset({'alg', 'crit', 'cty', 'enc', 'jku', 'jwk', 'kid', 'typ', 'x5c', 'x5t', 'x5t#S256', 'x5u', 'zip'})

    Registered Header Parameter Names defined by Section 4.1

  classmethod register_algorithm(algorithm)

    Register an algorithm for `alg` or `enc` or `zip` of JWE.

  serialize_compact(protected, payload, key, sender_key=None)

    Generate a JWE Compact Serialization.

    The JWE Compact Serialization represents encrypted content as a compact, URL-safe string. This string is:

        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 by the JWE Compact Serialization and it provides no syntax to represent JWE Shared Unprotected Header, JWE Per-Recipient Unprotected Header, or JWE AAD values.

    Parameters:

      - protected – A dict of protected header

      - payload – Payload (bytes or a value convertible to bytes)

      - key – Public key used to encrypt payload

      - sender_key – Sender’s private key in case JWEAlgorithmWithTagAwareKeyAgreement is used

    Returns:

      JWE compact serialization as bytes

  serialize_json(header_obj, payload, keys, sender_key=None)

    Generate a JWE JSON Serialization (in fully general syntax).

    The JWE JSON Serialization represents encrypted content as a JSON object. This representation is neither optimized for compactness nor URL safe.

    The following members are defined for use in top-level JSON objects used for the fully general JWE JSON Serialization syntax:

    protected

      The “protected” member MUST be present and contain the value BASE64URL(UTF8(JWE Protected Header)) when the JWE Protected Header value is non-empty; otherwise, it MUST be absent. These Header Parameter values are integrity protected.

    unprotected

      The “unprotected” member MUST be present and contain the value JWE Shared Unprotected Header when the JWE Shared Unprotected Header value is non-empty; otherwise, it MUST be absent. This value is represented as an unencoded JSON object, rather than as a string. These Header Parameter values are not integrity protected.

    iv

      The “iv” member MUST be present and contain the value BASE64URL(JWE Initialization Vector) when the JWE Initialization Vector value is non-empty; otherwise, it MUST be absent.

    aad

      The “aad” member MUST be present and contain the value BASE64URL(JWE AAD)) when the JWE AAD value is non-empty; otherwise, it MUST be absent. A JWE AAD value can be included to supply a base64url-encoded value to be integrity protected but not encrypted.

    ciphertext

      The “ciphertext” member MUST be present and contain the value BASE64URL(JWE Ciphertext).

    tag

      The “tag” member MUST be present and contain the value BASE64URL(JWE Authentication Tag) when the JWE Authentication Tag value is non-empty; otherwise, it MUST be absent.

    recipients

      The “recipients” member value MUST be an array of JSON objects. Each object contains information specific to a single recipient. This member MUST be present with exactly one array element per recipient, even if some or all of the array element values are the empty JSON object “{}” (which can happen when all Header Parameter values are shared between all recipients and when no encrypted key is used, such as when doing Direct Encryption).

    The following members are defined for use in the JSON objects that are elements of the “recipients” array:

    header

      The “header” member MUST be present and contain the value JWE Per- Recipient Unprotected Header when the JWE Per-Recipient Unprotected Header value is non-empty; otherwise, it MUST be absent. This value is represented as an unencoded JSON object, rather than as a string. These Header Parameter values are not integrity protected.

    encrypted_key

      The “encrypted_key” member MUST be present and contain the value BASE64URL(JWE Encrypted Key) when the JWE Encrypted Key value is non-empty; otherwise, it MUST be absent.

    This implementation assumes that “alg” and “enc” header fields are contained in the protected or shared unprotected header.

    Parameters:

      - header_obj – A dict of headers (in addition optionally contains JWE AAD)

      - payload – Payload (bytes or a value convertible to bytes)

      - keys – Public keys (or a single public key) used to encrypt payload

      - sender_key – Sender’s private key in case JWEAlgorithmWithTagAwareKeyAgreement is used

    Returns:

      JWE JSON serialization (in fully general syntax) as dict

    Example of header_obj:

        {
            "protected": {
                "alg": "ECDH-1PU+A128KW",
                "enc": "A256CBC-HS512",
                "apu": "QWxpY2U",
                "apv": "Qm9iIGFuZCBDaGFybGll",
            },
            "unprotected": {"jku": "https://alice.example.com/keys.jwks"},
            "recipients": [
                {"header": {"kid": "bob-key-2"}},
                {"header": {"kid": "2021-05-06"}},
            ],
            "aad": b"Authenticate me too.",
        }

  serialize(header, payload, key, sender_key=None)

    Generate a JWE Serialization.

    It will automatically generate a compact or JSON serialization depending on header argument. If header is a dict with “protected”, “unprotected” and/or “recipients” keys, it will call serialize_json, otherwise it will call serialize_compact.

    Parameters:

      - header – A dict of header(s)

      - payload – Payload (bytes or a value convertible to bytes)

      - key – Public key(s) used to encrypt payload

      - sender_key – Sender’s private key in case JWEAlgorithmWithTagAwareKeyAgreement is used

    Returns:

      JWE compact serialization as bytes or JWE JSON serialization as dict

  deserialize_compact(s, key, decode=None, sender_key=None)

    Extract JWE Compact Serialization.

    Parameters:

      - s – JWE Compact Serialization as bytes

      - key – Private key used to decrypt payload (optionally can be a tuple of kid and essentially key)

      - decode – Function to decode payload data

      - sender_key – Sender’s public key in case JWEAlgorithmWithTagAwareKeyAgreement is used

    Returns:

      dict with header and payload keys where header value is a dict containing protected header fields

  deserialize_json(obj, key, decode=None, sender_key=None)

    Extract JWE JSON Serialization.

    Parameters:

      - obj – JWE JSON Serialization as dict or str

      - key – Private key used to decrypt payload (optionally can be a tuple of kid and essentially key)

      - decode – Function to decode payload data

      - sender_key – Sender’s public key in case JWEAlgorithmWithTagAwareKeyAgreement is used

    Returns:

      dict with header and payload keys where header value is a dict containing protected, unprotected, recipients and/or aad keys

  deserialize(obj, key, decode=None, sender_key=None)

    Extract a JWE Serialization.

    It supports both compact and JSON serialization.

    Parameters:

      - obj – JWE compact serialization as bytes or JWE JSON serialization as dict or str

      - key – Private key used to decrypt payload (optionally can be a tuple of kid and essentially key)

      - decode – Function to decode payload data

      - sender_key – Sender’s public key in case JWEAlgorithmWithTagAwareKeyAgreement is used

    Returns:

      dict with header and payload keys

  static parse_json(obj)

    Parse JWE JSON Serialization.

    Parameters:

      obj – JWE JSON Serialization as str or dict

    Returns:

      Parsed JWE JSON Serialization as dict if obj is an str, or obj as is if obj is already a dict

class authlib.jose.JWEAlgorithm

  Interface for JWE algorithm conforming to RFC7518. JWA specification (RFC7518) SHOULD implement the algorithms for JWE with this base implementation.

class authlib.jose.JWEEncAlgorithm
  encrypt(msg, aad, iv, key)

    Encrypt the given “msg” text.

    Parameters:

      - msg – text to be encrypt in bytes

      - aad – additional authenticated data in bytes

      - iv – initialization vector in bytes

      - key – encrypted key in bytes

    Returns:

      (ciphertext, tag)

  decrypt(ciphertext, aad, iv, tag, key)

    Decrypt the given cipher text.

    Parameters:

      - ciphertext – ciphertext in bytes

      - aad – additional authenticated data in bytes

      - iv – initialization vector in bytes

      - tag – authentication tag in bytes

      - key – encrypted key in bytes

    Returns:

      message

class authlib.jose.JWEZipAlgorithm