JWE API

This part of the documentation covers all the interfaces of joserfc.jwe.

class joserfc.jwe.CompactEncryption(protected: Dict[str, Any], plaintext: bytes | None = None)

An object to represent the JWE Compact Serialization. It is usually returned by decrypt_compact method.

attach_recipient(key: OctKey | RSAKey | ECKey | OKPKey, header: Dict[str, Any] | None = None) None

Add a recipient to the JWE Compact Serialization. Please add a key that comply with the given “alg” value.

Parameters:
  • key – an instance of a key, e.g. (OctKey, RSAKey, ECKey, and etc)

  • header – extra header in dict

plaintext

the plaintext in bytes

protected

protected header in dict

class joserfc.jwe.FlattenedJSONEncryption(protected: Dict[str, Any], plaintext: bytes | None = None, unprotected: Dict[str, Any] | None = None, aad: bytes | None = None)

An object to represent the JWE Flattened JSON Serialization. It is used by encrypt_json, and it is usually returned by decrypt_json method.

To construct an object of FlattenedJSONEncryption:

protected = {"enc": "A128CBC-HS256"}
plaintext = b"hello world"
obj = FlattenedJSONEncryption(protected, plaintext)
# then add each recipient
obj.add_recipient({"alg": "A128KW"})
add_recipient(header: Dict[str, Any] | None = None, key: OctKey | RSAKey | ECKey | OKPKey | None = None) None

Add a recipient to the JWE JSON Serialization. Please add a key that comply with the “alg” to this recipient.

Parameters:
  • header – recipient’s own (unprotected) header

  • key – an instance of a key, e.g. (OctKey, RSAKey, ECKey, and etc)

flattened: ClassVar[bool] = True

represents if the object is in flatten syntax

class joserfc.jwe.GeneralJSONEncryption(protected: Dict[str, Any], plaintext: bytes | None = None, unprotected: Dict[str, Any] | None = None, aad: bytes | None = None)

An object to represent the JWE General JSON Serialization. It is used by encrypt_json, and it is usually returned by decrypt_json method.

To construct an object of GeneralJSONEncryption:

protected = {"enc": "A128CBC-HS256"}
plaintext = b"hello world"
obj = GeneralJSONEncryption(protected, plaintext)
# then add each recipient
obj.add_recipient({"alg": "A128KW"})
add_recipient(header: Dict[str, Any] | None = None, key: OctKey | RSAKey | ECKey | OKPKey | None = None) None

Add a recipient to the JWE JSON Serialization. Please add a key that comply with the “alg” to this recipient.

Parameters:
  • header – recipient’s own (unprotected) header

  • key – an instance of a key, e.g. (OctKey, RSAKey, ECKey, and etc)

flattened: ClassVar[bool] = False

represents if the object is in flatten syntax

class joserfc.jwe.JWERegistry(header_registry: Dict[str, HeaderParameter] | None = None, algorithms: list[str] | None = None, verify_all_recipients: bool = True, strict_check_header: bool = True)

A registry for JSON Web Encryption to keep all the supported algorithms. An instance of JWERegistry is usually used together with methods in joserfc.jwe.

Parameters:
  • header_registry – extra header parameters registry

  • algorithms – allowed algorithms to be used

  • verify_all_recipients – validating all recipients in a JSON serialization

  • strict_check_header – only allow header key in the registry to be used

check_header(header: Dict[str, Any], check_more: bool = False) None

Check and validate the fields in header part of a JWS object.

get_alg(name: str) JWEKeyEncryption | JWEKeyWrapping | JWEKeyAgreement | JWEDirectEncryption

Get the allowed (“alg”) algorithm instance of the given name.

Parameters:

name – value of the alg, e.g. ECDH-ES, A128KW

get_enc(name: str) JWEEncModel

Get the allowed (“enc”) algorithm instance of the given name.

Parameters:

name – value of the enc, e.g. A128CBC-HS256, A128GCM

get_zip(name: str) JWEZipModel

Get the allowed (“zip”) algorithm instance of the given name.

Parameters:

name – value of the zip, e.g. DEF

class joserfc.jwe.Recipient(parent: CompactEncryption | GeneralJSONEncryption | FlattenedJSONEncryption, header: Dict[str, Any] | None = None, recipient_key: KeyType | None = None)
joserfc.jwe.decrypt_compact(value: bytes | str, private_key: str | bytes | OctKey | RSAKey | ECKey | OKPKey | KeySet | Callable[[GuestProtocol], str | bytes | OctKey | RSAKey | ECKey | OKPKey | KeySet], algorithms: list[str] | None = None, registry: JWERegistry | None = None, sender_key: ECKey | OKPKey | KeySet | None = None) CompactEncryption

