Issue 434 - Added documentation for $sitekey functionality

body.html

Index: body.html
===================================================================
--- a/body.html
+++ b/body.html
@@ -158,6 +158,9 @@
     <li>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>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>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>
+      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". Note that sitekey restrictions require <a href="#sitekey_server">modifications on the server-side</a>.

[Wladimir Palant, 2014/09/08 14:09:26]

Maybe add something like "This is similar to domain restrictions but allows
covering scenarios where a single filter should apply to a very large number of
domains."

[Thomas Greiner, 2014/09/08 15:17:36]

Done.

+    </li>
     <li><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><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>
@@ -239,3 +242,25 @@
   <h3 id="elemhide_simplified">Simplified element hiding syntax</h3>
 
   <p>Adblock Plus supports simplified element hiding syntax (e.g. <code><fix>#div(id=foo)</fix></code>) for backwards compatibility only. Using this syntax is discouraged, usual CSS selectors are preferred. Support for this syntax might be removed at some point.</p>
+
+  <h2 id="sitekey_server">Implementing a sitekey on the server</h2>
+
+<p>
+  For a <a href="#options">sitekey-restricted filter</a> to apply, a webpage needs to return base64-encoded versions of the public key and a signature which Adblock Plus can validate. Currently, this means including them in both the HTTP response header (<code><fix>X-Adblock-Key: abcdpublickeydcba_abcdsignaturedcba</fix></code>) and the root tag of the document (<code><fix>&lt;html data-adblockkey="abcdpublickeydcba_abcdsignaturedcba"&gt;</fix></code>).
+</p>
+
+<p>
+  First you need to create a private RSA key (preferably 512 bit to keep the transfer volume low) and then a DER representation of the public key.
+</p>
+
+<p>
+  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>
+  Finally, generate the signature for this string by using the signature algorithm SEC_OID_ISO_SHA_WITH_RSA_SIGNATURE (default when using OpenSSL).
+</p>