Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Add section about proxy SSL headers in middleware doc.

  • Loading branch information...
commit f6441061a1706e0ba8bbc25fa29f6d076902503b 1 parent 0251c3d
Carl Meyer authored
Showing with 53 additions and 16 deletions.
  1. +44 −1 doc/middleware.rst
  2. +9 −15 doc/settings.rst
45 doc/middleware.rst
View
@@ -1,12 +1,13 @@
SecurityMiddleware
==================
-The ``djangosecure.middleware.SecurityMiddleware`` performs five different
+The ``djangosecure.middleware.SecurityMiddleware`` performs six different
tasks for you. Each one can be independently enabled or disabled with a
setting.
.. contents:: :local:
+
.. _x-frame-options:
X-Frame-Options: DENY
@@ -44,6 +45,7 @@ at all, decorate the view with the ``frame_deny_exempt`` decorator::
.. _Clickjacking: http://www.sectheory.com/clickjacking.htm
.. _its own middleware and setting: https://docs.djangoproject.com/en/dev/ref/clickjacking/
+
.. _http-strict-transport-security:
HTTP Strict Transport Security
@@ -82,6 +84,7 @@ may still be vulnerable via an insecure connection to a subdomain.
.. _"Strict-Transport-Security" header: http://en.wikipedia.org/wiki/Strict_Transport_Security
+
.. _x-content-type-options:
X-Content-Type-Options: nosniff
@@ -107,6 +110,7 @@ is ``True``.
.. _IE Security Blog: http://blogs.msdn.com/b/ie/archive/2008/09/02/ie8-security-part-vi-beta-2-update.aspx
+
.. _x-xss-protection:
X-XSS-Protection: 1; mode=block
@@ -135,6 +139,7 @@ header. ``SecurityMiddleware`` will do this for all responses if the
.. _XSS attack: http://en.wikipedia.org/wiki/Cross-site_scripting
.. _X-XSS-Protection header: http://blogs.msdn.com/b/ie/archive/2008/07/02/ie8-security-part-iv-the-xss-filter.aspx
+
.. _ssl-redirect:
SSL Redirect
@@ -168,3 +173,41 @@ in the :ref:`SECURE_REDIRECT_EXEMPT` setting.
may need to set the :ref:`SECURE_PROXY_SSL_HEADER` setting.
.. _nginx: http://nginx.org
+
+
+.. _proxied-ssl:
+
+Detecting proxied SSL
+---------------------
+
+.. note::
+
+ `Django 1.4+ offers the same functionality`_ built-in. The Django setting
+ works identically to this version.
+
+In some deployment scenarios, Django's ``request.is_secure()`` method returns
+``False`` even on requests that are actually secure, because the HTTPS
+connection is made to a front-end loadbalancer or reverse-proxy, and the
+internal proxied connection that Django sees is not HTTPS. Usually in these
+cases the proxy server provides an alternative header to indicate the secured
+external connection.
+
+If this is your situation, you can set the :ref:`SECURE_PROXY_SSL_HEADER`
+setting to a tuple of ("header", "value"); if "header" is set to "value" in
+``request.META``, django-secure will tell Django to consider it a secure
+request (in other words, ``request.is_secure()`` will return ``True`` for this
+request). The "header" should be specified in the format it would be found in
+``request.META`` (e.g. "HTTP_X_FORWARDED_PROTOCOL", not
+"X-Forwarded-Protocol"). For example::
+
+ SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTOCOL", "https")
+
+.. warning::
+
+ If you set this to a header that your proxy allows through from the request
+ unmodified (i.e. a header that can be spoofed), you are allowing an attacker
+ to pretend that any request is secure, even if it is not. Make sure you only
+ use a header that your proxy sets unconditionally, overriding any value from
+ the request.
+
+.. _Django 1.4+ offers the same functionality: https://docs.djangoproject.com/en/dev/ref/settings/#secure-proxy-ssl-header
24 doc/settings.rst
View
@@ -105,23 +105,17 @@ SECURE_PROXY_SSL_HEADER
.. note::
- As of Dec. 16, 2011, `this setting is available in Django 1.4`_ proper. The
- official Django setting works identically to this version.
-
-In some deployment scenarios, Django's ``request.is_secure()`` method returns
-``False`` even on requests that are actually secure, because the HTTPS
-connection is made to a front-end loadbalancer or reverse-proxy, and the
-internal proxied connection that Django sees is not HTTPS. Usually in these
-cases the proxy server provides an alternative header to indicate the secured
-external connection. This setting, if set, should be a tuple of ("header",
-"value"); if "header" is set to "value" in ``request.META``, django-secure will
-tell Django to consider it a secure request (in other words,
-``request.is_secure()`` will return ``True`` for this request). The "header"
-should be specified in the format it would be found in ``request.META``
-(e.g. "HTTP_X_FORWARDED_PROTOCOL", not "X-Forwarded-Protocol"). For example::
+ This setting is `built-in to Django 1.4+`_. The Django setting works
+ identically to this version.
+
+A tuple of ("header", "value"); if "header" is set to "value" in
+``request.META``, django-secure will tell Django to consider this a secure
+request. For example::
SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTOCOL", "https")
+See :ref:`proxied-ssl` for more details.
+
Defaults to ``None``.
.. warning::
@@ -132,7 +126,7 @@ Defaults to ``None``.
use a header that your proxy sets unconditionally, overriding any value from
the request.
-.. _this setting is available in Django 1.4: https://docs.djangoproject.com/en/dev/ref/settings/#secure-proxy-ssl-header
+.. _built-in to Django 1.4+: https://docs.djangoproject.com/en/dev/ref/settings/#secure-proxy-ssl-header
.. _SECURE_REDIRECT_EXEMPT:
Please sign in to comment.
Something went wrong with that request. Please try again.