|
1 ===================================== |
|
2 Cross Site Request Forgery protection |
|
3 ===================================== |
|
4 |
|
5 The CsrfMiddleware class provides easy-to-use protection against |
|
6 `Cross Site Request Forgeries`_. This type of attack occurs when a malicious |
|
7 web site creates a link or form button that is intended to perform some action |
|
8 on your web site, using the credentials of a logged-in user who is tricked |
|
9 into clicking on the link in their browser. |
|
10 |
|
11 The first defense against CSRF attacks is to ensure that GET requests |
|
12 are side-effect free. POST requests can then be protected by adding this |
|
13 middleware into your list of installed middleware. |
|
14 |
|
15 .. _Cross Site Request Forgeries: http://www.squarefree.com/securitytips/web-developers.html#CSRF |
|
16 |
|
17 How to use it |
|
18 ============= |
|
19 |
|
20 Add the middleware ``'django.contrib.csrf.middleware.CsrfMiddleware'`` to |
|
21 your list of middleware classes, ``MIDDLEWARE_CLASSES``. It needs to process |
|
22 the response after the SessionMiddleware, so must come before it in the |
|
23 list. It also must process the response before things like compression |
|
24 happen to the response, so it must come after GZipMiddleware in the list. |
|
25 |
|
26 How it works |
|
27 ============ |
|
28 |
|
29 CsrfMiddleware does two things: |
|
30 |
|
31 1. It modifies outgoing requests by adding a hidden form field to all |
|
32 'POST' forms, with the name 'csrfmiddlewaretoken' and a value which is |
|
33 a hash of the session ID plus a secret. If there is no session ID set, |
|
34 this modification of the response isn't done, so there is very little |
|
35 performance penalty for those requests that don't have a session. |
|
36 |
|
37 2. On all incoming POST requests that have the session cookie set, it |
|
38 checks that the 'csrfmiddlewaretoken' is present and correct. If it |
|
39 isn't, the user will get a 403 error. |
|
40 |
|
41 This ensures that only forms that have originated from your web site |
|
42 can be used to POST data back. |
|
43 |
|
44 It deliberately only targets HTTP POST requests (and the corresponding |
|
45 POST forms). GET requests ought never to have side effects (if you are |
|
46 using HTTP GET and POST correctly), and so a CSRF attack with a GET |
|
47 request will always be harmless. |
|
48 |
|
49 POST requests that are not accompanied by a session cookie are not protected, |
|
50 but they do not need to be protected, since the 'attacking' web site |
|
51 could make these kind of requests anyway. |
|
52 |
|
53 The Content-Type is checked before modifying the response, and only |
|
54 pages that are served as 'text/html' or 'application/xml+xhtml' |
|
55 are modified. |
|
56 |
|
57 Limitations |
|
58 =========== |
|
59 |
|
60 CsrfMiddleware requires Django's session framework to work. If you have |
|
61 a custom authentication system that manually sets cookies and the like, |
|
62 it won't help you. |
|
63 |
|
64 If your app creates HTML pages and forms in some unusual way, (e.g. |
|
65 it sends fragments of HTML in javascript document.write statements) |
|
66 you might bypass the filter that adds the hidden field to the form, |
|
67 in which case form submission will always fail. It may still be possible |
|
68 to use the middleware, provided you can find some way to get the |
|
69 CSRF token and ensure that is included when your form is submitted. |