<p>This page describes how to write rulesets for <a href="https://eff.org/https-everywhere">HTTPS Everywhere</a>, the Firefox plugin that switches sites over from http to https automatically. HTTPS Everywhere comes with <a href="http://www.eff.org/https-everywhere/atlas/">thousands</a> of rulesets, but you might want to edit them, or write new ones. Rulesets are simple xml files. Here is a simplified version of <a href="https://gitweb.torproject.org/https-everywhere.git/blob/HEAD:/src/chrome/content/rules/Twitter.xml"><tt>Twitter.xml</tt></a>, from the plugin distribution:</p><pre>&lt;ruleset name="Twitter"&gt;

&lt;target host="www.twitter.com" /&gt;

&lt;target host="twitter.com" /&gt;

&lt;rule from="^http://(www\.)?twitter\.com/" to="https://twitter.com/"/&gt;

&lt;/ruleset&gt;</pre><p>The "target" tag specifies which domains the ruleset might apply to. The target host tag does not use regular expressions. The content of a target tag should be the actual name of a web server to which the ruleset applies or partially applies, like <tt>www.eff.org</tt>, <tt>www.google.com</tt>, <tt>secure.wikimedia.org</tt>, and so on. If your rule applies to the bare domain (like "eff.org", not just "www.eff.org"), you need an additional target tag to say so. For example, the sample ruleset above is meant to apply to either <tt>www.twitter.com</tt> or <tt>twitter.com</tt>, so it has a separate target tag for each. A target may, however, contain a wildcard in one portion of the domain (like <tt>*.google.com</tt> or <tt>google.*</tt>, but <tt>*.google.*</tt> would not work). A wildcard on the left will match arbitrarily deep subdomains (for instance, <tt>*.facebook.com</tt> will match <tt>s-static.ak.facebook.com</tt>).Exception: currently this is not true for a target host that is less than three levels deep. <tt>&lt;target host="*.com"&gt;</tt> would match <tt>thing.com</tt> but not <tt>very.thing.com</tt>. We would consider changing that if anybody needs to use it. The "rule" does the actual rewriting work. The "from" and "to" clauses in each rule are <a href="http://www.regular-expressions.info/javascript.html">JavaScript regular expressions</a>. You can use them to rewrite URLs in more complicated ways. Here's a simplified (and now obsolete) example for Wikipedia:</p><pre>&lt;ruleset name="Wikipedia"&gt;

&lt;target host="*.wikipedia.org" /&gt;

&lt;rule from="^http://([^@:/][^/:@])\.wikipedia\.org/wiki/"

to="https://secure.wikimedia.org/wikipedia/$1/wiki/"/&gt;

&lt;/ruleset&gt;</pre><p>That rewrites a URL like <tt>http://fr.wikipedia.org/wiki/Chose</tt> to <tt>https://secure.wikimedia.org/wikipedia/fr/wiki/Chose</tt>. Notice, again, that the target is allowed to contain (just one) * as a wildcard meaning "any". It is possible to add exclusions. An exclusion specifies a pattern, using a regular expression, for URLs where the rule should <strong>not</strong> be applied. The EFF rule contains one exclusion, for a domain that is hosted externally and does not support HTTPS:</p><pre>&lt;ruleset name="EFF"&gt;

&lt;target host="eff.org" /&gt;

&lt;target host="*.eff.org" /&gt;

&lt;exclusion pattern="^http://action\.eff\.org/"/&gt;

&lt;rule from="^http://eff\.org/" to="https://eff.org/"/&gt;

&lt;rule from="^http://([^/:@]*)\.eff\.org/" to="https://$1.eff.org/"/&gt;

