From 6151fdf930c9a513597e94fe8e8aee5e88c69ca1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tom=C3=A1=C5=A1=20Ehrlich?= <tomas.ehrlich@gmail.com>
Date: Wed, 3 Jul 2013 08:13:38 +0200
Subject: [PATCH] [1.5.x] Fixed #20687 -- Added documentation for
django.core.signing API.
Thanks Baptiste Mispelon for the suggestion.
Backport of c5bc98d7e1 from master.
---
django/core/signing.py | 4 ++++
docs/topics/signing.txt | 26 ++++++++++++++++++++------
2 files changed, 24 insertions(+), 6 deletions(-)
diff --git a/django/core/signing.py b/django/core/signing.py
index 92ab968123..4d2b0a2d54 100644
--- a/django/core/signing.py
+++ b/django/core/signing.py
@@ -195,6 +195,10 @@ class TimestampSigner(Signer):
return super(TimestampSigner, self).sign(value)
def unsign(self, value, max_age=None):
+ """
+ Retrieve original value and check it wasn't signed more
+ than max_age seconds ago.
+ """
result = super(TimestampSigner, self).unsign(value)
value, timestamp = result.rsplit(self.sep, 1)
timestamp = baseconv.base62.decode(timestamp)
diff --git a/docs/topics/signing.txt b/docs/topics/signing.txt
index 671f2472d5..3da70da679 100644
--- a/docs/topics/signing.txt
+++ b/docs/topics/signing.txt
@@ -39,8 +39,6 @@ generate their own signed values.
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::
@@ -76,6 +74,11 @@ generate signatures. You can use a different secret by passing it to the
>>> value
'My string:EkfQJafvGyiofrdGnuthdxImIJw'
+.. class:: Signer(key=None, sep=':', salt=None)
+
+ Returns a signer which uses ``key`` to generate signatures and ``sep``
+ to separate values.
+
Using the salt argument
-----------------------
@@ -107,8 +110,6 @@ secret.
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::
@@ -126,6 +127,17 @@ created within a specified period of time::
>>> signer.unsign(value, max_age=20)
u'hello'
+.. class:: TimestampSigner(key=None, sep=':', salt=None)
+
+ .. method:: sign(value)
+
+ Sign ``value`` and append current timestamp to it.
+
+ .. method:: unsign(value, max_age=None)
+
+ Checks if ``value`` was signed less than ``max_age`` seconds ago,
+ otherwise raises ``SignatureExpired``.
+
Protecting complex data structures
----------------------------------
@@ -144,8 +156,10 @@ to execute arbitrary commands by exploiting the pickle format.::
.. 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.
+ Checks ``max_age`` (in seconds) if given.