Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Fixed #20687 -- Added documentation for django.core.signing API.

Thanks Baptiste Mispelon for the suggestion.
  • Loading branch information...
commit c5bc98d7e1779263dc870843cab296f052e9a318 1 parent 63b2155
@tricoder42 tricoder42 authored timgraham committed
Showing with 24 additions and 6 deletions.
  1. +4 −0 django/core/signing.py
  2. +20 −6 docs/topics/signing.txt
View
4 django/core/signing.py
@@ -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)
View
26 docs/topics/signing.txt
@@ -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.
Please sign in to comment.
Something went wrong with that request. Please try again.