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 bydecrypt_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 bydecrypt_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 injoserfc.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:
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
orFlattenedJSONEncryption
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
orFlattenedJSONEncryption
- 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
orFlattenedJSONEncryption
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
orFlattenedJSONEncryption
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