Extract and validate the JWE Compact Serialization (in string, or bytes) with the given key. An JWE Compact Serialization looks like:

line breaks for display purposes only
OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe
ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb
Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV
mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8
1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi
6UklfCpIMfIjf7iGdXKHzg
Parameters:
  • value – a string (or bytes) of the JWE Compact Serialization

  • private_key – a flexible private key to decrypt the serialization

  • algorithms – a list of allowed algorithms

  • registry – a JWERegistry to use

  • sender_key – only required when using ECDH-1PU

Returns:

object of the CompactEncryption

joserfc.jwe.decrypt_json(data: GeneralJSONSerialization | FlattenedJSONSerialization, private_key: str | bytes | OctKey | RSAKey | ECKey | OKPKey | KeySet | Callable[[GuestProtocol], str | bytes | OctKey | RSAKey | ECKey | OKPKey | KeySet], algorithms: list[str] | None = None, registry: JWERegistry | None = None, sender_key: ECKey | OKPKey | KeySet | None = None) GeneralJSONEncryption | FlattenedJSONEncryption

Decrypt the JWE JSON Serialization (in dict) to a GeneralJSONEncryption or FlattenedJSONEncryption object.

Parameters:
  • data – JWE JSON Serialization in dict

  • private_key – a flexible private key to decrypt the CEK

  • algorithms – a list of allowed algorithms

  • registry – a JWERegistry to use

  • sender_key – only required when using ECDH-1PU

Returns:

an instance of GeneralJSONEncryption or FlattenedJSONEncryption

joserfc.jwe.encrypt_compact(protected: Dict[str, Any], plaintext: bytes | str, public_key: str | bytes | OctKey | RSAKey | ECKey | OKPKey | KeySet | Callable[[GuestProtocol], str | bytes | OctKey | RSAKey | ECKey | OKPKey | KeySet], algorithms: list[str] | None = None, registry: JWERegistry | None = None, sender_key: ECKey | OKPKey | KeySet | None = None) str

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)
Parameters:
  • protected – protected header part of the JWE, in dict

  • plaintext – the content (message) to be encrypted

  • public_key – a public key used to encrypt the CEK

  • algorithms – a list of allowed algorithms

  • registry – a JWERegistry to use

  • sender_key – only required when using ECDH-1PU

Returns:

JWE Compact Serialization in bytes

joserfc.jwe.encrypt_json(obj: GeneralJSONEncryption, public_key: str | bytes | OctKey | RSAKey | ECKey | OKPKey | KeySet | Callable[[GuestProtocol], str | bytes | OctKey | RSAKey | ECKey | OKPKey | KeySet] | None, algorithms: list[str] | None = None, registry: JWERegistry | None = None, sender_key: ECKey | OKPKey | KeySet | None = None) GeneralJSONSerialization
joserfc.jwe.encrypt_json(obj: FlattenedJSONEncryption, public_key: str | bytes | OctKey | RSAKey | ECKey | OKPKey | KeySet | Callable[[GuestProtocol], str | bytes | OctKey | RSAKey | ECKey | OKPKey | KeySet] | None, algorithms: list[str] | None = None, registry: JWERegistry | None = None, sender_key: ECKey | OKPKey | KeySet | None = None) FlattenedJSONSerialization

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

When calling this method, developers MUST construct an instance of a GeneralJSONEncryption or FlattenedJSONEncryption object. Here is an example:

from joserfc.jwe import GeneralJSONEncryption

protected = {"enc": "A128CBC-HS256"}
plaintext = b"hello world"
header = {"jku": "https://server.example.com/keys.jwks"}  # optional shared header
obj = GeneralJSONEncryption(protected, plaintext, header)
# add the recipients
obj.add_recipient({"kid": "alice", "alg": "RSA1_5"})  # not configured a key
bob_key = OctKey.import_key("bob secret")
obj.add_recipient({"kid": "bob", "alg": "A128KW"}, bob_key)
Parameters:
  • obj – an instance of GeneralJSONEncryption or FlattenedJSONEncryption

  • public_key – a public key used to encrypt the CEK

  • algorithms – a list of allowed algorithms

  • registry – a JWERegistry to use

  • sender_key – only required when using ECDH-1PU

Returns:

JWE JSON Serialization in dict