← Back to branch summary

~ubuntu-branches/ubuntu/quantal/python-django/quantal

« back to all changes in this revision

Viewing changes to docs/ref/contrib/csrf.txt

  • Committer: Bazaar Package Importer
  • Author(s): Chris Lamb
  • Date: 2009-07-29 11:26:28 UTC
  • mfrom: (1.1.8 upstream) (4.1.5 sid)
  • Revision ID: james.westby@ubuntu.com-20090729112628-pg09ino8sz0sj21t
Tags: 1.1-1
http://bugs.debian.org/538863
* New upstream release.
* Merge from experimental:
  - Ship FastCGI initscript and /etc/default file in python-django's examples
    directory (Closes: #538863)
  - Drop "05_10539-sphinx06-compatibility.diff"; it has been applied
    upstream.
  - Bump Standards-Version to 3.8.2.

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/ref/contrib/csrf.txt
26
26
your list of middleware classes, :setting:`MIDDLEWARE_CLASSES`. It needs to process
27
27
the response after the SessionMiddleware, so must come before it in the
28
28
list. It also must process the response before things like compression
29
 
happen to the response, so it must come after GZipMiddleware in the list.
 
29
happen to the response, so it must come after GZipMiddleware in the
 
30
list.
 
31
 
 
32
The ``CsrfMiddleware`` class is actually composed of two middleware:
 
33
``CsrfViewMiddleware`` which performs the checks on incoming requests,
 
34
and ``CsrfResponseMiddleware`` which performs post-processing of the
 
35
result.  This allows the individual components to be used and/or
 
36
replaced instead of using ``CsrfMiddleware``.
 
37
 
 
38
.. versionchanged:: 1.1
 
39
    (previous versions of Django did not provide these two components
 
40
    of ``CsrfMiddleware`` as described above)
 
41
 
 
42
Exceptions
 
43
----------
 
44
 
 
45
.. versionadded:: 1.1
 
46
 
 
47
To manually exclude a view function from being handled by the
 
48
CsrfMiddleware, you can use the ``csrf_exempt`` decorator, found in
 
49
the ``django.contrib.csrf.middleware`` module. For example::
 
50
 
 
51
    from django.contrib.csrf.middleware import csrf_exempt
 
52
 
 
53
    def my_view(request):
 
54
        return HttpResponse('Hello world')
 
55
    my_view = csrf_exempt(my_view)
 
56
 
 
57
Like the middleware itself, the ``csrf_exempt`` decorator is composed
 
58
of two parts: a ``csrf_view_exempt`` decorator and a
 
59
``csrf_response_exempt`` decorator, found in the same module.  These
 
60
disable the view protection mechanism (``CsrfViewMiddleware``) and the
 
61
response post-processing (``CsrfResponseMiddleware``) respectively.
 
62
They can be used individually if required.
 
63
 
 
64
You don't have to worry about doing this for most AJAX views. Any
 
65
request sent with "X-Requested-With: XMLHttpRequest" is automatically
 
66
exempt. (See the next section.)
30
67
 
31
68
How it works
32
69
============
38
75
   a hash of the session ID plus a secret. If there is no session ID set,
39
76
   this modification of the response isn't done, so there is very little
40
77
   performance penalty for those requests that don't have a session.
 
78
   (This is done by ``CsrfResponseMiddleware``).
41
79
 
42
80
2. On all incoming POST requests that have the session cookie set, it
43
81
   checks that the 'csrfmiddlewaretoken' is present and correct. If it
44
 
   isn't, the user will get a 403 error.
 
82
   isn't, the user will get a 403 error. (This is done by
 
83
   ``CsrfViewMiddleware``)
45
84
 
46
85
This ensures that only forms that have originated from your Web site
47
86
can be used to POST data back.
59
98
pages that are served as 'text/html' or 'application/xml+xhtml'
60
99
are modified.
61
100
 
 
101
The middleware tries to be smart about requests that come in via AJAX. Many
 
102
JavaScript toolkits send an "X-Requested-With: XMLHttpRequest" HTTP header;
 
103
these requests are detected and automatically *not* handled by this middleware.
 
104
We can do this safely because, in the context of a browser, the header can only
 
105
be added by using ``XMLHttpRequest``, and browsers already implement a
 
106
same-domain policy for ``XMLHttpRequest``. (Note that this is not secure if you
 
107
don't trust content within the same domain or subdomains.)
 
108
 
 
109
 
62
110
.. _9.1.1 Safe Methods, HTTP 1.1, RFC 2616: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html
63
111
 
64
112
Limitations
73
121
you might bypass the filter that adds the hidden field to the form,
74
122
in which case form submission will always fail.  It may still be possible
75
123
to use the middleware, provided you can find some way to get the
76
 
CSRF token and ensure that is included when your form is submitted.
 
 
b'\\ No newline at end of file'
 
124
CSRF token and ensure that is included when your form is submitted.