Added 'settings' section to CSRF docs, eliminating the unneeded 'Subdomains' section

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

1 files changed, 47 insertions, 19 deletions

diff --git a/docs/ref/contrib/csrf.txt b/docs/ref/contrib/csrf.txt
index 762c517084..88e9523719 100644
--- a/docs/ref/contrib/csrf.txt
+++ b/docs/ref/contrib/csrf.txt
@@ -166,18 +166,6 @@ both is fine, and will incur minimal overhead.
             # ...
             return render(request, "a_template.html", c)
 
-Subdomains
-----------
-
-By default, CSRF cookies are specific to the subdomain they are set for.  This
-means that a form served from one subdomain (e.g. server1.example.com) will not
-be able to have a target on another subdomain (e.g. server2.example.com).  This
-restriction can be removed by setting :setting:`CSRF_COOKIE_DOMAIN` to be
-something like ``".example.com"``.
-
-Please note that, with or without use of this setting, this CSRF protection
-mechanism is not safe against cross-subdomain attacks -- see `Limitations`_.
-
 Rejected requests
 =================
 
@@ -189,13 +177,7 @@ POST form.
 
 The error page, however, is not very friendly, so you may want to provide your
 own view for handling this condition.  To do this, simply set the
-:setting:`CSRF_FAILURE_VIEW` setting to a dotted path to your own view function,
-which should have the following signature::
-
-    def csrf_failure(request, reason="")
-
-where ``reason`` is a short message (intended for developers or logging, not for
-end users) indicating the reason the request was rejected.
+:setting:`CSRF_FAILURE_VIEW` setting.
 
 How it works
 ============
@@ -409,3 +391,49 @@ all relevant views in contrib apps use the ``csrf_protect`` decorator to ensure
 the security of these applications against CSRF.  It is recommended that the
 developers of other reusable apps that want the same guarantees also use the
 ``csrf_protect`` decorator on their views.
+
+Settings
+========
+
+A number of settings can be used to control Django's CSRF behaviour.
+
+CSRF_COOKIE_DOMAIN
+------------------
+
+.. versionadded:: 1.2
+
+Default: ``None``
+
+The domain to be used when setting the CSRF cookie.  This can be useful for
+easily allowing cross-subdomain requests to be exluded from the normal cross
+site request forgery protection.  It should be set to a string such as
+``".lawrence.com"`` to allow a POST request from a form on one subdomain to be
+accepted by accepted by a view served from another subdomain.
+
+Please note that, with or without use of this setting, this CSRF protection
+mechanism is not safe against cross-subdomain attacks -- see `Limitations`_.
+
+CSRF_COOKIE_NAME
+----------------
+
+.. versionadded:: 1.2
+
+Default: ``'csrftoken'``
+
+The name of the cookie to use for the CSRF authentication token. This can be
+whatever you want.
+
+CSRF_FAILURE_VIEW
+-----------------
+
+.. versionadded:: 1.2
+
+Default: ``'django.views.csrf.csrf_failure'``
+
+A dotted path to the view function to be used when an incoming request
+is rejected by the CSRF protection.  The function should have this signature::
+
+  def csrf_failure(request, reason="")
+
+where ``reason`` is a short message (intended for developers or logging, not for
+end users) indicating the reason the request was rejected.