Ticket #20687: ticket-20687.patch

django/core/signing.py

@@ -183 +183 @@
         return super(TimestampSigner, self).sign(value)
 
     def unsign(self, value, max_age=None):
+        """
+        Retrieve original value and check it wasn't signed longer than
+        max_age before (in seconds).
+
+        """
         result =  super(TimestampSigner, self).unsign(value)
         value, timestamp = result.rsplit(self.sep, 1)
         timestamp = baseconv.base62.decode(timestamp)

docs/topics/signing.txt

@@ -37 +37 @@
 Using the low-level API
 =======================
 
-.. class:: Signer
-
 Django's signing methods live in the ``django.core.signing`` module.
 To sign a value, first instantiate a ``Signer`` instance::
 
@@ -74 +72 @@
     >>> value
     'My string:EkfQJafvGyiofrdGnuthdxImIJw'
 
+.. class:: Signer(key=None, sep=':', salt=None)
+
+    Returns signer which uses ``key`` to generate signatures and ``sep``
+    to separate values.
+
 Using the salt argument
 -----------------------
 
@@ -105 +108 @@
 Verifying timestamped values
 ----------------------------
 
-.. class:: TimestampSigner
-
 ``TimestampSigner`` is a subclass of :class:`~Signer` that appends a signed
 timestamp to the value. This allows you to confirm that a signed value was
 created within a specified period of time::
@@ -124 +125 @@
     >>> signer.unsign(value, max_age=20)
     u'hello'
 
+.. class:: TimestampSigner(key=None, sep=':', salt=None)
+
+.. function:: TimestampSigner.sign(value)
+
+    Sign ``value`` and append current timestamp to it.
+
+.. function:: TimestampSigner.unsing(value, max_age=None)
+
+    Checks if ``value`` was signed less than ``max_age`` seconds before, otherwise
+    raises ``SignatureExpired``
+
 Protecting complex data structures
 ----------------------------------
 
@@ -142 +154 @@
 
 .. function:: dumps(obj, key=None, salt='django.core.signing', compress=False)
 
-    Returns URL-safe, sha1 signed base64 compressed JSON string.
+    Returns URL-safe, sha1 signed base64 compressed JSON string. Serialized
+    object is signed using :class:`~TimestampSigner`.
 
 .. function:: loads(string, key=None, salt='django.core.signing', max_age=None)
 
-    Reverse of dumps(), raises ``BadSignature`` if signature fails.
+    Reverse of ``dumps()``, raises ``BadSignature`` if signature fails. Optionaly
+    checks ``max_age`` (in seconds).