Fixed #27611 -- Doc'd that CSRF_COOKIE_HTTPONLY setting offers no security.

2 files changed, 15 insertions, 5 deletions

diff --git a/docs/ref/checks.txt b/docs/ref/checks.txt
index 3b16921e52..c6f7e518ef 100644
--- a/docs/ref/checks.txt
+++ b/docs/ref/checks.txt
@@ -593,7 +593,9 @@ The following checks are run if you use the :option:`check --deploy` option:
   sniffers to steal the CSRF token.
 * **security.W017**: :setting:`CSRF_COOKIE_HTTPONLY` is not set to ``True``.
   Using an ``HttpOnly`` CSRF cookie makes it more difficult for cross-site
-  scripting attacks to steal the CSRF token.
+  scripting attacks to steal the CSRF token. *This check is removed in Django
+  1.11 as the* :setting:`CSRF_COOKIE_HTTPONLY` *setting offers no pratical
+  benefit.*
 * **security.W018**: You should not have :setting:`DEBUG` set to ``True`` in
   deployment.
 * **security.W019**: You have
diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt
index 87dbc89584..1d28c96137 100644
--- a/docs/ref/settings.txt
+++ b/docs/ref/settings.txt
@@ -334,10 +334,18 @@ Default: ``False``
 Whether to use ``HttpOnly`` flag on the CSRF cookie. If this is set to
 ``True``, client-side JavaScript will not to be able to access the CSRF cookie.
 
-This can help prevent malicious JavaScript from bypassing CSRF protection. If
-you enable this and need to send the value of the CSRF token with Ajax requests,
-your JavaScript will need to pull the value from a hidden CSRF token form input
-on the page instead of from the cookie.
+Designating the CSRF cookie as ``HttpOnly`` doesn't offer any practical
+protection because CSRF is only to protect against cross-domain attacks. If an
+attacker can read the cookie via JavaScript, they're already on the same domain
+as far as the browser knows, so they can do anything they like anyway. (XSS is
+a much bigger hole than CSRF.)
+
+Although the setting offers little practical benefit, it's sometimes required
+by security auditors.
+
+If you enable this and need to send the value of the CSRF token with an AJAX
+request, your JavaScript must pull the value from a hidden CSRF token form
+input on the page instead of from the cookie.
 
 See :setting:`SESSION_COOKIE_HTTPONLY` for details on ``HttpOnly``.