[1.6.x] Fixed #20687 -- Added documentation for django.core.signing API.

Thanks Baptiste Mispelon for the suggestion.

Backport of c5bc98d7e1 from master.
This commit is contained in:
Tomáš Ehrlich 2013-07-03 08:13:38 +02:00 committed by Tim Graham
parent 295a925cef
commit 2f9e5483f6
2 changed files with 24 additions and 6 deletions

View File

@ -183,6 +183,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)

View File

@ -37,8 +37,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::
@ -74,6 +72,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
-----------------------
@ -105,8 +108,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::
@ -124,6 +125,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
----------------------------------
@ -142,8 +154,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.