LogoLogo
About GitLabAcceptable Ads
  • Getting Started
  • Browser Ad-Filtering Solution
    • Features
    • Getting Started
      • Quickstart
      • Integrate the Solution
      • Set up user counting
    • Guides
      • User counting
      • Configure Solution settings
      • Run separate instances of the filtering engine
      • Update the Solution
      • Understand the snippets library
      • Create a filter list
      • Testing
    • Advanced
      • Services and classes
      • Sitekey
      • ADRs
      • Frame hierarchy
  • Snippets
    • Snippets Overview
    • Behavioral Snippets
      • abort-current-inline-script
      • abort-on-property-read
      • abort-on-property-write
      • abort-on-iframe-property-read
      • abort-on-iframe-property-write
      • array-override
      • cookie-remover
      • freeze-element
      • json-override
      • json-prune
      • override-property-read
      • prevent-listener
      • replace-fetch-response
      • replace-xhr-response
      • simulate-mouse-event
      • skip-video
      • strip-fetch-query-parameter
    • Conditional Hiding Snippets
      • hide-if-canvas-contains
      • hide-if-contains
      • hide-if-contains-image
      • hide-if-contains-similar-text
      • hide-if-contains-visible-text
      • hide-if-contains-and-matches-style
      • hide-if-has-and-matches-style
      • hide-if-labelled-by
      • hide-if-matches-computed-xpath
      • hide-if-matches-xpath
      • hide-if-matches-xpath3
      • hide-if-shadow-contains
    • Debugging Snippets
      • debug
      • log
      • profile
      • trace
    • Performance Snippets
      • race
    • Snippets Support by Platform
    • Node Highlighting
    • Accessing shadow DOM elements
  • Working with filters
  • DATA AND PRIVACY
    • Data collection at eyeo
Powered by GitBook
On this page
  • How sitekeys work
  • Other resources

Was this helpful?

Edit on GitLab
Export as PDF
  1. Browser Ad-Filtering Solution
  2. Advanced

Sitekey

Last updated 1 year ago

Was this helpful?

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: and . 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-value

  • The host that the client contacted, for example, catstoys.com

These three strings are connected into a single line of text, separated by null (\0) symbols, as in the following example:

/page.html?param-value\0catstoys.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:

nLH8Vbc1rzmy0Q+Xg+bvm43IEO42h8rq5D9C0WCn/Y3ykgAoV4npzm7eMlqBSwZBLA/0DuuVsfTJT9MOVaurcA==

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 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:

MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBANnylWw2vLY4hUn9w06zQKbhKBfvjFUCsdFlb6TdQhxb9RXWXuI4t31c+o8fYOv/s8q1LGPga3DE1L/tHU4LENMCAwEAAQ_nLH8Vbc1rzmy0Q+Xg+bvm43IEO42h8rq5D9C0WCn/Y3ykgAoV4npzm7eMlqBSwZBLA/0DuuVsfTJT9MOVaurcA=

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.

Applicable sitekey filter
@@$document,sitekey=MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBANnylWw2vLY4hUn9w06zQKbhKBfvjFUCsdFlb6TdQhxb9RXWXuI4t31c+o8fYOv/s8q1LGPga3DE1L/tHU4LENMCAwEAAQ

The following diagram illustrates the browser-side sitekey process:

Other resources

The client's , like Mozilla/5.0 (X11; Linux x86_64), Chrome/92.0.4515.107 Safari/537.36, and so on.

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 .

As a result, in the example, filter list allowing can now be applied on :

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 .

user agent
public-key cryptography
https://catstoys.com
How to write filters
https://catstoys.com
https://dogstoys.com
Multiple domains using the same sitekey
Server-side flow for sitekey generation
Browser-side handling of sitekeys