Issue 6626 - Document the rewrite filter option

pages/filters.html

 title=Writing Adblock Plus filters
 
 
 <p>{{s1 Current Adblock Plus versions allow you to "tweak" your filters in many different ways. This document explains the choices that you have and how they can be used.}}</p>
 
   <p>{{s2 <em>Disclaimer</em>: All filter examples given here are really only examples and are not meant to be used.}}</p>
 
   <h2 id="introduction">{{s3 Introduction to Adblock Plus filters}}</h2>
 
   <p>{{s4 The options described in this section should be enough for users who have to create a filter occasionally.}}</p>
@@ skipping 152 matching lines @@
       {{deprecated-options The type options <code><fix>background</fix></code>,
       <code><fix>xbl</fix></code> and <code><fix>dtd</fix></code> are outdated
       and should no longer be used.}}
     </li>
     <li>{{s69 Inverse type options: specify the element types the filter should <strong>not</strong> be applied to. Possible inverse type options: <code><fix>~script</fix></code>, <code><fix>~image</fix></code>, <code><fix>~stylesheet</fix></code>, <code><fix>~object</fix></code>, <code><fix>~xmlhttprequest</fix></code>, <code><fix>~object-subrequest</fix></code>, <code><fix>~subdocument</fix></code>, <code><fix>~document</fix></code>, <code><fix>~elemhide</fix></code>, <code><fix>~other</fix></code>}}</li>
     <li>{{s70 Restriction to third-party/first-party requests: If the <code><fix>third-party</fix></code> option is specified, the filter is only applied to requests from a different origin than the currently viewed page. Similarly, <code><fix>~third-party</fix></code> restricts the filter to requests from the same origin as the currently viewed page.}}</li>
     <li>{{s71 Domain restrictions: The option <code><fix>domain=example.com</fix></code> means that the filter should only be applied on pages from "example.com" domain. Multiple domains can be specified using "|" as separator: with the option <code><fix>domain=example.com|example.net</fix></code> the filter will only be applied on pages from "example.com" or "example.net" domains. If a domain name is preceded with "~", the filter should <strong>not</strong> be applied on pages from this domain. For example, <code><fix>domain=~example.com</fix></code> means that the filter should be applied on pages from any domain but "example.com" and <code><fix>domain=example.com|~foo.example.com</fix></code> restricts the filter to the "example.com" domain with the exception of "foo.example.com" subdomain.}}</li>
     <li>
       {{s72 Sitekey restrictions: The option <code><fix>sitekey=abcdsitekeydcba</fix></code> means that the filter should only be applied on pages that provide a public key and a signature which can be verified by that very same public key that is also contained in the filter (but without the trailing =). Multiple sitekeys can be specified using "|" as separator: with the option <code><fix>sitekey=abcdsitekeydcba|bcdesitekeyedcb</fix></code> the filter will only be applied on pages providing either sitekey "abcdsitekeydcba" or "bcdesitekeyedcb". This is similar to domain restrictions but allows covering scenarios where a single filter should apply to a very large number of domains. Note that sitekey restrictions require <a href="#sitekey_server">modifications on the server-side</a>.}}
     </li>
