Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Add section about proxy SSL headers in middleware doc.

  • Loading branch information...
commit f6441061a1706e0ba8bbc25fa29f6d076902503b 1 parent 0251c3d
Carl Meyer authored

Showing 2 changed files with 53 additions and 16 deletions. Show diff stats Hide diff stats

  1. +44 1 doc/middleware.rst
  2. +9 15 doc/settings.rst
45 doc/middleware.rst
Source Rendered
... ... @@ -1,12 +1,13 @@
1 1 SecurityMiddleware
2 2 ==================
3 3
4   -The ``djangosecure.middleware.SecurityMiddleware`` performs five different
  4 +The ``djangosecure.middleware.SecurityMiddleware`` performs six different
5 5 tasks for you. Each one can be independently enabled or disabled with a
6 6 setting.
7 7
8 8 .. contents:: :local:
9 9
  10 +
10 11 .. _x-frame-options:
11 12
12 13 X-Frame-Options: DENY
@@ -44,6 +45,7 @@ at all, decorate the view with the ``frame_deny_exempt`` decorator::
44 45 .. _Clickjacking: http://www.sectheory.com/clickjacking.htm
45 46 .. _its own middleware and setting: https://docs.djangoproject.com/en/dev/ref/clickjacking/
46 47
  48 +
47 49 .. _http-strict-transport-security:
48 50
49 51 HTTP Strict Transport Security
@@ -82,6 +84,7 @@ may still be vulnerable via an insecure connection to a subdomain.
82 84
83 85 .. _"Strict-Transport-Security" header: http://en.wikipedia.org/wiki/Strict_Transport_Security
84 86
  87 +
85 88 .. _x-content-type-options:
86 89
87 90 X-Content-Type-Options: nosniff
@@ -107,6 +110,7 @@ is ``True``.
107 110
108 111 .. _IE Security Blog: http://blogs.msdn.com/b/ie/archive/2008/09/02/ie8-security-part-vi-beta-2-update.aspx
109 112
  113 +
110 114 .. _x-xss-protection:
111 115
112 116 X-XSS-Protection: 1; mode=block
@@ -135,6 +139,7 @@ header. ``SecurityMiddleware`` will do this for all responses if the
135 139 .. _XSS attack: http://en.wikipedia.org/wiki/Cross-site_scripting
136 140 .. _X-XSS-Protection header: http://blogs.msdn.com/b/ie/archive/2008/07/02/ie8-security-part-iv-the-xss-filter.aspx
137 141
  142 +
138 143 .. _ssl-redirect:
139 144
140 145 SSL Redirect
@@ -168,3 +173,41 @@ in the :ref:`SECURE_REDIRECT_EXEMPT` setting.
168 173 may need to set the :ref:`SECURE_PROXY_SSL_HEADER` setting.
169 174
170 175 .. _nginx: http://nginx.org
  176 +
  177 +
  178 +.. _proxied-ssl:
  179 +
  180 +Detecting proxied SSL
  181 +---------------------
  182 +
  183 +.. note::
  184 +
  185 + `Django 1.4+ offers the same functionality`_ built-in. The Django setting
  186 + works identically to this version.
  187 +
  188 +In some deployment scenarios, Django's ``request.is_secure()`` method returns
  189 +``False`` even on requests that are actually secure, because the HTTPS
  190 +connection is made to a front-end loadbalancer or reverse-proxy, and the
  191 +internal proxied connection that Django sees is not HTTPS. Usually in these
  192 +cases the proxy server provides an alternative header to indicate the secured
  193 +external connection.
  194 +
  195 +If this is your situation, you can set the :ref:`SECURE_PROXY_SSL_HEADER`
  196 +setting to a tuple of ("header", "value"); if "header" is set to "value" in
  197 +``request.META``, django-secure will tell Django to consider it a secure
  198 +request (in other words, ``request.is_secure()`` will return ``True`` for this
  199 +request). The "header" should be specified in the format it would be found in
  200 +``request.META`` (e.g. "HTTP_X_FORWARDED_PROTOCOL", not
  201 +"X-Forwarded-Protocol"). For example::
  202 +
  203 + SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTOCOL", "https")
  204 +
  205 +.. warning::
  206 +
  207 + If you set this to a header that your proxy allows through from the request
  208 + unmodified (i.e. a header that can be spoofed), you are allowing an attacker
  209 + to pretend that any request is secure, even if it is not. Make sure you only
  210 + use a header that your proxy sets unconditionally, overriding any value from
  211 + the request.
  212 +
  213 +.. _Django 1.4+ offers the same functionality: https://docs.djangoproject.com/en/dev/ref/settings/#secure-proxy-ssl-header
24 doc/settings.rst
Source Rendered
@@ -105,23 +105,17 @@ SECURE_PROXY_SSL_HEADER
105 105
106 106 .. note::
107 107
108   - As of Dec. 16, 2011, `this setting is available in Django 1.4`_ proper. The
109   - official Django setting works identically to this version.
110   -
111   -In some deployment scenarios, Django's ``request.is_secure()`` method returns
112   -``False`` even on requests that are actually secure, because the HTTPS
113   -connection is made to a front-end loadbalancer or reverse-proxy, and the
114   -internal proxied connection that Django sees is not HTTPS. Usually in these
115   -cases the proxy server provides an alternative header to indicate the secured
116   -external connection. This setting, if set, should be a tuple of ("header",
117   -"value"); if "header" is set to "value" in ``request.META``, django-secure will
118   -tell Django to consider it a secure request (in other words,
119   -``request.is_secure()`` will return ``True`` for this request). The "header"
120   -should be specified in the format it would be found in ``request.META``
121   -(e.g. "HTTP_X_FORWARDED_PROTOCOL", not "X-Forwarded-Protocol"). For example::
  108 + This setting is `built-in to Django 1.4+`_. The Django setting works
  109 + identically to this version.
  110 +
  111 +A tuple of ("header", "value"); if "header" is set to "value" in
  112 +``request.META``, django-secure will tell Django to consider this a secure
  113 +request. For example::
122 114
123 115 SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTOCOL", "https")
124 116
  117 +See :ref:`proxied-ssl` for more details.
  118 +
125 119 Defaults to ``None``.
126 120
127 121 .. warning::
@@ -132,7 +126,7 @@ Defaults to ``None``.
132 126 use a header that your proxy sets unconditionally, overriding any value from
133 127 the request.
134 128
135   -.. _this setting is available in Django 1.4: https://docs.djangoproject.com/en/dev/ref/settings/#secure-proxy-ssl-header
  129 +.. _built-in to Django 1.4+: https://docs.djangoproject.com/en/dev/ref/settings/#secure-proxy-ssl-header
136 130
137 131
138 132 .. _SECURE_REDIRECT_EXEMPT:

0 comments on commit f644106

Please sign in to comment.
Something went wrong with that request. Please try again.