Fixed #14261 - Added clickjacking protection (X-Frame-Options header)

Many thanks to rniemeyer for the patch!

git-svn-id: http://code.djangoproject.com/svn/django/trunk@16298 bcc190cf-cafb-0310-a4f2-bffc1f526a37

docs/index.txt

@@ -167,8 +167,9 @@ Other batteries included
     * :doc:`Admin site <ref/contrib/admin/index>` | :doc:`Admin actions <ref/contrib/admin/actions>` | :doc:`Admin documentation generator<ref/contrib/admin/admindocs>`
     * :doc:`Authentication <topics/auth>`
     * :doc:`Cache system <topics/cache>`
-    * :doc:`Conditional content processing <topics/conditional-view-processing>`
+    * :doc:`Clickjacking protection <ref/clickjacking>`
     * :doc:`Comments <ref/contrib/comments/index>` | :doc:`Moderation <ref/contrib/comments/moderation>` | :doc:`Custom comments <ref/contrib/comments/custom>`
+    * :doc:`Conditional content processing <topics/conditional-view-processing>`
     * :doc:`Content types <ref/contrib/contenttypes>`
     * :doc:`Cross Site Request Forgery protection <ref/contrib/csrf>`
     * :doc:`Cryptographic signing <topics/signing>`

docs/ref/clickjacking.txt

@@ -0,0 +1,126 @@
+========================
+Clickjacking Protection
+========================
+
+.. module:: django.middleware.clickjacking
+   :synopsis: Protects against Clickjacking
+
+The clickjacking middleware and decorators provide easy-to-use protection
+against `clickjacking`_.  This type of attack occurs when a malicious site
+tricks a user into clicking on a concealed element of another site which they
+have loaded in a hidden frame or iframe.
+
+.. versionadded:: 1.4
+   The clickjacking middleware and decorators were added.
+
+.. _clickjacking: http://en.wikipedia.org/wiki/Clickjacking
+
+An example of clickjacking
+==========================
+
+Suppose an online store has a page where a logged in user can click "Buy Now" to
+purchase an item. A user has chosen to stay logged into the store all the time
+for convenience. An attacker site might create an "I Like Ponies" button on one
+of their own pages, and load the store's page in a transparent iframe such that
+the "Buy Now" button is invisibly overlaid on the "I Like Ponies" button. If the
+user visits the attacker site and clicks "I Like Ponies" he will inadvertently
+click on the online store's "Buy Now" button and unknowningly purchase the item.
+
+Preventing clickjacking
+=======================
+
+Modern browsers honor the `X-Frame-Options`_ HTTP header that indicates whether
+or not a resource is allowed to load within a frame or iframe. If the response
+contains the header with a value of SAMEORIGIN then the browser will only load
+the resource in a frame if the request originated from the same site. If the
+header is set to DENY then the browser will block the resource from loading in a
+frame no matter which site made the request.
+
+.. _X-Frame-Options: https://developer.mozilla.org/en/The_X-FRAME-OPTIONS_response_header
+
+Django provides a few simple ways to include this header in responses from your
+site:
+
+1. A simple middleware that sets the header in all responses.
+
+2. A set of view decorators that can be used to override the middleware or to
+   only set the header for certain views.
+
+How to use it
+=============
+
+Setting X-Frame-Options for all responses
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To set the same X-Frame-Options value for all responses in your site, add
+``'django.middleware.clickjacking.XFrameOptionsMiddleware'`` to
+:setting:`MIDDLEWARE_CLASSES`::
+
+    MIDDLEWARE_CLASSES = (
+        ...
+        'django.middleware.clickjacking.XFrameOptionsMiddleware',
+        ...
+    )
+
+By default, the middleware will set the X-Frame-Options header to SAMEORIGIN for
+every outgoing ``HttpResponse``. If you want DENY instead, set the
+:setting:`X_FRAME_OPTIONS` setting::
+
+    X_FRAME_OPTIONS = 'DENY'
+
+When using the middleware there may be some views where you do **not** want the
+X-Frame-Options header set. For those cases, you can use a view decorator that
+tells the middleware to not set the header::
+
+    from django.http import HttpResponse
+    from django.views.decorators.clickjacking import xframe_options_exempt
+
+    @xframe_options_exempt
+    def ok_to_load_in_a_frame(request):
+        return HttpResponse("This page is safe to load in a frame on any site.")
+
+
+Setting X-Frame-Options per view
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To set the X-Frame-Options header on a per view basis, Django provides these
+decorators::
+
+    from django.http import HttpResponse
+    from django.views.decorators.clickjacking import xframe_options_deny
+    from django.views.decorators.clickjacking import xframe_options_sameorigin
+
+    @xframe_options_deny
+    def view_one(request):
+        return HttpResponse("I won't display in any frame!")
+
+    @xframe_options_sameorigin
+    def view_two(request):
+        return HttpResponse("Display in a frame if it's from the same origin as me.")
+
+Note that you can use the decorators in conjunction with the middleware. Use of
+a decorator overrides the middleware.
+
+Limitations
+===========
+
+The `X-Frame-Options` header will only protect against clickjacking in a modern
+browser. Older browsers will quietly ignore the header and need `other
+clickjacking prevention techniques`_.
+
+Browsers that support X-Frame-Options
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Internet Explorer 8+
+* Firefox	3.6.9+
+* Opera	10.5+
+* Safari	4+
+* Chrome	4.1+
+
+See also
+~~~~~~~~
+
+A `complete list`_ of browsers supporting X-Frame-Options.
+
+.. _complete list: https://developer.mozilla.org/en/The_X-FRAME-OPTIONS_response_header#Browser_compatibility
+.. _other clickjacking prevention techniques: http://en.wikipedia.org/wiki/Clickjacking#Prevention

