Fixed #12417 -- Added signing functionality, including signing cookies. Many thanks to Simon, Stephan, Paul and everyone else involved.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@16253 bcc190cf-cafb-0310-a4f2-bffc1f526a37

2 files changed, 61 insertions, 0 deletions

diff --git a/docs/ref/request-response.txt b/docs/ref/request-response.txt
index 6281120d15..d4ff40a746 100644
--- a/docs/ref/request-response.txt
+++ b/docs/ref/request-response.txt
@@ -240,6 +240,43 @@ Methods
 
    Example: ``"http://example.com/music/bands/the_beatles/?print=true"``
 
+.. method:: HttpRequest.get_signed_cookie(key, default=RAISE_ERROR, salt='', max_age=None)
+
+   .. versionadded:: 1.4
+
+   Returns a cookie value for a signed cookie, or raises a
+   :class:`~django.core.signing.BadSignature` exception if the signature is
+   no longer valid. If you provide the ``default`` argument the exception
+   will be suppressed and that default value will be returned instead.
+
+   The optional ``salt`` argument can be used to provide extra protection
+   against brute force attacks on your secret key. If supplied, the
+   ``max_age`` argument will be checked against the signed timestamp
+   attached to the cookie value to ensure the cookie is not older than
+   ``max_age`` seconds.
+
+   For example::
+
+          >>> request.get_signed_cookie('name')
+          'Tony'
+          >>> request.get_signed_cookie('name', salt='name-salt')
+          'Tony' # assuming cookie was set using the same salt
+          >>> request.get_signed_cookie('non-existing-cookie')
+          ...
+          KeyError: 'non-existing-cookie'
+          >>> request.get_signed_cookie('non-existing-cookie', False)
+          False
+          >>> request.get_signed_cookie('cookie-that-was-tampered-with')
+          ...
+          BadSignature: ...
+          >>> request.get_signed_cookie('name', max_age=60)
+          ...
+          SignatureExpired: Signature age 1677.3839159 > 60 seconds
+          >>> request.get_signed_cookie('name', False, max_age=60)
+          False
+
+   See :doc:`cryptographic signing </topics/signing>` for more information.
+
 .. method:: HttpRequest.is_secure()
 
    Returns ``True`` if the request is secure; that is, if it was made with
@@ -618,6 +655,17 @@ Methods
     .. _`cookie Morsel`: http://docs.python.org/library/cookie.html#Cookie.Morsel
     .. _HTTPOnly: http://www.owasp.org/index.php/HTTPOnly
 
+.. method:: HttpResponse.set_signed_cookie(key, value='', salt='', max_age=None, expires=None, path='/', domain=None, secure=None, httponly=False)
+
+    .. versionadded:: 1.4
+
+    Like :meth:`~HttpResponse.set_cookie()`, but
+    :doc:`cryptographic signing </topics/signing>` the cookie before setting
+    it. Use in conjunction with :meth:`HttpRequest.get_signed_cookie`.
+    You can use the optional ``salt`` argument for added key strength, but
+    you will need to remember to pass it to the corresponding
+    :meth:`HttpRequest.get_signed_cookie` call.
+
 .. method:: HttpResponse.delete_cookie(key, path='/', domain=None)
 
     Deletes the cookie with the given key. Fails silently if the key doesn't
diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt
index f5f1226f21..4716fabea7 100644
--- a/docs/ref/settings.txt
+++ b/docs/ref/settings.txt
@@ -1647,6 +1647,19 @@ See :tfilter:`allowed date format strings <date>`.
 
 See also ``DATE_FORMAT`` and ``SHORT_DATETIME_FORMAT``.
 
+.. setting:: SIGNING_BACKEND
+
+SIGNING_BACKEND
+---------------
+
+.. versionadded:: 1.4
+
+Default: 'django.core.signing.TimestampSigner'
+
+The backend used for signing cookies and other data.
+
+See also the :doc:`/topics/signing` documentation.
+
 .. setting:: SITE_ID
 
 SITE_ID