docs/csrf.txt

   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 POST
  45 forms). GET requests ought never to have any potentially dangerous side
  46 effects (see `9.1.1 Safe Methods, HTTP 1.1, RFC 2616`_), and so a
  47 CSRF attack with a GET request ought to 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 .. _9.1.1 Safe Methods, HTTP 1.1, RFC 2616: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html
  58
  59 Limitations
  60 ===========
  61
  62 CsrfMiddleware requires Django's session framework to work. If you have
  63 a custom authentication system that manually sets cookies and the like,
  64 it won't help you.
  65
  66 If your app creates HTML pages and forms in some unusual way, (e.g.
  67 it sends fragments of HTML in javascript document.write statements)
  68 you might bypass the filter that adds the hidden field to the form,
  69 in which case form submission will always fail.  It may still be possible
  70 to use the middleware, provided you can find some way to get the
  71 CSRF token and ensure that is included when your form is submitted.