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 (str | bytes | cabc.Iterable[str] | cabc.Iterable[bytes]) – The secret key to sign and verify with. Can be a list of keys, oldest to newest, to support key rotation.
salt (str | bytes | None) – Extra key to combine with
secret_key
to distinguish signatures in different contexts.sep (str | bytes) – Separator between the signature and value.
key_derivation (str | None) – How to derive the signing key from the secret key and salt. Possible values are
concat
,django-concat
, orhmac
. Defaults todefault_key_derivation
, which defaults todjango-concat
.digest_method (t.Any | None) – Hash function to use when generating the HMAC signature. Defaults to
default_digest_method
, which defaults tohashlib.sha1()
. Note that the security of the hash alone doesn’t apply when used intermediately in HMAC.algorithm (SigningAlgorithm | None) – A
SigningAlgorithm
instance to use instead of building a defaultHMACAlgorithm
with thedigest_method
.
Changelog
Changed in version 2.0: Added support for key rotation by passing a list to
secret_key
.Changed in version 0.18:
algorithm
was added as an argument to the class constructor.Changed in version 0.14:
key_derivation
anddigest_method
were added as arguments to the class constructor.- static default_digest_method(string=b'')¶
The default digest method to use for the signer. The default is
hashlib.sha1()
, but can be changed to anyhashlib
or compatible object. Note that the security of the hash alone doesn’t apply when used intermediately in HMAC.Changelog
Added 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 areconcat
,django-concat
, andhmac
.Changelog
Added in version 0.14.
- 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.
- property secret_key: bytes¶
The newest (last) entry in the
secret_keys
list. This is for compatibility from before key rotation support was added.
- 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 (str | bytes | None) – A specific secret key to derive from. Defaults to the last item in
secret_keys
.- Return type:
Changelog
Changed in version 2.0: Added the
secret_key
parameter.
- get_signature(value)¶
Returns the signature for the given value.
- verify_signature(value, sig)¶
Verifies the signature for the given value.
- unsign(signed_value)¶
Unsigns the given string.
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 (t.Any)