Sometimes you just want to send some data to untrusted environments. But how to do this safely? The trick involves signing. Given a key only you know, you can cryptographically sign your data and hand it over to someone else. When you get the data back you can easily ensure that nobody tampered with it.
Granted, the receiver can decode the contents and look into the package, but they can not modify the contents unless they also have your secret key. So if you keep the key secret and complex, you will be fine.
Internally itsdangerous uses HMAC and SHA1 for signing by default and bases the implementation on the Django signing module. It also however supports JSON Web Signatures (JWS). The library is BSD licensed and written by Armin Ronacher though most of the copyright for the design and implementation goes to Simon Willison and the other amazing Django people that made this library possible.
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')
'my string.wh6tMHxLgJqB6oY1uT73iMlyrOA'
The signature is appended to the string, separated by a dot (.). To validate the string, use the unsign() method:
>>> s.unsign('my string.wh6tMHxLgJqB6oY1uT73iMlyrOA')
'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 unsigning fails you will get an exception:
>>> s.unsign('my string.wh6tMHxLgJqB6oY1uT73iMlyrOX')
Traceback (most recent call last):
...
itsdangerous.BadSignature: Signature "wh6tMHxLgJqB6oY1uT73iMlyrOX" does not match
Traceback (most recent call last):
...
itsdangerous.BadSignature: Signature "wh6tMHxLgJqB6oY1uT73iMlyrOX" does not match
If you want to expire signatures you can use the TimestampSigner class which will additionally put in a timestamp information and sign it. On unsigning you can validate that the timestamp did not expire:
>>> from itsdangerous import TimestampSigner
>>> s = TimestampSigner('secret-key')
>>> string = s.sign('foo')
>>> s.unsign(string, max_age=5)
Traceback (most recent call last):
...
itsdangerous.SignatureExpired: Signature age 15 > 5 seconds
Traceback (most recent call last):
...
itsdangerous.SignatureExpired: Signature age 15 > 5 seconds
Because strings are hard to handle this module also provides a serialization interface similar to json/pickle and others. (Internally it uses simplejson by default, however this can be changed by subclassing.) The Serializer class implements that:
>>> from itsdangerous import Serializer
>>> s = Serializer('secret-key')
>>> s.dumps([1, 2, 3, 4])
'[1, 2, 3, 4].r7R9RhGgDPvvWl3iNzLuIIfELmo'
And it can of course also load:
>>> s.loads('[1, 2, 3, 4].r7R9RhGgDPvvWl3iNzLuIIfELmo')
[1, 2, 3, 4]
If you want to have the timestamp attached you can use the TimedSerializer.
Often it is helpful if you can pass these trusted strings to environments where you only have a limited set of characters available. Because of this, itsdangerous also provides URL safe serializers:
>>> from itsdangerous import URLSafeSerializer
>>> s = URLSafeSerializer('secret-key')
>>> s.dumps([1, 2, 3, 4])
'WzEsMiwzLDRd.wSPHqC0gR7VUqivlSukJ0IeTDgo'
>>> s.loads('WzEsMiwzLDRd.wSPHqC0gR7VUqivlSukJ0IeTDgo')
[1, 2, 3, 4]
Starting with “itsdangerous” 0.18 JSON Web Signatures are also supported. They generally work very similar to the already existing URL safe serializer but will emit headers according to the current draft (10) of the JSON Web Signature (JWS) [draft-ietf-jose-json-web-signature].
>>> from itsdangerous import JSONWebSignatureSerializer
>>> s = JSONWebSignatureSerializer('secret-key')
>>> s.dumps({'x': 42})
'eyJhbGciOiJIUzI1NiJ9.eyJ4Ijo0Mn0.ZdTn1YyGz9Yx5B5wNpWRL221G1WpVE5fPCPKNuc6UAo'
When loading the value back the header will not be returned by default like with the other serializers. However it is possible to also ask for the header by passing return_header=True. Custom header fields can be provided upon serialization:
>>> s.dumps(0, header_fields={'v': 1})
'eyJhbGciOiJIUzI1NiIsInYiOjF9.MA.wT-RZI9YU06R919VBdAfTLn82_iIQD70J_j-3F4z_aM'
>>> s.loads('eyJhbGciOiJIUzI1NiIsInYiOjF9.MA.wT-RZI9YU06R919VBdAf'
... 'TLn82_iIQD70J_j-3F4z_aM', return_header=True)
...
(0, {u'alg': u'HS256', u'v': 1})
“itsdangerous” only provides HMAC SHA derivatives and the none algorithm at the moment and does not support the ECC based ones. The algorithm in the header is checked against the one of the serializer and on a mismatch a BadSignature exception is raised.
All classes also accept a salt argument. The name might be misleading because usually if you think of salts in cryptography you would expect the salt to be something that is stored alongside the resulting signed string as a way to prevent rainbow table lookups. Such salts are usually public.
In “itsdangerous”, like in the original Django implementation, the salt serves a different purpose. You could describe it as namespacing. It’s still not critical if you disclose it because without the secret key it does not help an attacker.
Let’s assume that you have two links you want to sign. You have the activation link on your system which can activate a user account and then you have an upgrade link that can upgrade a user’s account to a paid account which you send out via email. If in both cases all you sign is the user ID a user could reuse the variable part in the URL from the activation link to upgrade the account. Now you could either put more information in there which you sign (like the intention: upgrade or activate), but you could also use different salts:
>>> s1 = URLSafeSerializer('secret-key', salt='activate-salt')
>>> s1.dumps(42)
'NDI.kubVFOOugP5PAIfEqLJbXQbfTxs'
>>> s2 = URLSafeSerializer('secret-key', salt='upgrade-salt')
>>> s2.dumps(42)
'NDI.7lx-N1P-z2veJ7nT1_2bnTkjGTE'
>>> s2.loads(s1.dumps(42))
Traceback (most recent call last):
...
itsdangerous.BadSignature: Signature "kubVFOOugP5PAIfEqLJbXQbfTxs" does not match
Traceback (most recent call last):
...
itsdangerous.BadSignature: Signature "kubVFOOugP5PAIfEqLJbXQbfTxs" does not match
Only the serializer with the same salt can load the value:
>>> s2.loads(s2.dumps(42))
42
Starting with itsdangerous 0.14 exceptions have helpful attributes which allow you to inspect payload if the signature check failed. This has to be done with extra care because at that point you know that someone tampered with your data but it might be useful for debugging purposes.
Example usage:
from itsdangerous import URLSafeSerializer, BadSignature, BadData
s = URLSafeSerializer('secret-key')
decoded_payload = None
try:
decoded_payload = s.loads(data)
# This payload is decoded and safe
except BadSignature, e:
encoded_payload = e.payload
if encoded_payload is not None:
try:
decoded_payload = s.load_payload(encoded_payload)
except BadData:
pass
# This payload is decoded but unsafe because someone
# tampered with the signature. The decode (load_payload)
# step is explicit because it might be unsafe to unserialize
# the payload (think pickle instead of json!)
If you don’t want to inspect attributes to figure out what exactly went wrong you can also use the unsafe loading:
from itsdangerous import URLSafeSerializer
s = URLSafeSerializer('secret-key')
sig_okay, payload = s.loads_unsafe(data)
The first item in the returned tuple is a boolean that indicates if the signature was correct.
On Python 3 the interface that itsdangerous provides can be confusing at first. Depending on the internal serializer it wraps the return value of the functions can alter between unicode strings or bytes objects. The internal signer is always byte based.
This is done to allow the module to operate on different serializers independent of how they are implemented. The module decides on the type of the serializer by doing a test serialization of an empty object.
This class can sign bytes and unsign it and validate 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.
The digest method to use for the signer. This defaults to sha1 but can be changed for any other function in the hashlib module.
Changed in version 0.14.
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. If you’re unhappy with the default key derivation choices you can override them here. Keep in mind that the key derivation in itsdangerous 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.
Just validates the given signed value. Returns True if the signature exists and is valid, False otherwise.
Verifies the signature for the given value.
Works like the regular Signer but also records the time of the signing and can be used to expire signatures. The unsign method can rause a SignatureExpired method if the unsigning failed because the signature is expired. This exception is a subclass of BadSignature.
Returns the current timestamp. This implementation returns the seconds since 1/1/2011. The function must return an integer.
Signs the given string and also attaches a time information.
Used to convert the timestamp from get_timestamp into a datetime object.
Works like the regular unsign() but can also validate the time. See the base docstring of the class for the general behavior. If return_timestamp is set to True the timestamp of the signature will be returned as naive datetime.datetime object in UTC.
Just validates the given signed value. Returns True if the signature exists and is valid, False otherwise.
This class provides a algorithm that does not perform any signing and returns an empty signature.
This class provides signature generation using HMACs.
This class provides a serialization interface on top of the signer. It provides a similar API to json/pickle and other modules but is slightly differently structured internally. If you want to change the underlying implementation for parsing and loading you have to override the load_payload() and dump_payload() functions.
This implementation uses simplejson if available for dumping and loading and will fall back to the standard library’s json module if it’s not available.
Starting with 0.14 you do not need to subclass this class in order to switch out or customer the Signer. You can instead also pass a different class to the constructor as well as keyword arguments as dictionary that should be forwarded:
s = Serializer(signer_kwargs={'key_derivation': 'hmac'})
Changed in version 0.14:: The signer and signer_kwargs parameters were added to the constructor.
If a serializer module or class is not passed to the constructor this one is picked up. This currently defaults to json.
The default Signer class that is being used by this serializer.
New in version 0.14.
alias of Signer
Like dumps() but dumps into a file. The file handle has to be compatible with what the internal serializer expects.
Dumps the encoded object. The return value is always a bytestring. If the internal serializer is text based the value will automatically be encoded to utf-8.
Returns a signed string serialized with the internal serializer. The return value can be either a byte or unicode string depending on the format of the internal serializer.
Loads the encoded object. This function raises BadPayload if the payload is not valid. The serializer parameter can be used to override the serializer stored on the class. The encoded payload is always byte based.
Like loads_unsafe() but loads from a file.
New in version 0.15.
Reverse of dumps(), raises BadSignature if the signature validation fails.
Like loads() but without verifying the signature. This is potentially very dangerous to use depending on how your serializer works. The return value is (signature_okay, payload) instead of just the payload. The first item will be a boolean that indicates if the signature is okay (True) or if it failed. This function never fails.
Use it for debugging only and if you know that your serializer module is not exploitable (eg: do not use it with a pickle serializer).
New in version 0.15.
Uses the TimestampSigner instead of the default Signer().
alias of TimestampSigner
Reverse of dumps(), raises BadSignature if the signature validation fails. If a max_age is provided it will ensure the signature is not older than that time in seconds. In case the signature is outdated, SignatureExpired is raised which is a subclass of BadSignature. All arguments are forwarded to the signer’s unsign() method.
This serializer implements JSON Web Signature (JWS) support. Only supports the JWS Compact Serialization.
The default algorithm to use for signature generation
Works like the regular JSONWebSignatureSerializer but also records the time of the signing and can be used to expire signatures.
JWS currently does not specify this behavior but it mentions a possibility extension like this in the spec. Expiry date is encoded into the header similarily as specified in `draft-ietf-oauth-json-web-token <http://self-issued.info/docs/draft-ietf-oauth-json-web-token.html#expDef`_.
The unsign method can raise a SignatureExpired method if the unsigning failed because the signature is expired. This exception is a subclass of BadSignature.
Works like Serializer but dumps and loads into a URL safe string consisting of the upper and lowercase character of the alphabet as well as '_', '-' and '.'.
Works like TimedSerializer but dumps and loads into a URL safe string consisting of the upper and lowercase character of the alphabet as well as '_', '-' and '.'.
Raised if bad data of any sort was encountered. This is the base for all exceptions that itsdangerous is currently using.
New in version 0.15.
This error is raised if a signature does not match. As of itsdangerous 0.14 there are helpful attributes on the exception instances. You can also catch down the baseclass BadData.
The payload that failed the signature test. In some situations you might still want to inspect this, even if you know it was tampered with.
New in version 0.14.
Raised for time based signatures that fail. This is a subclass of BadSignature so you can catch those down as well.
If the signature expired this exposes the date of when the signature was created. This can be helpful in order to tell the user how long a link has been gone stale.
New in version 0.14.
Signature timestamp is older than required max_age. This is a subclass of BadTimeSignature so you can use the baseclass for catching the error.
Raised if a signed header is invalid in some form. This only happens for serializers that have a header that goes with the signature.
New in version 0.24.
If the header is actually available but just malformed it might be stored here.
If available, the error that indicates why the payload was not valid. This might be None.
This error is raised in situations when payload is loaded without checking the signature first and an exception happend as a result of that. The original exception that caused that will be stored on the exception as original_error.
This can also happen with a JSONWebSignatureSerializer that is subclassed and uses a different serializer for the payload than the expected one.
New in version 0.15.
If available, the error that indicates why the payload was not valid. This might be None.
base64 encodes a single bytestring (and is tolerant to getting called with a unicode string). The resulting bytestring is safe for putting into URLs.
base64 decodes a single bytestring (and is tolerant to getting called with a unicode string). The result is also a bytestring.