Fixed #24496 -- Added CSRF Referer checking against CSRF_COOKIE_DOMAIN.

Thanks Seth Gottlieb for help with the documentation and
Carl Meyer and Joshua Kehn for reviews.

3 files changed, 22 insertions, 4 deletions

diff --git a/docs/ref/csrf.txt b/docs/ref/csrf.txt
index ba24339a78..77b176455c 100644
--- a/docs/ref/csrf.txt
+++ b/docs/ref/csrf.txt
@@ -257,11 +257,19 @@ The CSRF protection is based on the following things:
    due to the fact that HTTP 'Set-Cookie' headers are (unfortunately) accepted
    by clients that are talking to a site under HTTPS.  (Referer checking is not
    done for HTTP requests because the presence of the Referer header is not
-   reliable enough under HTTP.) Expanding the accepted referers beyond the
-   current host can be done with the :setting:`CSRF_TRUSTED_ORIGINS` setting.
+   reliable enough under HTTP.)
 
-This ensures that only forms that have originated from your Web site can be used
-to POST data back.
+   If the :setting:`CSRF_COOKIE_DOMAIN` setting is set, the referer is compared
+   against it. This setting supports subdomains. For example,
+   ``CSRF_COOKIE_DOMAIN = '.example.com'`` will allow POST requests from
+   ``www.example.com`` and ``api.example.com``. If the setting is not set, then
+   the referer must match the HTTP ``Host`` header.
+
+   Expanding the accepted referers beyond the current host or cookie domain can
+   be done with the :setting:`CSRF_TRUSTED_ORIGINS` setting.
+
+This ensures that only forms that have originated from trusted domains can be
+used to POST data back.
 
 It deliberately ignores GET requests (and other requests that are defined as
 'safe' by :rfc:`2616`). These requests ought never to have any potentially
@@ -269,6 +277,10 @@ dangerous side effects , and so a CSRF attack with a GET request ought to be
 harmless. :rfc:`2616` defines POST, PUT and DELETE as 'unsafe', and all other
 methods are assumed to be unsafe, for maximum protection.
 
+.. versionchanged:: 1.9
+
+    Checking against the :setting:`CSRF_COOKIE_DOMAIN` setting was added.
+
 Caching
 =======
 
diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt
index 2c855a0e1e..6a398e1c60 100644
--- a/docs/ref/settings.txt
+++ b/docs/ref/settings.txt
@@ -444,6 +444,8 @@ header that matches the origin present in the ``Host`` header. This prevents,
 for example, a ``POST`` request from ``subdomain.example.com`` from succeeding
 against ``api.example.com``. If you need cross-origin unsafe requests over
 HTTPS, continuing the example, add ``"subdomain.example.com"`` to this list.
+The setting also supports subdomains, so you could add ``".example.com"``, for
+example, to allow access from all subdomains of ``example.com``.
 
 .. setting:: DATABASES
 
diff --git a/docs/releases/1.9.txt b/docs/releases/1.9.txt
index d5ed37737f..efece97853 100644
--- a/docs/releases/1.9.txt
+++ b/docs/releases/1.9.txt
@@ -516,6 +516,10 @@ CSRF
 * The request header's name used for CSRF authentication can be customized
   with :setting:`CSRF_HEADER_NAME`.
 
+* The CSRF referer header is now validated against the
+  :setting:`CSRF_COOKIE_DOMAIN` setting if set. See :ref:`how-csrf-works` for
+  details.
+
 * The new :setting:`CSRF_TRUSTED_ORIGINS` setting provides a way to allow
   cross-origin unsafe requests (e.g. ``POST``) over HTTPS.