Signing With Timestamps

If you want to expire signatures you can use the TimestampSigner class which will adds timestamp information and signs it. On unsigning you can validate that the timestamp did not expire:

from itsdangerous import TimestampSigner
s = TimestampSigner('secret-key')
string = s.sign('foo')

s.unsign(string, max_age=5)
Traceback (most recent call last):
  ...
itsdangerous.exc.SignatureExpired: Signature age 15 > 5 seconds

class itsdangerous.timed.TimestampSigner(secret_key, salt=None, sep='.', key_derivation=None, digest_method=None, algorithm=None)

Works like the regular Signer but also records the time of the signing and can be used to expire signatures. The unsign() method can raise SignatureExpired if the unsigning failed because the signature is expired.

get_timestamp()

Returns the current timestamp. The function must return an integer.

sign(value)

Signs the given string and also attaches time information.

timestamp_to_datetime(ts)

Used to convert the timestamp from get_timestamp() into a datetime object.

unsign(value, max_age=None, return_timestamp=False)

Works like the regular Signer.unsign() but can also validate the time. See the base docstring of the class for the general behavior. If return_timestamp is True the timestamp of the signature will be returned as a naive datetime.datetime object in UTC.

validate(signed_value, max_age=None)

Only validates the given signed value. Returns True if the signature exists and is valid.

class itsdangerous.timed.TimedSerializer(secret_key, salt=b'itsdangerous', serializer=None, serializer_kwargs=None, signer=None, signer_kwargs=None, fallback_signers=None)

Uses TimestampSigner instead of the default Signer.

default_signer

alias of TimestampSigner

loads(s, max_age=None, return_timestamp=False, salt=None)

Reverse of dumps(), raises BadSignature if the signature validation fails. If a max_age is provided it will ensure the signature is not older than that time in seconds. In case the signature is outdated, SignatureExpired is raised. All arguments are forwarded to the signer’s unsign() method.

loads_unsafe(s, max_age=None, salt=None)

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.