&lt;/ruleset&gt;</pre><p>Note that if your rules include ampersands (&amp;), they need to be appropriately XML-encoded: replace each occurence of <strong>&amp;</strong> with <strong>&amp;#x26;</strong>. Lastly, because many HTTPS websites fail to correctly set the <a href="https://secure.wikimedia.org/wikipedia/en/wiki/HTTP_cookie#Secure_and_HttpOnly">secure flag</a> on authentication cookies, there is a facility for turning this flag on. For instance:</p><pre>&lt;securecookie host="^market\.android\.com$" name=".*" /&gt;</pre><p>The "host" parameter is a regexp specifying which domains should have their cookies secured; the "name" parameter is a regexp specifying which cookies should be secured. Note that HTTPS Everywhere will only secure a cookie when it is set over HTTPS. Once you've written a ruleset, you can use and test it by placing it in the <tt>HTTPSEverywhereUserRules/</tt> subdirectory in <a href="http://kb.mozillazine.org/Profile_folder_-_Firefox">your Firefox profile directory</a>, and then restarting Firefox. While using the rule, check for messages in the Firefox Error Console to see if there are any issues with the way the site supports HTTPS. Note that it is inadvisable to edit the builtin rules in-place, since they will be overwritten by upgrades to the extension. Either keep your edits in a safe place, or use a <a href="/https-everywhere/development">git repository</a>. If you've tested your rule and are sure it would be of use to the world at large, send it to the rulesets mailing list at <tt>https-everywhere-rules AT eff.org</tt>. Please be aware that this is a public and publicly-archived mailing list. <strong>NOTE</strong>: many rules that are not yet distributed in the official version of HTTPS Everywhere are already in our git repository! Before sending us a new rule, please <a href="https://gitweb.torproject.org/https-everywhere.git/tree/HEAD:/src/chrome/content/rules">check there</a> to see if your rule has already been submitted by someone else. Note that there are currently hundreds of pending rules which are not present in the latest stable version but which are included in development builds. If a version of the rule you're interested in is found in <a href="https://gitweb.torproject.org/https-everywhere.git/tree/HEAD:/src/chrome/content/rules">the relevant part of our git repository</a>, you don't need to write a new one -- just switch to the the <a href="https://www.eff.org/files/https-everywhere-devel.xpi">development branch</a> or build your own .xpi from git.</p><h2>make-trivial-rule and trivial-validate.py</h2><p>As an alternative to writing rules by hand, there are scripts you can run from a Unix command line to automate the process of creating a simple rule for a specified domain. These scripts are not included with HTTPS Everywhere releases but are available in our development repository and are described in <a href="development">our development documentation</a>. <a name="default_off"></a></p><h2>Disabling a ruleset by default</h2><p>Sometimes rulesets are useful or interesting, but contain some bugs or issues that make them unsuitable for being enabled by default in everyone's browsers. For instance, the HTTPS website may use a Certificate Authority that is not trusted by everyone's browsers (most commonly, <a href="http://www.cacert.org/">CAcert</a> or a self-signed certificate). Or the ruleset may successfully secure parts of a site but interfere with others. In such cases, rulesets should be disabled by default. This is done by adding a <tt>default_off</tt> attribute to the ruleset element, with a value explaining why the rule is off.</p><pre>&lt;ruleset name="Amazon (buggy)" default_off="currently somewhat broken"&gt;

&lt;target host="www.amazon.*" /&gt;

&lt;target host="amazon.*" /&gt;</pre><p>By convention, you should add a parenthetical to the name of the ruleset — like <tt>(buggy)</tt> while it is off. If you reenable a ruleset, you should remove the parenthetical. <em>This convention is important: it exists so that the change to the default overrides existing users' settings for whether the ruleset is on or off.</em> <a name="platform"></a></p><h3>Disabling a ruleset on some platforms</h3><p>Sometimes bugs on a platform may mean that a ruleset should be off by default on that platform only. For instance, <a href="https://trac.torproject.org/projects/tor/ticket/5196">this bug</a> caused us to temporarily disable the Google Translate rules on Chromium and Chrome. This can be achieved with the "platform" attribute:</p><pre>&lt;ruleset name="Google Translate" platform="firefox"&gt;

&lt;target host="translate.googleapis.com"/&gt;

&lt;target host="translate.google.com"/&gt;

&lt;rule from="^http://translate\.googleapis\.com/"

to="https://translate.googleapis.com/"/&gt;

&lt;rule from="^http://translate\.google\.com/translate_a/element\.js"

to="https://translate.google.com/translate_a/element.js"/&gt;

&lt;/ruleset&gt;</pre><p>Platform is a space-delimited list of platforms on which the ruleset works. Currently anticipated values are "firefox", "chromium", "mixedcontent", "cacert" and "ipsca". The "mixedcontent" value is important, and should be used for sites that render badly in Chrome because that browser <a href="https://trac.torproject.org/projects/tor/ticket/6975">blocks HTTP content from loading in HTTPS pages</a> by default. If the platform attribute is present, but does not match the current platform, the ruleset will be treated as off-by-default. <strong>Update (12/12/13)</strong>: Firefox 23+ has enabled mixed content blocking by default. As a result, many rules that were previously labeled "firefox" should now be labeled "mixedcontent." <a name="downgrade"></a></p><h3>HTTPS-&gt;HTTP downgrade rules</h3><p>By default, HTTPS Everywhere will refuse to allow rules that would downgrade a URL from HTTPS to HTTP. Occasionally, this has turned out to be necessary because when HTTPS Everywhere is active some sites write broken relative links to HTTPS resources on their own domains that are not actually available over HTTPS. If you want to have a <tt>&lt;rule&gt;</tt> like that (<a href="https://gitweb.torproject.org/pde/https-everywhere.git/blob/4.0:/src/chrome/content/rules/BBC.xml">here's an example</a>), it will need a downgrade="1" attribute to make sure you really meant it, and to facilitate auditing of the ruleset library.</p>