[1.6.x] Added a warning regarding session security and subdomains.

Backport of a3372f67cb from master

2 files changed, 35 insertions, 2 deletions

diff --git a/docs/topics/http/sessions.txt b/docs/topics/http/sessions.txt
index 92e5c6622e..8adaa14c39 100644
--- a/docs/topics/http/sessions.txt
+++ b/docs/topics/http/sessions.txt
@@ -307,13 +307,19 @@ You can edit it multiple times.
       Returns either ``True`` or ``False``, depending on whether the user's
       session cookie will expire when the user's Web browser is closed.
 
-    .. method:: SessionBase.clear_expired
+    .. method:: clear_expired
 
       .. versionadded:: 1.5
 
       Removes expired sessions from the session store. This class method is
       called by :djadmin:`clearsessions`.
 
+    .. method:: cycle_key
+
+      Creates a new session key while retaining the current session data.
+      :func:`django.contrib.auth.login()` calls this method to mitigate against
+      session fixation.
+
 .. _session_serialization:
 
 Session serialization
@@ -498,7 +504,7 @@ An API is available to manipulate session data outside of a view::
     >>> s['last_login']
     1376587691
 
-In order to prevent session fixation attacks, sessions keys that don't exist
+In order to mitigate session fixation attacks, sessions keys that don't exist
 are regenerated::
 
     >>> from django.contrib.sessions.backends.db import SessionStore
@@ -641,6 +647,26 @@ behavior:
 * :setting:`SESSION_FILE_PATH`
 * :setting:`SESSION_SAVE_EVERY_REQUEST`
 
+.. _topics-session-security:
+
+Session security
+================
+
+Subdomains within a site are able to set cookies on the client for the whole
+domain. This makes session fixation possible if all subdomains are not
+controlled by trusted users (or, are at least unable to set cookies).
+
+For example, an attacker could log into ``good.example.com`` and get a valid
+session for his account. If the attacker has control over ``bad.example.com``,
+he can use it to send his session key to you since a subdomain is permitted
+to set cookies on `*.example.com``. When you visit ``good.example.com``,
+you'll be logged in as the attacker and might inadvertently enter your
+sensitive personal data (e.g. credit card info) into the attackers account.
+
+Another possible attack would be if ``good.example.com`` sets its
+:setting:`SESSION_COOKIE_DOMAIN` to ``".example.com"`` which would cause
+session cookies from that site to be sent to ``bad.example.com``.
+
 Technical details
 =================
 
diff --git a/docs/topics/security.txt b/docs/topics/security.txt
index 22135a72ea..5200edb95f 100644
--- a/docs/topics/security.txt
+++ b/docs/topics/security.txt
@@ -195,6 +195,13 @@ Additionally, as of 1.3.1, Django requires you to explicitly enable support for
 the ``X-Forwarded-Host`` header (via the :setting:`USE_X_FORWARDED_HOST`
 setting) if your configuration requires it.
 
+Session security
+================
+
+Similar to the :ref:`CSRF limitations <csrf-limitations>` requiring a site to
+be deployed such that untrusted users don't have access to any subdomains,
+:mod:`django.contrib.sessions` also has limitations. See :ref:`the session
+topic guide section on security <topics-session-security>` for details.
 
 .. _additional-security-topics: