From fa350e2f303572ee8f9a8302dda45a12288d3d95 Mon Sep 17 00:00:00 2001
From: Erik Romijn <eromijn@solidlinks.nl>
Date: Sun, 8 Mar 2015 12:34:55 +0100
Subject: Fixed #24464 -- Made built-in HTML template filter functions escape
 their input by default.

This may cause some backwards compatibility issues, but may also
resolve security issues in third party projects that fail to heed warnings
in our documentation.

Thanks Markus Holtermann for help with tests and docs.
---
 docs/howto/custom-template-tags.txt | 27 +++++++++++++++++++--------
 docs/releases/1.8.txt               | 20 ++++++++++++++++++++
 2 files changed, 39 insertions(+), 8 deletions(-)

(limited to 'docs')

diff --git a/docs/howto/custom-template-tags.txt b/docs/howto/custom-template-tags.txt
index 7bf698ae23..a340ac7b83 100644
--- a/docs/howto/custom-template-tags.txt
+++ b/docs/howto/custom-template-tags.txt
@@ -281,7 +281,9 @@ Template filter code falls into one of two situations:
    (If you don't specify this flag, it defaults to ``False``). This flag tells
    Django that your filter function wants to be passed an extra keyword
    argument, called ``autoescape``, that is ``True`` if auto-escaping is in
-   effect and ``False`` otherwise.
+   effect and ``False`` otherwise. It is recommended to set the default of the
+   ``autoescape`` parameter to ``True``, so that if you call the function
+   from Python code it will have escaping enabled by default.
 
    For example, let's write a filter that emphasizes the first character of
    a string::
@@ -293,7 +295,7 @@ Template filter code falls into one of two situations:
       register = template.Library()
 
       @register.filter(needs_autoescape=True)
-      def initial_letter_filter(text, autoescape=None):
+      def initial_letter_filter(text, autoescape=True):
           first, other = text[0], text[1:]
           if autoescape:
               esc = conditional_escape
@@ -323,9 +325,15 @@ Template filter code falls into one of two situations:
 
 .. warning:: Avoiding XSS vulnerabilities when reusing built-in filters
 
-    Be careful when reusing Django's built-in filters. You'll need to pass
-    ``autoescape=True`` to the filter in order to get the proper autoescaping
-    behavior and avoid a cross-site script vulnerability.
+    .. versionchanged:: 1.8
+
+    Django's built-in filters have ``autoescape=True`` by default in order to
+    get the proper autoescaping behavior and avoid a cross-site script
+    vulnerability.
+
+    In older versions of Django, be careful when reusing Django's built-in
+    filters as ``autoescape`` defaults to ``None``. You'll need to pass
+    ``autoescape=True`` to get autoescaping.
 
     For example, if you wanted to write a custom filter called
     ``urlize_and_linebreaks`` that combined the :tfilter:`urlize` and
@@ -333,9 +341,12 @@ Template filter code falls into one of two situations:
 
         from django.template.defaultfilters import linebreaksbr, urlize
 
-        @register.filter
-        def urlize_and_linebreaks(text):
-            return linebreaksbr(urlize(text, autoescape=True), autoescape=True)
+        @register.filter(needs_autoescape=True)
+        def urlize_and_linebreaks(text, autoescape=True):
+            return linebreaksbr(
+                urlize(text, autoescape=autoescape),
+                autoescape=autoescape
+            )
 
     Then:
 
diff --git a/docs/releases/1.8.txt b/docs/releases/1.8.txt
index a6fa0cb33e..bbbe97a881 100644
--- a/docs/releases/1.8.txt
+++ b/docs/releases/1.8.txt
@@ -1012,6 +1012,26 @@ those writing third-party backends in updating their code:
   now takes a second argument named ``obj_id`` which is the serialized
   identifier used to retrieve the object before deletion.
 
+Default autoescaping of functions in ``django.template.defaultfilters``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In order to make built-in template filters that output HTML "safe by default"
+when calling them in Python code, the following functions in
+``django.template.defaultfilters`` have been changed to automatically escape
+their input value:
+
+* ``join``
+* ``linebreaksbr``
+* ``linebreaks_filter``
+* ``linenumbers``
+* ``unordered_list``
+* ``urlize``
+* ``urlizetrunc``
+
+You can revert to the old behavior by specifying ``autoescape=False`` if you
+are passing trusted content. This change doesn't have any effect when using
+the corresponding filters in templates.
+
 Miscellaneous
 ~~~~~~~~~~~~~
 
-- 
cgit v1.3