Signing With Timestamps

If you want to expire signatures you can use the TimestampSigner class which adds timestamp information and signs it. On unsigning you can validate that the timestamp is not older than a given age.

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=b'itsdangerous.Signer', sep=b'.', 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.

Parameters

  • secret_key (Union[Iterable[Union[str, bytes]], str, bytes]) –

  • salt (Optional[Union[str, bytes]]) –

  • sep (bytes) –

  • key_derivation (str) –

  • digest_method (Any) –

  • algorithm (itsdangerous.signer.SigningAlgorithm) –

get_timestamp()

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

Return type

int

sign(value)

Signs the given string and also attaches time information.

Parameters

value (Union[str, bytes]) –

Return type

bytes

timestamp_to_datetime(ts)

Convert the timestamp from get_timestamp() into an aware :class`datetime.datetime` in UTC.

Changelog

Changed in version 2.0: The timestamp is returned as a timezone-aware datetime in UTC rather than a naive datetime assumed to be UTC.

Parameters

ts (int) –

Return type

datetime.datetime

unsign(signed_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 an aware datetime.datetime object in UTC.

Changelog

Changed in version 2.0: The timestamp is returned as a timezone-aware datetime in UTC rather than a naive datetime assumed to be UTC.

Parameters

  • signed_value (Union[str, bytes]) –

  • max_age (Optional[int]) –

  • return_timestamp (bool) –

Return type

Union[Tuple[bytes, datetime.datetime], bytes]

validate(signed_value, max_age=None)

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

Parameters

  • signed_value (Union[str, bytes]) –

  • max_age (Optional[int]) –

Return type

bool

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.

Parameters
default_signer

alias of itsdangerous.timed.TimestampSigner

iter_unsigners(salt=None)

Iterates over all signers to be tried for unsigning. Starts with the configured signer, then constructs each signer specified in fallback_signers.

Parameters

salt (Optional[Union[str, bytes]]) –

Return type

Iterator[itsdangerous.timed.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.

Parameters

  • s (Union[str, bytes]) –

  • max_age (Optional[int]) –

  • return_timestamp (bool) –

  • salt (Optional[Union[str, bytes]]) –

Return type

Any

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

Changelog

New in version 0.15.

Parameters

  • s (Union[str, bytes]) –

  • max_age (Optional[int]) –

  • salt (Optional[Union[str, bytes]]) –

Return type

Tuple[bool, Any]