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):
itsdangerous.exc.BadSignature: Signature "wh6tMHxLgJqB6oY1uT73iMlyrOA" does not match

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

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

This class can sign and unsign bytes, validating the signature provided.

Salt can be used to namespace the hash, so that a signed string is only valid for a given namespace. Leaving this at the default value or re-using a salt value across different parts of your application where the same signed value in one part can mean something different in another part is a security risk.

See The Salt for an example of what the salt is doing and how you can utilize it.


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

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

static default_digest_method()

The digest method to use for the signer. This defaults to SHA1 but can be changed to any other function in the hashlib module.


New in version 0.14.

default_key_derivation = 'django-concat'

Controls how the key is derived. The default is Django-style concatenation. Possible values are concat, django-concat and hmac. This is used for deriving a key from the secret key with an added salt.


New in version 0.14.


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.


Returns the signature for the given value.


Signs the given string.


Unsigns the given string.


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

verify_signature(value, sig)

Verifies the signature for the given value.

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.