Browse files

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

Thanks Baptiste Mispelon for the suggestion.

Backport of c5bc98d from master.
  • Loading branch information...
tricoder42 authored and timgraham committed Jul 3, 2013
1 parent 295a925 commit 2f9e5483f6e65bcc0364833517fdae26f1b8c885
Showing with 24 additions and 6 deletions.
  1. +4 −0 django/core/
  2. +20 −6 docs/topics/signing.txt
@@ -183,6 +183,10 @@ def sign(self, value):
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)
@@ -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)
.. 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.

0 comments on commit 2f9e548

Please sign in to comment.