From 8eecb95ec8824f8e6ce89fa7a96e094db906a0f5 Mon Sep 17 00:00:00 2001 From: Luke Plant Date: Mon, 8 May 2006 23:03:08 +0000 Subject: Added CsrfMiddleware to contrib, and documentation. git-svn-id: http://code.djangoproject.com/svn/django/trunk@2868 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/add_ons.txt | 10 +++++++++ docs/csrf.txt | 68 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 78 insertions(+) create mode 100644 docs/csrf.txt (limited to 'docs') diff --git a/docs/add_ons.txt b/docs/add_ons.txt index e602e429ad..28df4f55b6 100644 --- a/docs/add_ons.txt +++ b/docs/add_ons.txt @@ -57,6 +57,16 @@ See the `syndication documentation`_. .. _syndication documentation: http://www.djangoproject.com/documentation/syndication/ +csrf +==== + +A middleware for preventing Cross Site Request Forgeries + +See the `csrf documentation`_. + +.. _csrf documentation: http://www.djangoproject.com/documentation/csrf/ + + Other add-ons ============= diff --git a/docs/csrf.txt b/docs/csrf.txt new file mode 100644 index 0000000000..4ea09552fc --- /dev/null +++ b/docs/csrf.txt @@ -0,0 +1,68 @@ +===================================== +Cross Site Request Forgery Protection +===================================== + +The CsrfMiddleware class provides easy-to-use protection against +`Cross Site Request Forgeries`_. This type of attack occurs when a malicious +web site creates a link or form button that is intended to perform some action +on your web site, using the credentials of a logged-in user who is tricked +into clicking on the link in their browser. + +The first defense against CSRF attacks is to ensure that GET requests +are side-effect free. POST requests can then be protected by adding this +middleware into your list of installed middleware. + + +.. _Cross Site Request Forgeries: http://www.squarefree.com/securitytips/web-developers.html#CSRF + +How to use it +============= +Add the middleware ``"django.contrib.csrf.middleware.CsrfMiddleware"`` to +your list of middleware classes, ``MIDDLEWARE_CLASSES``. It needs to process +the response after the SessionMiddleware, so must come before it in the +list. It also must process the response before things like compression +happen to the response, so it must come after GZipMiddleware in the list. + +How it works +============ +CsrfMiddleware does two things: + +1. It modifies outgoing requests by adding a hidden form field to all + 'POST' forms, with the name 'csrfmiddlewaretoken' and a value which is + a hash of the session ID plus a secret. If there is no session ID set, + this modification of the response isn't done, so there is very little + performance penalty for those requests that don't have a session. + +2. On all incoming POST requests that have the session cookie set, it + checks that the 'csrfmiddlewaretoken' is present and correct. If it + isn't, the user will get a 403 error. + +This ensures that only forms that have originated from your web site +can be used to POST data back. + +It deliberately only targets HTTP POST requests (and the corresponding +POST forms). GET requests ought never to have side effects (if you are +using HTTP GET and POST correctly), and so a CSRF attack with a GET +request will always be harmless. + +POST requests that are not accompanied by a session cookie are not protected, +but they do not need to be protected, since the 'attacking' web site +could make these kind of requests anyway. + +The Content-Type is checked before modifying the response, and only +pages that are served as 'text/html' or 'application/xml+xhtml' +are modified. + +Limitations +=========== +CsrfMiddleware requires Django's session framework to work. If you have +a custom authentication system that manually sets cookies and the like, +it won't help you. + +If your app creates HTML pages and forms in some unusual way, (e.g. +it sends fragments of HTML in javascript document.write statements) +you might bypass the filter that adds the hidden field to the form, +in which case form submission will always fail. It may still be possible +to use the middleware, provided you can find some way to get the +CSRF token and ensure that is included when your form is submitted. + -- cgit v1.3