Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code

Side by Side Diff: body.html

Issue 5424603463680000: Issue 434 - Added documentation for $sitekey functionality (Closed)
Patch Set: Created Sept. 8, 2014, 9:53 a.m.
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments.
Jump to:
View unified diff | Download patch
« no previous file with comments | « no previous file | no next file » | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
1 <p>Current Adblock Plus versions allow you to "tweak" your filters in many diffe rent ways. This document explains the choices that you have and how they can be used.</p> 1 <p>Current Adblock Plus versions allow you to "tweak" your filters in many diffe rent ways. This document explains the choices that you have and how they can be used.</p>
2 2
3 <p><em>Disclaimer</em>: All filter examples given here are really only example s and are not meant to be used.</p> 3 <p><em>Disclaimer</em>: All filter examples given here are really only example s and are not meant to be used.</p>
4 4
5 <h2 id="introduction">Introduction to Adblock Plus filters</h2> 5 <h2 id="introduction">Introduction to Adblock Plus filters</h2>
6 6
7 <p>The options described in this section should be enough for users who have t o create a filter occasionally.</p> 7 <p>The options described in this section should be enough for users who have t o create a filter occasionally.</p>
8 8
9 <h3 id="basic">Basic filter rules</h3> 9 <h3 id="basic">Basic filter rules</h3>
10 10
(...skipping 140 matching lines...) Expand 10 before | Expand all | Expand 10 after
151 <li><code><fix>elemhide</fix></code> -- for exception rules only, simila r to <code><fix>document</fix></code> but only disables <a href="#elemhide">elem ent hiding rules</a> on the page rather than all filter rules (Adblock Plus 1.2 and higher required)</li> 151 <li><code><fix>elemhide</fix></code> -- for exception rules only, simila r to <code><fix>document</fix></code> but only disables <a href="#elemhide">elem ent hiding rules</a> on the page rather than all filter rules (Adblock Plus 1.2 and higher required)</li>
152 <li><code><fix>other</fix></code> -- types of requests not covered in th e list above</li> 152 <li><code><fix>other</fix></code> -- types of requests not covered in th e list above</li>
153 </ul> 153 </ul>
154 The type options <code><fix>background</fix></code>, <code><fix>xbl</fix>< /code>, 154 The type options <code><fix>background</fix></code>, <code><fix>xbl</fix>< /code>,
155 <code><fix>ping</fix></code> and <code><fix>dtd</fix></code> are outdated and should no 155 <code><fix>ping</fix></code> and <code><fix>dtd</fix></code> are outdated and should no
156 longer be used. 156 longer be used.
157 </li> 157 </li>
158 <li>Inverse type options: specify the element types the filter should <stron g>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>, <co de><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> 158 <li>Inverse type options: specify the element types the filter should <stron g>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>, <co de><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>
159 <li>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>~t hird-party</fix></code> restricts the filter to requests from the same origin as the currently viewed page.</li> 159 <li>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>~t hird-party</fix></code> restricts the filter to requests from the same origin as the currently viewed page.</li>
160 <li>Domain restrictions: The option <code><fix>domain=example.com</fix></cod e> means that the filter should only be applied on pages from "example.com" doma in. Multiple domains can be specified using "|" as separator: with the option <c ode><fix>domain=example.com|example.net</fix></code> the filter will only be app lied on pages from "example.com" or "example.net" domains. If a domain name is p receded with "~", the filter should <strong>not</strong> be applied on pages fro m this domain. For example, <code><fix>domain=~example.com</fix></code> means th at 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> 160 <li>Domain restrictions: The option <code><fix>domain=example.com</fix></cod e> means that the filter should only be applied on pages from "example.com" doma in. Multiple domains can be specified using "|" as separator: with the option <c ode><fix>domain=example.com|example.net</fix></code> the filter will only be app lied on pages from "example.com" or "example.net" domains. If a domain name is p receded with "~", the filter should <strong>not</strong> be applied on pages fro m this domain. For example, <code><fix>domain=~example.com</fix></code> means th at 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>
161 <li>
162 Sitekey restrictions: The option <code><fix>sitekey=abcdsitekeydcba</fix>< /code> means that the filter should only be applied on pages that provide a publ ic key and a signature which can be verified by that very same public key that i s also contained in the filter (but without the trailing =). Multiple sitekeys c an be specified using "|" as separator: with the option <code><fix>sitekey=abcds itekeydcba|bcdesitekeyedcb</fix></code> the filter will only be applied on pages providing either sitekey "abcdsitekeydcba" or "bcdesitekeyedcb". Note that site key restrictions require <a href="#sitekey_server">modifications on the server-s ide</a>.
Wladimir Palant 2014/09/08 14:09:26 Maybe add something like "This is similar to domai
Thomas Greiner 2014/09/08 15:17:36 Done.
163 </li>
161 <li><code><fix>match-case</fix></code> -- makes the filter only apply to add resses with matching letter case, e.g. the filter <code><fix>*/BannerAd.gif$matc h-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> 164 <li><code><fix>match-case</fix></code> -- makes the filter only apply to add resses with matching letter case, e.g. the filter <code><fix>*/BannerAd.gif$matc h-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>
162 <li><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 m ake sure the filter never hides the element.</li> 165 <li><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 m ake sure the filter never hides the element.</li>
163 <li> 166 <li>
164 <code><fix>donottrack</fix></code> -- for any address matching a blocking rule with 167 <code><fix>donottrack</fix></code> -- for any address matching a blocking rule with
165 this option and not matching any exception rules with this option a 168 this option and not matching any exception rules with this option a
166 <a href="http://donottrack.us/">Do-Not-Track header</a> will be sent (requ ires 169 <a href="http://donottrack.us/">Do-Not-Track header</a> will be sent (requ ires
167 Adblock Plus 1.3.5 or higher).<fix> </fix>For backwards compatibility it i s recommended 170 Adblock Plus 1.3.5 or higher).<fix> </fix>For backwards compatibility it i s recommended
168 to use this option in combination with contradicting type options, this wi ll prevent this 171 to use this option in combination with contradicting type options, this wi ll prevent this
169 filter from blocking anything in earlier Adblock Plus versions: 172 filter from blocking anything in earlier Adblock Plus versions:
170 <code><fix>*$donottrack,image,~image</fix></code> 173 <code><fix>*$donottrack,image,~image</fix></code>
(...skipping 61 matching lines...) Expand 10 before | Expand all | Expand 10 after
232 <code><fix>example.com#@#div.textad</fix></code>.<fix> </fix>The combination o f these two 235 <code><fix>example.com#@#div.textad</fix></code>.<fix> </fix>The combination o f these two
233 rules has exactly the same effect as the single rule 236 rules has exactly the same effect as the single rule
234 <code><fix>~example.com##div.textad</fix></code>.<fix> </fix>It is recommended that you use 237 <code><fix>~example.com##div.textad</fix></code>.<fix> </fix>It is recommended that you use
235 exception rules only when you cannot change an overly general element hiding r ule, in all the 238 exception rules only when you cannot change an overly general element hiding r ule, in all the
236 other cases limiting this rule to the necessary domains is preferable. 239 other cases limiting this rule to the necessary domains is preferable.
237 </p> 240 </p>
238 241
239 <h3 id="elemhide_simplified">Simplified element hiding syntax</h3> 242 <h3 id="elemhide_simplified">Simplified element hiding syntax</h3>
240 243
241 <p>Adblock Plus supports simplified element hiding syntax (e.g. <code><fix>#di v(id=foo)</fix></code>) for backwards compatibility only. Using this syntax is d iscouraged, usual CSS selectors are preferred. Support for this syntax might be removed at some point.</p> 244 <p>Adblock Plus supports simplified element hiding syntax (e.g. <code><fix>#di v(id=foo)</fix></code>) for backwards compatibility only. Using this syntax is d iscouraged, usual CSS selectors are preferred. Support for this syntax might be removed at some point.</p>
245
246 <h2 id="sitekey_server">Implementing a sitekey on the server</h2>
247
248 <p>
249 For a <a href="#options">sitekey-restricted filter</a> to apply, a webpage nee ds to return base64-encoded versions of the public key and a signature which Adb lock Plus can validate. Currently, this means including them in both the HTTP re sponse header (<code><fix>X-Adblock-Key: abcdpublickeydcba_abcdsignaturedcba</fi x></code>) and the root tag of the document (<code><fix>&lt;html data-adblockkey ="abcdpublickeydcba_abcdsignaturedcba"&gt;</fix></code>).
250 </p>
251
252 <p>
253 First you need to create a private RSA key (preferably 512 bit to keep the tra nsfer volume low) and then a DER representation of the public key.
254 </p>
255
256 <p>
257 The data used for creating the signature is a concatenated list of request var iables (namely URI, host and user agent) separated by the <code><fix>NUL</fix></ code> character "\0". For example:
258 </p>
259
260 <pre>
261 /index.html?q=foo\0www.example.com\0Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv :30.0) Gecko/20100101 Firefox/30.0
262 </pre>
263
264 <p>
265 Finally, generate the signature for this string by using the signature algorit hm SEC_OID_ISO_SHA_WITH_RSA_SIGNATURE (default when using OpenSSL).
266 </p>
OLDNEW
« no previous file with comments | « no previous file | no next file » | no next file with comments »

Powered by Google App Engine
This is Rietveld