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 (str | bytes | cabc.Iterable[str] | cabc.Iterable[bytes])

  • salt (str | bytes | None)

  • sep (bytes)

  • key_derivation (str)

  • digest_method (Any)

  • algorithm (SigningAlgorithm)

get_timestamp()

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

Return type:

int

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

sign(value)

Signs the given string and also attaches time information.

Parameters:

value (str | bytes)

Return type:

bytes

unsign(signed_value: str | bytes, max_age: int | None = None, return_timestamp: Literal[False] = False) → bytes
unsign(signed_value: str | bytes, max_age: int | None = None, return_timestamp: Literal[True] = True) → tuple[bytes, datetime]

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.

validate(signed_value, max_age=None)

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

Parameters:
Return type:

bool

class itsdangerous.timed.TimedSerializer(secret_key: str | bytes | Iterable[str] | Iterable[bytes], salt: str | bytes | None = b'itsdangerous', serializer: None | _PDataSerializer[str] = None, serializer_kwargs: dict[str, Any] | None = None, signer: type[Signer] | None = None, signer_kwargs: dict[str, Any] | None = None, fallback_signers: list[dict[str, Any] | tuple[type[Signer], dict[str, Any]] | type[Signer]] | None = None)
class itsdangerous.timed.TimedSerializer(secret_key: str | bytes | Iterable[str] | Iterable[bytes], salt: str | bytes | None, serializer: _PDataSerializer[bytes], serializer_kwargs: dict[str, Any] | None = None, signer: type[Signer] | None = None, signer_kwargs: dict[str, Any] | None = None, fallback_signers: list[dict[str, Any] | tuple[type[Signer], dict[str, Any]] | type[Signer]] | None = None)
class itsdangerous.timed.TimedSerializer(secret_key: str | bytes | Iterable[str] | Iterable[bytes], salt: str | bytes | None = b'itsdangerous', *, serializer: _PDataSerializer[bytes], serializer_kwargs: dict[str, Any] | None = None, signer: type[Signer] | None = None, signer_kwargs: dict[str, Any] | None = None, fallback_signers: list[dict[str, Any] | tuple[type[Signer], dict[str, Any]] | type[Signer]] | None = None)
class itsdangerous.timed.TimedSerializer(secret_key: str | bytes | Iterable[str] | Iterable[bytes], salt: str | bytes | None, serializer: Any, serializer_kwargs: dict[str, Any] | None = None, signer: type[Signer] | None = None, signer_kwargs: dict[str, Any] | None = None, fallback_signers: list[dict[str, Any] | tuple[type[Signer], dict[str, Any]] | type[Signer]] | None = None)
class itsdangerous.timed.TimedSerializer(secret_key: str | bytes | Iterable[str] | Iterable[bytes], salt: str | bytes | None = b'itsdangerous', *, serializer: Any, serializer_kwargs: dict[str, Any] | None = None, signer: type[Signer] | None = None, signer_kwargs: dict[str, Any] | None = None, fallback_signers: list[dict[str, Any] | tuple[type[Signer], dict[str, Any]] | type[Signer]] | None = None)

Uses TimestampSigner instead of the default Signer.

Parameters:
default_signer

alias of 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 (str | bytes | None)

Return type:

Iterator[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:
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

Added in version 0.15.

Parameters:
Return type:

tuple[bool, Any]