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 available in this module too.
Classes¶
- class jwcrypto.jwe.JWE(plaintext=None, protected=None, unprotected=None, aad=None, algs=None, recipient=None, header=None, header_registry=None, flattened=True)¶
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
header_registry – Optional additions to the header registry
flattened – Use flattened serialization syntax (default True)
- 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 (jwcrypto.jwk.JWKSet
) that contains a key indexed by the ‘kid’ header or (deprecated) a string containing a password.
- Raises:
InvalidJWEOperation – if the key is not a JWK object.
InvalidJWEData – if the ciphertext can’t be decrypted or the object is otherwise malformed.
JWKeyNotFound – if key is a JWKSet and the key is not found.
- deserialize(raw_jwe, key=None)¶
Deserialize a JWE token.
NOTE: Destroys any current status and tries to import the raw JWE provided.
If a key is provided a decryption step will be attempted after the object is successfully deserialized.
- Parameters:
raw_jwe – a ‘raw’ JWE token (JSON Encoded or Compact notation) string.
key – A (
jwcrypto.jwk.JWK
) decryption key, or a (jwcrypto.jwk.JWKSet
) that contains a key indexed by the ‘kid’ header or (deprecated) a string containing a password (optional).
- Raises:
InvalidJWEData – if the raw object is an invalid JWE token.
InvalidJWEOperation – if the decryption fails.
- classmethod from_jose_token(token)¶
Creates a JWE object from a serialized JWE token.
- Parameters:
token – A string with the json or compat representation of the token.
- Raises:
InvalidJWEData – if the raw object is an invalid JWE token.
- Returns:
A JWE token
- Return type:
- 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 be serialized with the compact representation and compact is True.
InvalidJWEOperation – if no recipients have been added to the object.
- Returns:
A json formatted string or a compact representation string
- Return type:
str
- property 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 = ['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:
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:
JWException
Invalid JWE Object.
This exception is raised when the JWE Object is invalid and/or improperly formatted.
- class jwcrypto.jwe.InvalidJWEKeyType(expected, obtained)¶
Bases:
JWException
Invalid JWE Key Type.
This exception is raised when the provided JWK Key does not match the type required by the specified algorithm.
- class jwcrypto.jwe.InvalidJWEKeyLength(expected, obtained)¶
Bases:
JWException
Invalid JWE Key Length.
This exception is raised when the provided JWK Key does not match the length required by the specified algorithm.
- class jwcrypto.jwe.InvalidCEKeyLength(expected, obtained)¶
Bases:
JWException
Invalid CEK Key Length.
This exception is raised when a Content Encryption Key does not match the required length.
Registries¶
- jwcrypto.jwe.JWEHeaderRegistry¶
Registry of valid header parameters
Examples¶
Symmetric keys¶
- 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
Asymmetric keys¶
- Encrypt a JWE token::
>>> from jwcrypto import jwk, jwe >>> from jwcrypto.common import json_encode, json_decode >>> public_key = jwk.JWK() >>> private_key = jwk.JWK.generate(kty='RSA', size=2048) >>> public_key.import_key(**json_decode(private_key.export_public())) >>> payload = "My Encrypted message" >>> protected_header = { ... "alg": "RSA-OAEP-256", ... "enc": "A256CBC-HS512", ... "typ": "JWE", ... "kid": public_key.thumbprint(), ... } >>> jwetoken = jwe.JWE(payload.encode('utf-8'), ... recipient=public_key, ... protected=protected_header) >>> enc = jwetoken.serialize()
- Decrypt a JWE token::
>>> jwetoken = jwe.JWE() >>> jwetoken.deserialize(enc, key=private_key) >>> payload = jwetoken.payload