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¶