Added CsrfMiddleware to contrib, and documentation.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@2868 bcc190cf-cafb-0310-a4f2-bffc1f526a37

2 files changed, 78 insertions, 0 deletions

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.
+