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 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:
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 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: 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.

Registries

jwcrypto.jwe.JWEHeaderRegistry

Registry of valid header parameters