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)¶

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 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 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, 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
strict_check_header – only allow header key in the registry to be used

check_header(header: Dict[str, Any], check_more=False)¶: 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)¶

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

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

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

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