JSON Web Signature (JWS)

JSON Web Signatures (JWS) work similarly to the existing URL safe serializer but will emit headers according to draft-ietf-jose-json-web -signature.

from itsdangerous import JSONWebSignatureSerializer
s = JSONWebSignatureSerializer("secret-key")
s.dumps({"x": 42})
'eyJhbGciOiJIUzI1NiJ9.eyJ4Ijo0Mn0.ZdTn1YyGz9Yx5B5wNpWRL221G1WpVE5fPCPKNuc6UAo'

When loading the value back the header will not be returned by default like with the other serializers. However it is possible to also ask for the header by passing return_header=True. Custom header fields can be provided upon serialization:

s.dumps(0, header_fields={"v": 1})
'eyJhbGciOiJIUzI1NiIsInYiOjF9.MA.wT-RZI9YU06R919VBdAfTLn82_iIQD70J_j-3F4z_aM'
s.loads(
    "eyJhbGciOiJIUzI1NiIsInYiOjF9"
    ".MA.wT-RZI9YU06R919VBdAfTLn82_iIQD70J_j-3F4z_aM"
)
(0, {'alg': 'HS256', 'v': 1})

itsdangerous only provides HMAC SHA derivatives and the none algorithm at the moment and does not support the ECC based ones. The algorithm in the header is checked against the one of the serializer and on a mismatch a BadSignature exception is raised.

class itsdangerous.jws.JSONWebSignatureSerializer(secret_key, salt=None, serializer=None, serializer_kwargs=None, signer=None, signer_kwargs=None, algorithm_name=None)

This serializer implements JSON Web Signature (JWS) support. Only supports the JWS Compact Serialization.

default_algorithm = 'HS512'

The default algorithm to use for signature generation

default_serializer

alias of itsdangerous._json._CompactJSON

dump_payload(header, obj)

Dumps the encoded object. The return value is always bytes. If the internal serializer returns text, the value will be encoded as UTF-8.

dumps(obj, salt=None, header_fields=None)

Like Serializer.dumps() but creates a JSON Web Signature. It also allows for specifying additional fields to be included in the JWS header.

load_payload(payload, serializer=None, return_header=False)

Loads the encoded object. This function raises BadPayload if the payload is not valid. The serializer parameter can be used to override the serializer stored on the class. The encoded payload should always be bytes.

loads(s, salt=None, return_header=False)

Reverse of dumps(). If requested via return_header it will return a tuple of payload and header.

loads_unsafe(s, salt=None, return_header=False)

Like loads() but without verifying the signature. This is potentially very dangerous to use depending on how your serializer works. The return value is (signature_valid, payload) instead of just the payload. The first item will be a boolean that indicates if the signature is valid. This function never fails.

Use it for debugging only and if you know that your serializer module is not exploitable (for example, do not use it with a pickle serializer).

New in version 0.15.

make_signer(salt=None, algorithm=None)

Creates a new instance of the signer to be used. The default implementation uses the Signer base class.

class itsdangerous.jws.TimedJSONWebSignatureSerializer(secret_key, expires_in=None, **kwargs)

Works like the regular JSONWebSignatureSerializer but also records the time of the signing and can be used to expire signatures.

JWS currently does not specify this behavior but it mentions a possible extension like this in the spec. Expiry date is encoded into the header similar to what’s specified in draft-ietf-oauth -json-web-token.

loads(s, salt=None, return_header=False)

Reverse of dumps(). If requested via return_header it will return a tuple of payload and header.