From 53b2c3867b5720b2586f5b63978ca2835e7dfb5d Mon Sep 17 00:00:00 2001 From: Luke Plant Date: Tue, 3 Nov 2009 14:40:37 +0000 Subject: [PATCH] Fixed #12130 - documented need for csrf_protect on views that don't accept POST Includes: * proper documentation for csrf_protect * notes in comments app. * specific upgrade notes for comments app Thanks to carljm for report and debugging. git-svn-id: http://code.djangoproject.com/svn/django/trunk@11711 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- django/views/csrf.py | 5 +++++ docs/ref/contrib/comments/index.txt | 7 ++++++ docs/ref/contrib/csrf.txt | 34 ++++++++++++++++++++++++++--- 3 files changed, 43 insertions(+), 3 deletions(-) diff --git a/django/views/csrf.py b/django/views/csrf.py index 5bdcbd10a6..aa5e25b5b4 100644 --- a/django/views/csrf.py +++ b/django/views/csrf.py @@ -39,6 +39,11 @@ CSRF_FAILRE_TEMPLATE = """
  • In the template, there is a {% templatetag openblock %} csrf_token {% templatetag closeblock %} template tag inside each POST form that targets an internal URL.
    • + +
  • If you are not using CsrfViewMiddleware, then you must use + csrf_protect on any views that use the csrf_token + template tag, as well as those that accept the POST data.
    • +

    You're seeing the help section of this page because you have DEBUG = diff --git a/docs/ref/contrib/comments/index.txt b/docs/ref/contrib/comments/index.txt index 880be34101..6ee109782f 100644 --- a/docs/ref/contrib/comments/index.txt +++ b/docs/ref/contrib/comments/index.txt @@ -216,6 +216,13 @@ should know about: it with a warning field; if you use the comment form with a custom template you should be sure to do the same. +The comments app also depends on the more general :ref:`Cross Site Request +Forgery protection < ref-contrib-csrf>` that comes with Django. As described in +the documentation, it is best to use ``CsrfViewMiddleware``. However, if you +are not using that, you will need to use the ``csrf_protect`` decorator on any +views that include the comment form, in order for those views to be able to +output the CSRF token and cookie. + .. _honeypot: http://en.wikipedia.org/wiki/Honeypot_(computing) More information diff --git a/docs/ref/contrib/csrf.txt b/docs/ref/contrib/csrf.txt index 126df83676..c1bdb59cd1 100644 --- a/docs/ref/contrib/csrf.txt +++ b/docs/ref/contrib/csrf.txt @@ -44,9 +44,7 @@ To enable CSRF protection for your views, follow these steps: Alternatively, you can use the decorator ``django.views.decorators.csrf.csrf_protect`` on particular views you - want to protect. This is **not recommended** by itself, since if you - forget to use it, you will have a security hole. The 'belt and braces' - strategy of using both is fine, and will incur minimal overhead. + want to protect (see below). 2. In any template that uses a POST form, use the ``csrf_token`` tag inside the ``

    `` element if the form is for an internal URL, e.g.:: @@ -85,6 +83,30 @@ The utility script ``extras/csrf_migration_helper.py`` can help to automate the finding of code and templates that may need to be upgraded. It contains full help on how to use it. +The decorator method +-------------------- + +Rather than adding ``CsrfViewMiddleware`` as a blanket protection, you can use +the ``csrf_protect`` decorator, which has exactly the same functionality, on +particular views that need the protection. It must be used **both** on views +that insert the CSRF token in the output, and on those that accept the POST form +data. (These are often the same view function, but not always). It is used like +this:: + + from django.views.decorators.csrf import csrf_protect + from django.template import RequestContext + + @csrf_protect + def my_view(request): + c = {} + # ... + return render_to_response("a_template.html", c, + context_instance=RequestContext(request)) + +Use of the decorator is **not recommended** by itself, since if you forget to +use it, you will have a security hole. The 'belt and braces' strategy of using +both is fine, and will incur minimal overhead. + Legacy method ------------- @@ -182,6 +204,12 @@ above, or they will stop working. (If you cannot update these templates for some reason, you will be forced to use ``CsrfResponseMiddleware`` for these views to continue working). +Note also, if you are using the comments app, and you are not going to add +``CsrfViewMiddleware`` to your settings (not recommended), you will need to add +the ``csrf_protect`` decorator to any views that include the comment forms and +target the comment views (usually using the :ttag:`comment_form_target` template +tag). + Assuming you have followed the above, all views in your Django site will now be protected by the ``CsrfViewMiddleware``. Contrib apps meet the requirements imposed by the ``CsrfViewMiddleware`` using the template tag, and other