JSON Web Signature (JWS)

The jws Module implements the JSON Web Signature standard. A JSON Web Signature is represented by a JWS object, related utility classes and functions are available in this module too.

Classes

class jwcrypto.jws.JWS(payload=None)

Bases: object

JSON Web Signature object

This object represent a JWS token.

Creates a JWS object.

Parameters:payload(bytes) – An arbitrary value (optional).
add_signature(key, alg=None, protected=None, header=None)

Adds a new signature to the object.

Parameters:
  • key – A (jwcrypto.jwk.JWK) key of appropriate for the “alg” provided.
  • alg – An optional algorithm name. If already provided as an element of the protected or unprotected header it can be safely omitted.
  • potected – The Protected Header (optional)
  • header – The Unprotected Header (optional)
Raises:
  • InvalidJWSObject – if no payload has been set on the object.
  • ValueError – if the key is not a JWK object.
  • ValueError – if the algorithm is missing or is not provided by one of the headers.
  • InvalidJWAAlgorithm – if the algorithm is not valid, is unknown or otherwise not yet implemented.
deserialize(raw_jws, key=None, alg=None)

Deserialize a JWS token.

NOTE: Destroys any current status and tries to import the raw JWS provided.

Parameters:
  • raw_jws – a ‘raw’ JWS token (JSON Encoded or Compact notation) string.
  • key – A (jwcrypto.jwk.JWK) verification key (optional). If a key is provided a verification step will be attempted after the object is successfully deserialized.
  • alg – The signing algorithm (optional). usually the algorithm is known as it is provided with the JOSE Headers of the token.
Raises:
  • InvalidJWSObject – if the raw object is an invaid JWS token.
  • InvalidJWSSignature – if the verification fails.
serialize(compact=False)

Serializes the object into a JWS token.

Parameters:

compact(boolean) – if True generates the compact representation, otherwise generates a standard JSON format.

Raises:
  • InvalidJWSOperation – if the object cannot serialized with the compact representation and compat is True.
  • InvalidJWSSignature – if no signature has been added to the object, or no valid signature can be found.
verify(key, alg=None)

Verifies a JWS token.

Parameters:
  • key – The (jwcrypto.jwk.JWK) verification key.
  • alg – The signing algorithm (optional). usually the algorithm is known as it is provided with the JOSE Headers of the token.
Raises:

InvalidJWSSignature – if the verification fails.

allowed_algs

Allowed algorithms.

The list of allowed algorithms. Can be changed by setting a list of algorithm names.

class jwcrypto.jws.JWSCore(alg, key, header, payload, algs=None)

Bases: object

The inner JWS Core object.

This object SHOULD NOT be used directly, the JWS object should be used instead as JWS perform necessary checks on the validity of the object and requested operations.

Core JWS token handling.

Parameters:
  • alg – The algorithm used to produce the signature. See RFC 7518
  • key – A (jwcrypto.jwk.JWK) key of appropriate type for the “alg” provided in the ‘protected’ json string.
  • header – A JSON string representing the protected header.
  • payload(bytes) – An arbitrary value
  • algs – An optional list of allowed algorithms
Raises:
  • ValueError – if the key is not a JWK object
  • InvalidJWAAlgorithm – if the algorithm is not valid, is unknown or otherwise not yet implemented.
sign()

Generates a signature

verify(signature)

Verifies a signature

Raises:InvalidJWSSignature – if the verification fails.

Variables

jwcrypto.jws.default_allowed_algs = ['HS256', 'HS384', 'HS512', 'RS256', 'RS384', 'RS512', 'ES256', 'ES384', 'ES512', 'PS256', 'PS384', 'PS512']

Default allowed algorithms

Exceptions

class jwcrypto.jws.InvalidJWSSignature(message=None, exception=None)

Bases: exceptions.Exception

Invalid JWS Signature.

This exception is raised when a signature cannot be validated.

class jwcrypto.jws.InvalidJWSObject(message=None, exception=None)

Bases: exceptions.Exception

Invalid JWS Object.

This exception is raised when the JWS Object is invalid and/or improperly formatted.

class jwcrypto.jws.InvalidJWSOperation(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.

Registries

jwcrypto.jws.JWSHeaderRegistry

Registry of valid header parameters