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.
The network responses headers for both sites will contain
x-adblock-key. The sitekey is encoded within that header.
Multiple domains using the same sitekey
The sitekey server gets the following information:
- The host that the client contacted, for example,
- The URL requested by the client, for example,
These three strings are connected into a single line of text, separated by null (
\0) symbols, as in the following example:
catstoys.com\0https://catstoys.com\0Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/92.0.4515.107 Safari/537.36
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
The following diagram illustrates the process in its entirety:
Server-side flow for sitekey generation
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.
Applicable sitekey filter
The following diagram illustrates the browser-side sitekey process:
Browser-side handling of sitekeys