Signing Interface

The most basic interface is the signing interface. The Signer class can be used to attach a signature to a specific string:

from itsdangerous import Signer
s = Signer("secret-key")
s.sign("my string")
b'my string.wh6tMHxLgJqB6oY1uT73iMlyrOA'

The signature is appended to the string, separated by a dot. To validate the string, use the unsign() method:

s.unsign(b"my string.wh6tMHxLgJqB6oY1uT73iMlyrOA")
b'my string'

If unicode strings are provided, an implicit encoding to UTF-8 happens. However after unsigning you won’t be able to tell if it was unicode or a bytestring.

If the value is changed, the signature will no longer match, and unsigning will raise a BadSignature exception:

s.unsign(b"different string.wh6tMHxLgJqB6oY1uT73iMlyrOA")
Traceback (most recent call last):
  ...
BadSignature: Signature does not match

To record and validate the age of a signature, see Signing With Timestamps.

class itsdangerous.signer.Signer(secret_key, salt=b'itsdangerous.Signer', sep=b'.', key_derivation=None, digest_method=None, algorithm=None)

A signer securely signs bytes, then unsigns them to verify that the value hasn’t been changed.

The secret key should be a random string of bytes and should not be saved to code or version control. Different salts should be used to distinguish signing in different contexts. See General Concepts for information about the security of the secret key and salt.

Parameters

  • secret_key (Union[Iterable[Union[str, bytes]], str, bytes]) – The secret key to sign and verify with. Can be a list of keys, oldest to newest, to support key rotation.

  • salt (Optional[Union[str, bytes]]) – Extra key to combine with secret_key to distinguish signatures in different contexts.

  • sep (Union[str, bytes]) – Separator between the signature and value.

  • key_derivation (Optional[str]) – How to derive the signing key from the secret key and salt. Possible values are concat, django-concat, or hmac. Defaults to default_key_derivation, which defaults to django-concat.

  • digest_method (Optional[Any]) – Hash function to use when generating the HMAC signature. Defaults to default_digest_method, which defaults to hashlib.sha1(). Note that the security of the hash alone doesn’t apply when used intermediately in HMAC.

  • algorithm (Optional[itsdangerous.signer.SigningAlgorithm]) – A SigningAlgorithm instance to use instead of building a default HMACAlgorithm with the digest_method.

Changed in version 2.0: Added support for key rotation by passing a list to secret_key.

Changelog

Changed in version 0.18: algorithm was added as an argument to the class constructor.

Changed in version 0.14: key_derivation and digest_method were added as arguments to the class constructor.

static default_digest_method(string=b'', *, usedforsecurity=True)

The default digest method to use for the signer. The default is hashlib.sha1(), but can be changed to any hashlib or compatible object. Note that the security of the hash alone doesn’t apply when used intermediately in HMAC.

Changelog

New in version 0.14.

default_key_derivation: str = 'django-concat'

The default scheme to use to derive the signing key from the secret key and salt. The default is django-concat. Possible values are concat, django-concat, and hmac.

Changelog

New in version 0.14.

derive_key(secret_key=None)

This method is called to derive the key. The default key derivation choices can be overridden here. Key derivation is not intended to be used as a security method to make a complex key out of a short password. Instead you should use large random secret keys.

Parameters

secret_key (Optional[Union[str, bytes]]) – A specific secret key to derive from. Defaults to the last item in secret_keys.

Return type

bytes

Changed in version 2.0: Added the secret_key parameter.

get_signature(value)

Returns the signature for the given value.

Parameters

value (Union[str, bytes]) –

Return type

bytes

property secret_key: bytes

The newest (last) entry in the secret_keys list. This is for compatibility from before key rotation support was added.

secret_keys: List[bytes]

The list of secret keys to try for verifying signatures, from oldest to newest. The newest (last) key is used for signing.

This allows a key rotation system to keep a list of allowed keys and remove expired ones.

sign(value)

Signs the given string.

Parameters

value (Union[str, bytes]) –

Return type

bytes

unsign(signed_value)

Unsigns the given string.

Parameters

signed_value (Union[str, bytes]) –

Return type

bytes

validate(signed_value)

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

Parameters

signed_value (Union[str, bytes]) –

Return type

bool

verify_signature(value, sig)

Verifies the signature for the given value.

Parameters
Return type

bool

Signing Algorithms

class itsdangerous.signer.NoneAlgorithm

Provides an algorithm that does not perform any signing and returns an empty signature.

class itsdangerous.signer.HMACAlgorithm(digest_method=None)

Provides signature generation using HMACs.

Parameters

digest_method (Any) –