From d3db878e4beff057400dd780c24f3601a5d31f95 Mon Sep 17 00:00:00 2001 From: Thomas Chaumeny Date: Fri, 31 Oct 2014 23:39:46 +0100 Subject: [PATCH] Moved CSRF docs out of contrib. --- docs/index.txt | 2 +- docs/ref/contrib/index.txt | 8 -------- docs/ref/{contrib => }/csrf.txt | 13 ++++++------- docs/ref/index.txt | 1 + docs/ref/middleware.txt | 2 +- docs/ref/settings.txt | 4 ++-- docs/ref/templates/api.txt | 2 +- docs/ref/templates/builtins.txt | 2 +- docs/releases/1.1.txt | 2 +- docs/releases/1.2.txt | 4 ++-- docs/releases/1.3.txt | 2 +- docs/releases/1.4.11.txt | 2 +- docs/releases/1.4.txt | 4 ++-- docs/releases/1.5.6.txt | 2 +- docs/releases/1.6.3.txt | 2 +- docs/topics/forms/index.txt | 4 ++-- 16 files changed, 24 insertions(+), 32 deletions(-) rename docs/ref/{contrib => }/csrf.txt (97%) diff --git a/docs/index.txt b/docs/index.txt index 1c2a483eca..9aaf5e181d 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -227,7 +227,7 @@ applications and Django provides multiple protection tools and mechanisms: * :doc:`Security overview ` * :doc:`Disclosed security issues in Django ` * :doc:`Clickjacking protection ` -* :doc:`Cross Site Request Forgery protection ` +* :doc:`Cross Site Request Forgery protection ` * :doc:`Cryptographic signing ` * :ref:`Security Middleware ` diff --git a/docs/ref/contrib/index.txt b/docs/ref/contrib/index.txt index ebfc2874b4..a4787f8643 100644 --- a/docs/ref/contrib/index.txt +++ b/docs/ref/contrib/index.txt @@ -25,7 +25,6 @@ those packages have. admin/index auth contenttypes - csrf flatpages formtools/index gis/index @@ -63,13 +62,6 @@ Django model is a separate content type. See the :doc:`contenttypes documentation `. -csrf -==== - -A middleware for preventing Cross Site Request Forgeries - -See the :doc:`csrf documentation `. - flatpages ========= diff --git a/docs/ref/contrib/csrf.txt b/docs/ref/csrf.txt similarity index 97% rename from docs/ref/contrib/csrf.txt rename to docs/ref/csrf.txt index ac6c55a74c..9e682ec6ae 100644 --- a/docs/ref/contrib/csrf.txt +++ b/docs/ref/csrf.txt @@ -26,15 +26,14 @@ below. How to use it ============= -To enable CSRF protection for your views, follow these steps: +To take advantage of CSRF protection in your views, follow these steps: -1. Add the middleware - ``'django.middleware.csrf.CsrfViewMiddleware'`` to your list of - middleware classes, :setting:`MIDDLEWARE_CLASSES`. (It should come - before any view middleware that assume that CSRF attacks have - been dealt with.) +1. The CSRF middleware is activated by default in the + :setting:`MIDDLEWARE_CLASSES` setting. If you override that setting, remember + that ``'django.middleware.csrf.CsrfViewMiddleware'`` should come before any + view middleware that assume that CSRF attacks have been dealt with. - Alternatively, you can use the decorator + If you disabled it, which is not recommended, you can use :func:`~django.views.decorators.csrf.csrf_protect` on particular views you want to protect (see below). diff --git a/docs/ref/index.txt b/docs/ref/index.txt index 8aef2e9964..b81d8dd7d4 100644 --- a/docs/ref/index.txt +++ b/docs/ref/index.txt @@ -10,6 +10,7 @@ API Reference class-based-views/index clickjacking contrib/index + csrf databases django-admin exceptions diff --git a/docs/ref/middleware.txt b/docs/ref/middleware.txt index eea2d94a84..3ba7d52b9d 100644 --- a/docs/ref/middleware.txt +++ b/docs/ref/middleware.txt @@ -388,7 +388,7 @@ CSRF protection middleware Adds protection against Cross Site Request Forgeries by adding hidden form fields to POST forms and checking requests for the correct value. See the -:doc:`Cross Site Request Forgery protection documentation `. +:doc:`Cross Site Request Forgery protection documentation `. X-Frame-Options middleware -------------------------- diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index 3fd1c44ce5..90f6e1e147 100644 --- a/docs/ref/settings.txt +++ b/docs/ref/settings.txt @@ -374,7 +374,7 @@ CSRF_COOKIE_NAME Default: ``'csrftoken'`` The name of the cookie to use for the CSRF authentication token. This can be whatever you -want. See :doc:`/ref/contrib/csrf`. +want. See :doc:`/ref/csrf`. .. setting:: CSRF_COOKIE_PATH @@ -415,7 +415,7 @@ is rejected by the CSRF protection. The function should have this signature:: where ``reason`` is a short message (intended for developers or logging, not for end users) indicating the reason the request was rejected. See -:doc:`/ref/contrib/csrf`. +:doc:`/ref/csrf`. .. setting:: DATABASES diff --git a/docs/ref/templates/api.txt b/docs/ref/templates/api.txt index ac6c18fe79..08e001b039 100644 --- a/docs/ref/templates/api.txt +++ b/docs/ref/templates/api.txt @@ -576,7 +576,7 @@ django.core.context_processors.csrf This processor adds a token that is needed by the :ttag:`csrf_token` template tag for protection against :doc:`Cross Site Request Forgeries -`. +`. django.core.context_processors.request ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt index e9c2e0c391..fe9127bea5 100644 --- a/docs/ref/templates/builtins.txt +++ b/docs/ref/templates/builtins.txt @@ -70,7 +70,7 @@ csrf_token ^^^^^^^^^^ This tag is used for CSRF protection, as described in the documentation for -:doc:`Cross Site Request Forgeries `. +:doc:`Cross Site Request Forgeries `. .. templatetag:: cycle diff --git a/docs/releases/1.1.txt b/docs/releases/1.1.txt index 2788f1fded..38212615cc 100644 --- a/docs/releases/1.1.txt +++ b/docs/releases/1.1.txt @@ -372,7 +372,7 @@ Other improvements Other new features and changes introduced since Django 1.0 include: -* The :doc:`CSRF protection middleware ` has been split into +* The :doc:`CSRF protection middleware ` has been split into two classes -- ``CsrfViewMiddleware`` checks incoming requests, and ``CsrfResponseMiddleware`` processes outgoing responses. The combined ``CsrfMiddleware`` class (which does both) remains for diff --git a/docs/releases/1.2.txt b/docs/releases/1.2.txt index e59fb075c9..35ddde301a 100644 --- a/docs/releases/1.2.txt +++ b/docs/releases/1.2.txt @@ -141,7 +141,7 @@ Improved CSRF protection ------------------------ Django now has much improved protection against :doc:`Cross-Site Request Forgery -(CSRF) attacks`. This type of attack occurs when a malicious +(CSRF) attacks`. This type of attack occurs when a malicious Web site contains a link, a form button or some JavaScript that is intended to perform some action on your Web site, using the credentials of a logged-in user who visits the malicious site in their browser. A related type of attack, "login @@ -426,7 +426,7 @@ CSRF Protection --------------- We've made large changes to the way CSRF protection works, detailed in -:doc:`the CSRF documentation `. Here are the major changes you +:doc:`the CSRF documentation `. Here are the major changes you should be aware of: * ``CsrfResponseMiddleware`` and ``CsrfMiddleware`` have been deprecated and diff --git a/docs/releases/1.3.txt b/docs/releases/1.3.txt index 9c1baff8ab..1a18a2d862 100644 --- a/docs/releases/1.3.txt +++ b/docs/releases/1.3.txt @@ -341,7 +341,7 @@ Prior to Django 1.2.5, Django's CSRF-prevention system exempted AJAX requests from CSRF verification; due to `security issues`_ reported to us, however, *all* requests are now subjected to CSRF verification. Consult :doc:`the Django CSRF documentation -` for details on how to handle CSRF verification in +` for details on how to handle CSRF verification in AJAX requests. .. _security issues: https://www.djangoproject.com/weblog/2011/feb/08/security/ diff --git a/docs/releases/1.4.11.txt b/docs/releases/1.4.11.txt index 24194540d5..8cfcdbaeed 100644 --- a/docs/releases/1.4.11.txt +++ b/docs/releases/1.4.11.txt @@ -52,7 +52,7 @@ Caching of anonymous pages could reveal CSRF token Django includes both a :doc:`caching framework ` and a system for :doc:`preventing cross-site request forgery (CSRF) attacks -`. The CSRF-protection system is based on a random nonce +`. The CSRF-protection system is based on a random nonce sent to the client in a cookie which must be sent by the client on future requests and, in forms, a hidden value which must be submitted back with the form. diff --git a/docs/releases/1.4.txt b/docs/releases/1.4.txt index b04f8eb4c3..5b10f4c428 100644 --- a/docs/releases/1.4.txt +++ b/docs/releases/1.4.txt @@ -499,7 +499,7 @@ We've made various improvements to our CSRF features, including the help with AJAX-heavy sites; protection for PUT and DELETE requests; and the :setting:`CSRF_COOKIE_SECURE` and :setting:`CSRF_COOKIE_PATH` settings, which can improve the security and usefulness of CSRF protection. See the :doc:`CSRF -docs ` for more information. +docs ` for more information. Error report filtering ~~~~~~~~~~~~~~~~~~~~~~ @@ -996,7 +996,7 @@ expression, such as periods. CSRF protection extended to PUT and DELETE ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Previously, Django's :doc:`CSRF protection ` provided +Previously, Django's :doc:`CSRF protection ` provided protection only against POST requests. Since use of PUT and DELETE methods in AJAX applications is becoming more common, we now protect all methods not defined as safe by :rfc:`2616` -- i.e., we exempt GET, HEAD, OPTIONS and TRACE, diff --git a/docs/releases/1.5.6.txt b/docs/releases/1.5.6.txt index 1410d143c8..3bffb1c7ad 100644 --- a/docs/releases/1.5.6.txt +++ b/docs/releases/1.5.6.txt @@ -51,7 +51,7 @@ Caching of anonymous pages could reveal CSRF token Django includes both a :doc:`caching framework ` and a system for :doc:`preventing cross-site request forgery (CSRF) attacks -`. The CSRF-protection system is based on a random nonce +`. The CSRF-protection system is based on a random nonce sent to the client in a cookie which must be sent by the client on future requests and, in forms, a hidden value which must be submitted back with the form. diff --git a/docs/releases/1.6.3.txt b/docs/releases/1.6.3.txt index d06a9d44df..791f73faa1 100644 --- a/docs/releases/1.6.3.txt +++ b/docs/releases/1.6.3.txt @@ -51,7 +51,7 @@ Caching of anonymous pages could reveal CSRF token Django includes both a :doc:`caching framework ` and a system for :doc:`preventing cross-site request forgery (CSRF) attacks -`. The CSRF-protection system is based on a random nonce +`. The CSRF-protection system is based on a random nonce sent to the client in a cookie which must be sent by the client on future requests and, in forms, a hidden value which must be submitted back with the form. diff --git a/docs/topics/forms/index.txt b/docs/topics/forms/index.txt index 215b0d74c2..c20acde52f 100644 --- a/docs/topics/forms/index.txt +++ b/docs/topics/forms/index.txt @@ -81,7 +81,7 @@ or for binary data, such as an image. A Web application that uses ``GET`` requests for admin forms is a security risk: it can be easy for an attacker to mimic a form's request to gain access to sensitive parts of the system. ``POST``, coupled with other protections like Django's :doc:`CSRF protection -` offers more control over access. +` offers more control over access. On the other hand, ``GET`` is suitable for things like a web search form, because the URLs that represent a ``GET`` request can easily be bookmarked, @@ -335,7 +335,7 @@ from that ``{{ form }}`` by Django's template language. .. admonition:: Forms and Cross Site Request Forgery protection Django ships with an easy-to-use :doc:`protection against Cross Site Request - Forgeries `. When submitting a form via ``POST`` with + Forgeries `. When submitting a form via ``POST`` with CSRF protection enabled you must use the :ttag:`csrf_token` template tag as in the preceding example. However, since CSRF protection is not directly tied to forms in templates, this tag is omitted from the