+    <li>
+      {{csp Content Security Policies: The option <code><fix>csp=script-src: 'none'</fix></code> causes a Content Security Policy header of <code><fix>script-src: 'none'</fix></code> to be injected into HTTP responses for requested documents matching the filter — assuming that exception rules with the same option don't also match and that the document isn’t whitelisted. The Content Security Policy <code><fix>script-src: 'none'</fix></code> would in turn block all scripts — including inline — for the document. This filter option should generally be avoided, except as a last resort to counter advanced circumvention. (Adblock Plus 3.1 or higher required.)}}
+    </li>
     <li>{{s73 <code><fix>match-case</fix></code> — makes the filter only apply to addresses with matching letter case, e.g. the filter <code><fix>*/BannerAd.gif$match-case</fix></code> will block <code><fix>http://example.com/BannerAd.gif</fix></code> but not <code><fix>http://example.com/bannerad.gif</fix></code>.}}</li>
     <li>{{s74 <code><fix>collapse</fix></code> — this option will override the global "Hide placeholders of blocked elements" option and make sure the filter always hides the element. Similarly the <code><fix>~collapse</fix></code> option will make sure the filter never hides the element.}}</li>
     <li>
       {{s75 <code><fix>donottrack</fix></code> — for any address matching a blocking rule with
       this option and not matching any exception rules with this option a
       <a href="http://donottrack.us/">Do-Not-Track header</a> will be sent (requires
       Adblock Plus 1.3.5 or higher).}} {{s76 For backwards compatibility it is recommended
       to use this option in combination with contradicting type options, this will prevent this
       filter from blocking anything in earlier Adblock Plus versions:
       <code><fix>*$donottrack,image,~image</fix></code>}}
     </li>
     <li>
-      {{rewriteoption Rewrite the URL with the option <code><fix>rewrite=</fix></code>. You may want to create a regular expression filter to perform the rewrite operation. In that case, you can use <code><fix>$n</fix></code> in the rewrite argument, with n being a number between 1 and 100, to insert the n-th parenthesis submatch of the filter regular expression. Anything not explicitly matched by it will be added in the rewritten string. For example <code><fix>/(server.com\/assets\/file.php)\?.*$/$rewrite=$1</fix></code> will strip everything that comes after ".php" and redirects the request to the resulting URL. If there is no query parameter (i.e. no '?'), this filter won't match. The rewrite parameter has the same syntax as JavaScript’s <code><fix>String.prototype.replace()</fix></code> when using a regular expression instead of a substring. If both, a filter with/without <code><fix>$rewrite</fix></code> option matches, the behavior is undefined, i.e. the request might either be blocked or redirected. (Adblock Plus 3.2 or higher required.)}}

[Manish Jethani, 2018/05/10 02:47:39]

We should probably also mention about the requirement that the rewritten URL
should also be of the same origin.

If we're supporting relative URLs (we are as I see it), we can mention that here
as well, but then I also wonder if that's an unnecessary detail that can be
skipped in the documentation.

+      {{rewriteoption Rewrite the URL with the option <code><fix>rewrite=</fix></code>. You may want to create a regular expression filter to perform the rewrite operation. In that case, you can use <code><fix>$n</fix></code> in the rewrite argument, with <code><fix>n</fix></code> being a number between 1 and 100, to insert the n-th parenthesis submatch of the filter regular expression. Anything not explicitly matched by it will be added in the rewritten string. For example <code><fix>/(server\.com\/assets\/file.php)\?.*$/$rewrite=$1</fix></code> will strip everything that comes after ".php" and redirects the request to the resulting URL. If there is no query string (i.e. no '?'), this filter won't match. The rewrite parameter has the same syntax as JavaScript’s <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace#Specifying_a_string_as_a_parameter"><code><fix>String.prototype.replace()</fix></code></a>. The resulting URL must have the same origin; in case it is rewritten to a relative URL, the origin gets added back. Also, rewrite for scripts, subdocuments, objects, requests from within objects (like Flash) are not possible for security reason; even if explicitly stated by the filter. If both, a filter with/without <code><fix>$rewrite</fix></code> option matches, the behavior is undefined, i.e. the request might either be blocked or redirected. (Adblock Plus 3.2 or higher required.)}}
     </li>
   </ul>
 
   <h4 id="regexps">{{s77 Using regular expressions}}</h4>
 
   <p>{{s79 If you want even more control about what your filters match and what they don't match, you can use regular expressions. For example the filter <code><fix>/banner\d+/</fix></code> will match <code><fix>banner123</fix></code> and <code><fix>banner321</fix></code> but not <code><fix>banners</fix></code>. You can check out <a href="{{s79-link https://developer.mozilla.org/en/Core_JavaScript_1.5_Guide/Regular_Expressions#Writing_a_Regular_Expression_Pattern}}">documentation on regular expressions</a> to learn how to write them.}}</p>
 
   <p>{{s80 <em>Note</em>: For performance reasons it is recommended not to use regular expressions if they can be avoided.}}</p>
 
   <h2 id="elemhide">{{s81 Element hiding}}</h2>
@@ skipping 106 matching lines @@
   {{s110 The data used for creating the signature is a concatenated list of request variables (namely URI, host and user agent) separated by the <code><fix>NUL</fix></code> character "\0". For example:}}
 </p>
 
 <pre>
   /index.html?q=foo\0www.example.com\0Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:30.0) Gecko/20100101 Firefox/30.0
 </pre>
 
 <p>
   {{s111 Finally, generate the signature for this string by using the signature algorithm SEC_OID_ISO_SHA_WITH_RSA_SIGNATURE (default when using OpenSSL).}}
 </p>