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.14: key_derivation and digest_method were added as arguments to the class constructor.

New in version 0.18: algorithm was added as an argument 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.

derive_key()

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.

get_signature(value)

Returns the signature for the given value.

sign(value)

Signs the given string.

unsign(signed_value)

Unsigns the given string.

validate(signed_value)

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.