doc: Warn that ts_headline() output is not HTML-safe.

Add a documentation warning to ts_headline() pointing out that, when
working with untrusted input documents, the output is not guaranteed
to be safe for direct inclusion in web pages. This is because, while
it does remove some XML tags from the input, it doesn't remove all
HTML markup, and so the result may be unsafe (e.g., it might permit
XSS attacks).

To guard against that, all HTML markup should be removed from the
input, making it plain text, or the output should be passed through an
HTML sanitizer.

In addition, document precisely what the default text search parser
recognises as valid XML tags, since that's what determines which XML
tags ts_headline() will remove.

Reported-by: Richard Neill 
Author: Dean Rasheed 
Reviewed-by: Noah Misch 
Backpatch-through: 13

diff --git a/doc/src/sgml/textsearch.sgml b/doc/src/sgml/textsearch.sgml
index d171f8da8011650efcd59ab9be82d841e26b2782..908857a54af5f5bf2d4858797225d0a761562b0e 100644 (file)
--- a/doc/src/sgml/textsearch.sgml
+++ b/doc/src/sgml/textsearch.sgml
@@ -1342,7 +1342,7 @@ ts_headline( config 
        document, to distinguish them from other excerpted words.  The
        default values are <b> and
        </b>, which can be suitable
-       for HTML output.
+       for HTML output (but see the warning below).
       
      
      
@@ -1354,6 +1354,21 @@ ts_headline( config 
      
     
 
+    
+     Warning: Cross-site scripting (XSS) safety
+     
+      The output from ts_headline is not guaranteed to
+      be safe for direct inclusion in web pages. When
+      HighlightAll is false (the
+      default), some simple XML tags are removed from the document, but this
+      is not guaranteed to remove all HTML markup. Therefore, this does not
+      provide an effective defense against attacks such as cross-site
+      scripting (XSS) attacks, when working with untrusted input. To guard
+      against such attacks, all HTML markup should be removed from the input
+      document, or an HTML sanitizer should be used on the output.
+     
+    
+
     These option names are recognized case-insensitively.
     You must double-quote string values if they contain spaces or commas.
    
@@ -2225,6 +2240,18 @@ LIMIT 10;
     Specifically, the only non-alphanumeric characters supported for
     email user names are period, dash, and underscore.
    
+
+   
+    tag does not support all valid tag names as defined by
+    W3C Recommendation, XML.
+    Specifically, the only tag names supported are those starting with an
+    ASCII letter, underscore, or colon, and containing only letters, digits,
+    hyphens, underscores, periods, and colons. tag also
+    includes XML comments starting with <!-- and ending
+    with -->, and XML declarations (but note that this
+    includes anything starting with <?x and ending with
+    >).
+