Merge pull request #331 from davidfischer/master

Ticket #17324 - Improve security docs with better CSRF explanation

docs/topics/security.txt

@@ -76,9 +76,17 @@ POST to your Web site and have another logged in user unwittingly submit that
 form. The malicious user would have to know the nonce, which is user specific
 (using a cookie).
 
+When deployed with :ref:`HTTPS <security-recommendation-ssl>`, 
+``CsrfViewMiddleware`` will check that the HTTP referer header is set to a 
+URL on the same origin (including subdomain and port). Because HTTPS
+provides additional security, it is imperative to ensure connections use HTTPS
+where it is available by forwarding insecure connection requests and using
+HSTS for supported browsers.
+
 Be very careful with marking views with the ``csrf_exempt`` decorator unless
 it is absolutely necessary.
 
+
 SQL injection protection
 ========================
 
@@ -112,6 +120,8 @@ The middleware is strongly recommended for any site that does not need to have
 its pages wrapped in a frame by third party sites, or only needs to allow that
 for a small section of the site.
 
+.. _security-recommendation-ssl:
+
 SSL/HTTPS
 =========
 
@@ -147,7 +157,15 @@ server, there are some additional steps you may need:
   any POST data being accepted over HTTP (which will be fine if you are
   redirecting all HTTP traffic to HTTPS).
 
-.. _additional-security-topics:
+* Use HTTP Strict Transport Security (HSTS)
+
+  HSTS is an HTTP header that informs a browser that all future connections
+  to a particular site should always use HTTPS. Combined with redirecting
+  requests over HTTP to HTTPS, this will ensure that connections always enjoy
+  the added security of SSL provided one successful connection has occurred.
+  HSTS is usually configured on the web server.
+
+.. _host-headers-virtual-hosting:
 
 Host headers and virtual hosting
 ================================
@@ -167,6 +185,8 @@ recommend you ensure your Web server is configured such that:
 Additionally, as of 1.3.1, Django requires you to explicitly enable support for
 the ``X-Forwarded-Host`` header if your configuration requires it.
 
+.. _additional-security-topics:
+
 Additional security topics
 ==========================