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, header_registry=None)

Bases: object

JSON Web Signature object

This object represent a JWS token.

Creates a JWS object.

Parameters:

  • payload(bytes) – An arbitrary value (optional).

  • header_registry – Optional additions to the header registry

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.

  • protected – The Protected Header (optional)

  • header – The Unprotected Header (optional)

Raises:

  • InvalidJWSObject – if invalid headers are provided.

  • ValueError – if the key is not a (jwcrypto.jwk.JWK)

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

If a key is provided a verification step will be attempted after the object is successfully deserialized.

Parameters:

  • raw_jws – a ‘raw’ JWS token (JSON Encoded or Compact notation) string.

  • key – A (jwcrypto.jwk.JWK) verification or a (jwcrypto.jwk.JWKSet) that contains a key indexed by the ‘kid’ header (optional).

  • alg – The signing algorithm (optional). Usually the algorithm is known as it is provided with the JOSE Headers of the token.

Raises:
classmethod from_jose_token(token)

Creates a JWS object from a serialized JWS token.

Parameters:

token – A string with the json or compat representation of the token.

Raises:

InvalidJWSObject – if the raw object is an invalid JWS token.

Returns:

A JWS token

Return type:

JWS

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 compact is True.

  • InvalidJWSSignature – if no signature has been added to the object, or no valid signature can be found.

Returns:

A json formatted string or a compact representation string

Return type:

str

verify(key, alg=None, detached_payload=None)

Verifies a JWS token.

Parameters:

  • key – A (jwcrypto.jwk.JWK) verification or a (jwcrypto.jwk.JWKSet) that contains a key indexed by the ‘kid’ header.

  • alg – The signing algorithm (optional). Usually the algorithm is known as it is provided with the JOSE Headers of the token.

  • detached_payload – A detached payload to verify the signature against. Only valid for tokens that are not carrying a payload.

Raises:
property 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) verification or a (jwcrypto.jwk.JWKSet) that contains a key indexed by the ‘kid’ header. A JWKSet is allowed only for verification operations.

  • header – A JSON string representing the protected header.

  • payload(bytes) – An arbitrary value

  • algs – An optional list of allowed algorithms

Raises:
sign()

Generates a signature

verify(signature)

Verifies a signature

Raises:

InvalidJWSSignature – if the verification fails.

Returns:

Returns True or an Exception

Return type:

bool

Variables

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

Default allowed algorithms

Exceptions

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

Bases: JWException

Invalid JWS Signature.

This exception is raised when a signature cannot be validated.

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

Bases: JWException

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

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

Examples

Sign a JWS token::
>>> from jwcrypto import jwk, jws
>>> from jwcrypto.common import json_encode
>>> key = jwk.JWK.generate(kty='oct', size=256)
>>> payload = "My Integrity protected message"
>>> jwstoken = jws.JWS(payload.encode('utf-8'))
>>> jwstoken.add_signature(key, None,
...                        json_encode({"alg": "HS256"}),
...                        json_encode({"kid": key.thumbprint()}))
>>> sig = jwstoken.serialize()
Verify a JWS token::
>>> jwstoken = jws.JWS()
>>> jwstoken.deserialize(sig)
>>> jwstoken.verify(key)
>>> payload = jwstoken.payload