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

Registries

jwcrypto.jwe.JWEHeaderRegistry

Registry of valid header parameters

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