The most basic interface is the signing interface. The
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
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
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
bytesand 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.
key_derivation (str | None) – How to derive the signing key from the secret key and salt. Possible values are
hmac. Defaults to
default_key_derivation, which defaults to
digest_method (Any | None) – 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 (SigningAlgorithm | None) – A
SigningAlgorithminstance to use instead of building a default
Changed in version 2.0: Added support for key rotation by passing a list to
Changed in version 0.18:
algorithmwas added as an argument to the class constructor.
Changed in version 0.14:
digest_methodwere 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
hashlibor compatible object. Note that the security of the hash alone doesn’t apply when used intermediately in HMAC.
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
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.
- Return type:
Changed in version 2.0: Added the
Returns the signature for the given value.
- property secret_key: bytes¶
The newest (last) entry in the
secret_keyslist. 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.
Unsigns the given string.
Only validates the given signed value. Returns
Trueif the signature exists and is valid.
- class itsdangerous.signer.NoneAlgorithm¶
Provides an algorithm that does not perform any signing and returns an empty signature.