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.
Changelog
New in version 0.18:
algorithm
was added as an argument to the class constructor.New in version 0.14:
key_derivation
anddigest_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.
Changelog
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
andhmac
. This is used for deriving a key from the secret key with an added salt.Changelog
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.
-
static
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.