From ab26b65b2f178597be845e203eb698e193e3502e Mon Sep 17 00:00:00 2001
From: Joshua Kehn <josh@kehn.us>
Date: Mon, 31 Aug 2015 22:32:03 -0400
Subject: Fixed #25334 -- Provided a way to allow cross-origin unsafe requests
 over HTTPS.

Added the CSRF_TRUSTED_ORIGINS setting which contains a list of other
domains that are included during the CSRF Referer header verification
for secure (HTTPS) requests.
---
 docs/ref/csrf.txt      |  4 +++-
 docs/ref/settings.txt  | 18 ++++++++++++++++++
 docs/releases/1.9.txt  |  3 +++
 docs/spelling_wordlist |  1 +
 4 files changed, 25 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/ref/csrf.txt b/docs/ref/csrf.txt
index 590990571f..ba24339a78 100644
--- a/docs/ref/csrf.txt
+++ b/docs/ref/csrf.txt
@@ -257,7 +257,8 @@ 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.)
+   reliable enough under HTTP.) Expanding the accepted referers beyond the
+   current host can be done with the :setting:`CSRF_TRUSTED_ORIGINS` setting.
 
 This ensures that only forms that have originated from your Web site can be used
 to POST data back.
@@ -460,3 +461,4 @@ A number of settings can be used to control Django's CSRF behavior:
 * :setting:`CSRF_COOKIE_SECURE`
 * :setting:`CSRF_FAILURE_VIEW`
 * :setting:`CSRF_HEADER_NAME`
+* :setting:`CSRF_TRUSTED_ORIGINS`
diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt
index 217f54281d..ed5ac98947 100644
--- a/docs/ref/settings.txt
+++ b/docs/ref/settings.txt
@@ -428,6 +428,23 @@ any hyphens with underscores, and adding an ``'HTTP_'`` prefix to the name.
 For example, if your client sends a ``'X-XSRF-TOKEN'`` header, the setting
 should be ``'HTTP_X_XSRF_TOKEN'``.
 
+.. setting:: CSRF_TRUSTED_ORIGINS
+
+CSRF_TRUSTED_ORIGINS
+--------------------
+
+.. versionadded:: 1.9
+
+Default: ``[]`` (Empty list)
+
+A list of hosts which are trusted origins for unsafe requests (e.g. ``POST``).
+For a :meth:`secure <django.http.HttpRequest.is_secure>` unsafe
+request, Django's CSRF protection requires that the request have a ``Referer``
+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.
+
 .. setting:: DATABASES
 
 DATABASES
@@ -3374,6 +3391,7 @@ Security
   * :setting:`CSRF_COOKIE_SECURE`
   * :setting:`CSRF_FAILURE_VIEW`
   * :setting:`CSRF_HEADER_NAME`
+  * :setting:`CSRF_TRUSTED_ORIGINS`
 
 * :setting:`SECRET_KEY`
 * :setting:`X_FRAME_OPTIONS`
diff --git a/docs/releases/1.9.txt b/docs/releases/1.9.txt
index 5c0e3b613c..cf7909057b 100644
--- a/docs/releases/1.9.txt
+++ b/docs/releases/1.9.txt
@@ -484,6 +484,9 @@ CSRF
 * The request header's name used for CSRF authentication can be customized
   with :setting:`CSRF_HEADER_NAME`.
 
+* The new :setting:`CSRF_TRUSTED_ORIGINS` setting provides a way to allow
+  cross-origin unsafe requests (e.g. ``POST``) over HTTPS.
+
 Signals
 ^^^^^^^
 
diff --git a/docs/spelling_wordlist b/docs/spelling_wordlist
index 691ab2f4ef..1edaa68d49 100644
--- a/docs/spelling_wordlist
+++ b/docs/spelling_wordlist
@@ -644,6 +644,7 @@ refactoring
 refactorings
 refactors
 referer
+referers
 reflow
 regex
 regexes
-- 
cgit v1.3