HTTPS Everywhere Rulesets | Electronic Frontier Foundation

HTTPS Everywhere Rulesets

This page describes how to write rulesets for HTTPS Everywhere, the Firefox plugin that switches sites over from http to https automatically. HTTPS Everywhere comes with thousands of rulesets, but you might want to edit them, or write new ones.

[We believe this information is correct as of version 2.0 of HTTPS Everywhere.]

Rulesets are simple xml files. Here is a simplified version of Twitter.xml, from the plugin distribution:

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 www.eff.org, www.google.com, secure.wikimedia.org, and so on. If your rule applies to the domain itself (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 www.twitter.com or twitter.com, so it has a separate target tag for each.

A target may, however, contain a wildcard in one portion of the domain (like *.google.com or google.*, but *.google.* would not work). A wildcard on the left will match arbitrarily deep subdomains (for instance, *.facebook.com will match s-static.ak.facebook.com).1

The "rule" does the actual rewriting work. The "from" and "to" clauses in each rule are JavaScript regular expressions. You can use them to rewrite URLs in more complicated ways. Here's a simplified example for Wikipedia:

That rewrites a URL like http://fr.wikipedia.org/wiki/Chose to https://secure.wikimedia.org/wikipedia/fr/wiki/Chose. 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 not be applied. The EFF rule contains one exclusion, for a domain that is hosted externally and does not support HTTPS:

Note that if your rules include ampersands (&), they need to be appropriately XML-encoded: replace each occurence of & with &.

Lastly, because many HTTPS websites fail to correctly set the secure flag on authentication cookies, there is a facility for turning this flag on. For instance:

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 HTTPSEverywhereUserRules/ subdirectory in your Firefox profile directory, 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 git repository.

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 https-everywhere-rules AT eff.org. Please be aware that this is a public and publicly-archived mailing list. NOTE: 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 check there 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 the relevant part of our git repository, you don't need to write a new one -- just switch to the the development branch or build your own .xpi from git.

make-trivial-rule and trivial-validate.py

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 our development documentation.

Disabling a ruleset by default

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, CAcert 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 default_off attribute to the ruleset element, with a value explaining why the rule is off.

By convention, you should add a parenthetical to the name of the ruleset — like (buggy) while it is off. If you reenable a ruleset, you should remove the parenthetical. This convention is important: it exists so that the change to the default override existing users' settings for whether the ruleset is on or off.

Disabling a ruleset on some platforms

Sometimes bugs on a platform may mean that a ruleset should be off by default on that platform only. For instance, this bug caused us to temporarily disable the Google Translate rules on Chromium and Chrome. This can be achieved with the "platform" attribute:

Platform is a space-delimited list of platforms on which the ruleset works. Currently anticipated values are "firefox", "chromium", and "cacert". If the platform attribute is present, but does not match the current platform, the ruleset will be treated as off-by-default.

• 1. Exception: currently this is not true for a target host that is less than three levels deep. would match thing.com but not very.thing.com. We would consider changing that if anybody needs to use it. means a ruleset should be tested for every single URL.

via eff.org

Posted via email from DailyDDoSe