Introduction
CookieMaster is a WebExtension for Firefox that aims to provide control of cookies to ordinary users. It is inspired by the old pre-WebExtensions add-on called CookieMonster, although with some necessary differences for being a WebExtension, and that I wrote it from scratch.
About cookies
Cookies are divided into two types: first-party, and third-party. First-party are where the cookie is for the page you are browsing (or iframe that is loading), e.g. if you're browsing www.mozilla.org, then any cookies for mozilla.org are 'First Party'. Third-party are cookies set by requests for additional resources from other domains, e.g. if you're browsing www.cnn.com and it loads an image from doubleclick.net to serve an advert, and that image request tries to set a cookie, that's a third-party cookie.
For first-party cookies, CookieMaster assumes that if you haven't explicitly allowed them, then they should be blocked. If you want cookies for that site, you need to interact with CookieMaster to tell it so (see below, in "How to use CookieMaster").
For third-party cookies, the default assumption is that you do not want to allow any. However, to allow for other behaviours, you can also set it to
- Allow third-party cookies only if the domain has been explicitly added to CookieMaster's list (the same list as is used for first-party cookies), or
- Allow all third-party cookies (definitely not recommended)
If you're using CookieMaster because you want to limit cookies, you're probably going to want to keep the default setting.
You should know that cookies take effect for sub-domains, e.g. a cookie set for example.com will be used for any requests to www.example.com, "test.example.com", foo.bar.example.com and so-on. Therefore in CookieMaster allowing cookies for a higher level domain (e.g. example.com) implicitly allows cookies for any subdomains (e.g. www.example.com)
How to use CookieMaster
Configuration requirements
CookieMaster inserts itself into the cookie processing at a couple of control points to block cookies that have not been allowed. If a cookie is allowed, CookieMaster simply does nothing and lets Firefox do it's normal thing. Therefore, you almost definitely want to have Firefox's cookie settings configured to Accept cookies from websites, and possibly want Accept third-party cookies to something other than Never". CookieMaster tries to alert you if your settings might lead to unexpected results, but it's worth checking at least once that your general Cookie settings are how they should be. With the latest versions of Firefox, it's possible for CookieMaster to allow a cookie, but for Firefox to then block it as a tracking cookie.
Usage
CookieMaster presents as an icon in your Toolbar menu; when you click on it, a small popup/dropdown menu appears, that may look something like this:
In this case, I have visited www.example.com, and because I haven't specifically allowed it, cookies for www.example.com and example.com are both blocked. However, this site has not even tried to set cookies. Let's say I'm visiting https://edition.cnn.com/, and I click on the CookieMaster icon:
Notice how this time there is a blocked cookie icon to the left of the edition.cnn.com domain. This indicates that CNN tried to set cookies for edition.cnn.com and it was blocked, and has not attempted to set any for cnn.com. Note also that the CookieMaster icon has two red dots. The left hand side is First Party cookies, the right is Third Party. Red means that one or more cookies of that type were blocked, green means that all cookies of that type were allowed, and blue means 'mixed' (some allowed, some blocked).
My options here are varied. I might decide that I trust all of CNN, and want to allow any cookies from cnn.com and any sub-domains. To do that, I'd click on the red toggle for cnn.com, turning it green. It would then look like this:
There's a lot going on here. First up, notice that the cnn.com toggle is now green, with a tick. This says that when cnn.com next tries to set a cookie, it will be allowed. Notice what's happened to edition.cnn.com. Remember earlier where we talked about sub-domains? Because I've allowed cnn.com, I have implicitly allowed edition.cnn.com, and any other sub-domains of cnn.com. The toggle now shows in the middle, with a tick, and gray. This indicates that cookies will be allowed for edition.cnn.com, but the reason is because it's implied by cnn.com being allowed, not because I explicitly chose to allow edition.cnn.com. Not however that the 'cookie blocked' icon is still there; the page has not attempted to set a cookie since we allowed it, so the last record we have was a blocked cookie.
I then reload the page (although this might not be necessary; many sites will have Javascript that fetches resources that will trigger a cookie set, or explicitly set cookies from Javascript itself), and the popup will now look more like this:
Now cookies have been set for both cnn.com and edition.cnn.com, as indicated by the cookie icon with a green tick, on the left. However you may notice that CookieMaster icon has a blue dot for First Party cookies. This is because there some first party cookies were allowed, and some were blocked. But clearly both cnn.com domains have been allowed. What's going on? In a word, iframes. The link has more detail, but in short, an iframe is an HTML page embedded in it's own frame inside another HTML page. The pages are somewhat isolated from each other for security, but this also means that any cookies set by the iframe page, for the domain of the iframe, are considered First Party cookies.
How do we see them? If I click on 'Other Cookies', and I'll see something like this:
Here you can see that there were a number of iframes on the page, curiously including one for edition.cnn.com (for which the cookie was obviously allowed), and then 5 others for which the cookie was blocked. This is why the First Party dot is blue. Note that you can toggle whether cookies for those domains are allowed/blocked just as you can in the top section.
Third party cookies are also shown in the "Other Cookies" section.
With the Block All third-party policy in force, this is just a list of the third-party cookies that were blocked. This is mainly informational. If I change the third-party policy (in the Add-ons preference pages) to 'Allow only if explicitly permitted', then the popup will look something like this:
Notice how the third-party cookies now have toggles as well; these work exactly like toggles for first-party cookies that we're already familiar. In this case, however, we don't show the blocked/allowed cookie icon on the left; rather, the third-party cookies are sorted into two sections. Having allowed doubleclick.net and reloading, the popup now looks like this:
How to use preferences
To change preferences, and see the entire list of domains that have been permitted, goto "about:addons", or via the Firefox hamburger menu, click 'Add-ons'. Click the 'Preferences' button for CookieMaster.
Here you can set your choice of third-party cookie handling. The default setting is to "Block All". You can also set it to either "Allow all" (definitely not recommended), or to allow third-party cookies only if the domain has been explicitly added to CookieMaster's list (the same list as is used for first-party cookies). If you're using CookieMaster because you want to limit cookies, you're probably going to want to keep the default setting.
You can also see and manage the list of domains/sites that have been allowed to set cookies.
To add one, type the domain in the top text box ("Website address"), and click "Add Site". The new domain will appear in the list box below.
To remove one (or more), select them in the list box and click 'Remove Selected'.
How it works
You don't need to know this, but if you're interested, here's a high level view of how CookieMaster works.
Cookies can be set in two ways, by headers in an HTTP response, or from Javascript, using Document.cookie. CookieMaster takes care of the headers by hooking into the HTTP response process and removing any Set-Cookie headers that shouldn't be allowed based on the user-chosen policy + allow-list. Cookies set by Javascript are noticed by hooking into the cookie property setter (using a content script), and prevented from being set if the CookieMaster policy demands that.
Interestingly (perhaps), the actual blocking/allowing code is fairly trivial. The hard bit was (and is) a vaguely sensible UI
It's worth pointing out here that cookies are far from the only way you can be tracked on-line, and a determined third party can probably still track you if they're willing to put in enough effort.
Why is this document so ugly? Why is the UI layout awful?
Because I'm not a graphical designer; I'm a sysadmin with delusions of coding ability. If you'd like to contribute some patches/updates to make it look less terrible, I would be delighted. The icons have had a nice refresh/makeover already because someone took the time to help out, and I am deeply grateful
Source
https://github.com/craigmiskell/cookiemaster
Bug reports, patches, or other contributions are all gratefully received.
Licenses
CookieMaster is OpenSource software. The full License file describes the component parts/licenses, but we summarise these here:
Except as explicitly noted, all code in CookieMaster is released under the GPL version 3
cookie-parse.js from https://github.com/jkohrman/cookie-parse licensed under the MIT license:
Copyright (c) 2012-2014 Roman Shtylmanshtylman@gmail.com
Copyright (c) 2015 Douglas Christopher Wilson doug@somethingdoug.com
Copyright (c) 2016 Jeff Kohrman jeff.kohrman@gmail.com
psl.min.js from https://github.com/wrangr/psl, licensed under the MIT license:
Copyright (c) 2017 Lupo Montero lupomontero@gmail.com
Icons derived/modified from the Mint-Y icon set: https://github.com/linuxmint/mint-y-icons
License: Creative Commons Attribution-ShareAlike 4.0 (CC-BY-SA-4)
Original Copyright: 2015 Sam Hewitt sam@snwh.org, Alexey Varfolomeev
Updated icons:
Copyright https://github.com/ArcticGems
CC0 1.0 Universal (CC0 1.0)
Public Domain Dedication