docs/ref/index.txt

@@ -6,6 +6,7 @@ API Reference
    :maxdepth: 1
 
    authbackends
+   clickjacking
    contrib/index
    databases
    django-admin

docs/ref/middleware.txt

@@ -204,3 +204,16 @@ Middleware modules running inside it (coming later in the stack) will be under
 the same transaction control as the view functions.
 
 See the :doc:`transaction management documentation </topics/db/transactions>`.
+
+X-Frame-Options middleware
+--------------------------
+
+.. module:: django.middleware.clickjacking
+   :synopsis: Clickjacking protection
+
+.. class:: XFrameOptionsMiddleware
+
+.. versionadded:: 1.4
+   ``XFrameOptionsMiddleware`` was added.
+
+Simple :doc:`clickjacking protection via the X-Frame-Options header </ref/clickjacking/>`.

docs/ref/settings.txt

@@ -2023,6 +2023,17 @@ See :tfilter:`allowed date format strings <date>`. See also
 :setting:`DATE_FORMAT`, :setting:`DATETIME_FORMAT`, :setting:`TIME_FORMAT`
 and :setting:`MONTH_DAY_FORMAT`.
 
+.. setting:: X_FRAME_OPTIONS
+
+X_FRAME_OPTIONS
+---------------
+
+Default: ``'SAMEORIGIN'``
+
+The default value for the X-Frame-Options header used by
+:class:`~django.middleware.clickjacking.XFrameOptionsMiddleware`. See the
+:doc:`clickjacking protection </ref/clickjacking/>` documentation.
+
 Deprecated settings
 ===================
 

docs/releases/1.4.txt

@@ -55,6 +55,15 @@ signing in Web applications.
 
 See :doc:`cryptographic signing </topics/signing>` docs for more information.
 
+Simple clickjacking protection
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+We've added a middleware to provide easy protection against `clickjacking
+<http://en.wikipedia.org/wiki/Clickjacking>`_ using the X-Frame-Options
+header. It's not enabled by default for backwards compatibility reasons, but
+you'll almost certainly want to :doc:`enable it </ref/clickjacking/>` to help
+plug that security hole for browsers that support the header.
+
 ``reverse_lazy``
 ~~~~~~~~~~~~~~~~