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)¶ 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
-
add_recipient
(key, header=None)¶ Encrypt the plaintext with the given key.
Parameters: - key – A JWK key 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 key is not a JWK object.
- 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.Raises: - InvalidJWEOperation – if the key is not a JWK object.
- InvalidJWEData – if the ciphertext can’t be decrypted or the object is otherwise malformed.
-
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 (optional). If a key is provided a idecryption 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 compat 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:
exceptions.Exception
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:
exceptions.Exception
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:
exceptions.Exception
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:
exceptions.Exception
Invalid CEK Key Length.
This exception is raised when a Content Encryption Key does not match the required lenght.