Explained the purpose of the salt.

docs/index.rst

@@ -119,6 +119,46 @@ this, itsdangerous also provides URL safe serializers:
 >>> s.loads('WzEsMiwzLDRd.wSPHqC0gR7VUqivlSukJ0IeTDgo')
 [1, 2, 3, 4]
 
+.. _the-salt:
+
+The Salt
+--------
+
+All classes also accept a salt argument.  The name might me 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 to 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
+
+Only the serializer with the same salt can load the value:
+
+>>> s2.loads(s2.dumps(42))
+42
+
 API
 ---
 

itsdangerous.py

@@ -84,6 +84,15 @@ def bytes_to_int(bytes):
 class Signer(object):
     """This class can sign a string 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 :ref:`the-salt` for an example of what the salt is doing and how you
+    can utilize it.
     """
 
     def __init__(self, secret_key, salt=None, sep='.'):
@@ -220,9 +229,6 @@ def dumps(self, obj):
         If compress is True (the default) checks if compressing using zlib can
         save some space. Prepends a '.' to signify compression. This is included
         in the signature, to protect against zip bombs.
-
-        Salt can be used to further salt the hash, in case you're worried
-        that the NSA might try to brute-force your SHA-1 protected secret.
         """
         return self.make_signer().sign(self.dump_payload(obj))
 

setup.py

@@ -8,7 +8,7 @@
     name='itsdangerous',
     author='Armin Ronacher',
     author_email='armin.ronacher@active-4.com',
-    version='0.9',
+    version='0.9.1',
     url='http://github.com/mitsuhiko/itsdangerous',
     py_modules=['itsdangerous'],
     description='Various helpers to pass trusted data to untrusted environments.',