Sitekey
A sitekey is a special identifier that a server may attach to a resource. Sitekeys enable additional filters that determine whether to block or allow the resource.
Sitekeys are typically used to allowlist resources coming from a particular server that may serve many different domains.
How sitekeys work
Suppose a user visits two sites: https://catstoys.com and https://dogstoys.com. A single sitekey server handles both sites.
The network responses headers for both sites will contain x-adblock-key. The sitekey is encoded within that header.
How sitekeys get computed on the server side
The sitekey server gets the following information:
The path with query of the URL requested by the client, for example,
/page.html?param-valueThe host that the client contacted, for example,
catstoys.comThe client's user agent, like
Mozilla/5.0 (X11; Linux x86_64),Chrome/92.0.4515.107 Safari/537.36, and so on.
These three strings are connected into a single line of text, separated by null (\0) symbols, as in the following example:
This becomes the input to the encryption algorithm. This input is different for every URL that the browser requests.
The sitekey server holds a secret private key that is only generated once and never changes. Using this private key, the sitekey server encrypts the input text and generates a unique signature, or a hash. The hash would look something like this:
The sitekey server then returns the following:
The signature, that is, is the encrypted output. This signature changes for every request.
A sitekey, which is the public key to the server's internal, secret private key. The public key never changes.
The recipient of a public key cannot perform the encryption; that requires the private key. However, the recipient may verify whether an encryption was made using the private key paired with the public key. This is the basis of public-key cryptography.
The sitekey and signature are glued together with the underscore (_) as the separator, as in sitekey_signature. In the example scenario, the string would look like this:
The sitekey server then sends this string back to the browser in the x-adblock-keyheader.
The following diagram illustrates the process in its entirety:
Sitekey on the browser side
When the browser receives an HTTP response whose header contains x-adblock-key, it splits the string back into a separate sitekey and signature.
Because the browser knows the signature's three parameters (host, URL, UserAgent) and it has the public key, it can verify that the sender has the private key that corresponds to the sitekey that the browser received.
In other words, the browser now knows that the server is a legitimate provider of the MFwwDQYJKoZIhvcNAQ... sitekey. This is because the server successfully encrypted inputs given by the browser in a way that's verifiable with that sitekey.
As a result, in the example, filter list allowing can now be applied on https://catstoys.com:
The following diagram illustrates the browser-side sitekey process:
Other resources
The filter used in the example on this page allows all resources to load and disables element hiding on any page with the specified sitekey. For more on filter language, see How to write filters.
Last updated
