JSON Web Encryption (JWE)¶
The jwe Module implements the JSON Web Encryption standard. A JSON Web Encryption is represented by a JWE object, related utility classes and functions are availbale in this module too.
Classes¶
-
class
jwcrypto.jwe.
JWE
(plaintext=None, protected=None, unprotected=None, aad=None, algs=None, recipient=None, header=None)¶ Bases:
object
JSON Web Encryption object
This object represent a JWE token.
Creates a JWE token.
Parameters: - plaintext(bytes) – An arbitrary plaintext to be encrypted.
- protected – A JSON string with the protected header.
- unprotected – A JSON string with the shared unprotected header.
- aad(bytes) – Arbitrary additional authenticated data
- algs – An optional list of allowed algorithms
- recipient – An optional, default recipient key
- header – An optional header for the default recipient
-
add_recipient
(key, header=None)¶ Encrypt the plaintext with the given key.
Parameters: - key – A JWK key or password of appropriate type for the ‘alg’ provided in the JOSE Headers.
- header – A JSON string representing the per-recipient header.
Raises: - ValueError – if the plaintext is missing or not of type bytes.
- ValueError – if the compression type is unknown.
- InvalidJWAAlgorithm – if the ‘alg’ provided in the JOSE headers is missing or unknown, or otherwise not implemented.
-
decrypt
(key)¶ Decrypt a JWE token.
Parameters: - key – The (
jwcrypto.jwk.JWK
) decryption key. - key – A (
jwcrypto.jwk.JWK
) decryption key or a password string (optional).
Raises: - InvalidJWEOperation – if the key is not a JWK object.
- InvalidJWEData – if the ciphertext can’t be decrypted or the object is otherwise malformed.
- key – The (
-
deserialize
(raw_jwe, key=None)¶ Deserialize a JWE token.
NOTE: Destroys any current status and tries to import the raw JWE provided.
Parameters: - raw_jwe – a ‘raw’ JWE token (JSON Encoded or Compact notation) string.
- key – A (
jwcrypto.jwk.JWK
) decryption key or a password string (optional). If a key is provided a decryption step will be attempted after the object is successfully deserialized.
Raises: - InvalidJWEData – if the raw object is an invaid JWE token.
- InvalidJWEOperation – if the decryption fails.
-
serialize
(compact=False)¶ Serializes the object into a JWE token.
Parameters: compact(boolean) – if True generates the compact representation, otherwise generates a standard JSON format.
Raises: - InvalidJWEOperation – if the object cannot serialized with the compact representation and compact is True.
- InvalidJWEOperation – if no recipients have been added to the object.
-
allowed_algs
¶ Allowed algorithms.
The list of allowed algorithms. Can be changed by setting a list of algorithm names.
Variables¶
-
jwcrypto.jwe.
default_allowed_algs
= ['RSA1_5', 'RSA-OAEP', 'RSA-OAEP-256', 'A128KW', 'A192KW', 'A256KW', 'dir', 'ECDH-ES', 'ECDH-ES+A128KW', 'ECDH-ES+A192KW', 'ECDH-ES+A256KW', 'A128GCMKW', 'A192GCMKW', 'A256GCMKW', 'PBES2-HS256+A128KW', 'PBES2-HS384+A192KW', 'PBES2-HS512+A256KW', 'A128CBC-HS256', 'A192CBC-HS384', 'A256CBC-HS512', 'A128GCM', 'A192GCM', 'A256GCM']¶ Default allowed algorithms
Exceptions¶
-
class
jwcrypto.jwe.
InvalidJWEOperation
(message=None, exception=None)¶ Bases:
jwcrypto.common.JWException
Invalid JWS Object.
This exception is raised when a requested operation cannot be execute due to unsatisfied conditions.
-
class
jwcrypto.jwe.
InvalidJWEData
(message=None, exception=None)¶ Bases:
exceptions.Exception
Invalid JWE Object.
This exception is raised when the JWE Object is invalid and/or improperly formatted.
-
class
jwcrypto.jwe.
InvalidJWEKeyType
(expected, obtained)¶ Bases:
jwcrypto.common.JWException
Invalid JWE Key Type.
This exception is raised when the provided JWK Key does not match the type required by the sepcified algorithm.
-
class
jwcrypto.jwe.
InvalidJWEKeyLength
(expected, obtained)¶ Bases:
jwcrypto.common.JWException
Invalid JWE Key Length.
This exception is raised when the provided JWK Key does not match the lenght required by the sepcified algorithm.
-
class
jwcrypto.jwe.
InvalidCEKeyLength
(expected, obtained)¶ Bases:
jwcrypto.common.JWException
Invalid CEK Key Length.
This exception is raised when a Content Encryption Key does not match the required lenght.
Examples¶
- Encrypt a JWE token::
>>> from jwcrypto import jwk, jwe >>> from jwcrypto.common import json_encode >>> key = jwk.JWK.generate(kty='oct', size=256) >>> payload = "My Encrypted message" >>> jwetoken = jwe.JWE(payload.encode('utf-8'), json_encode({"alg": "A256KW", "enc": "A256CBC-HS512"})) >>> jwetoken.add_recipient(key) >>> enc = jwetoken.serialize()
- Decrypt a JWE token::
>>> jwetoken = jwe.JWE() >>> jwetoken.deserialize(enc) >>> jwetoken.decrypt(key) >>> payload = jwetoken.payload