From 873d9c0d5390b99101db8c9d5b11cd90947660ae Mon Sep 17 00:00:00 2001 From: William Budington Date: Sun, 30 Oct 2016 08:14:58 -0700 Subject: [PATCH 1/5] Move ruleset documentation to markdown --- docs/rulesets.html | 304 --------------------------------------------- docs/rulesets.md | 105 ++++++++++++++++ 2 files changed, 105 insertions(+), 304 deletions(-) delete mode 100644 docs/rulesets.html create mode 100644 docs/rulesets.md diff --git a/docs/rulesets.html b/docs/rulesets.html deleted file mode 100644 index 060d8aa4d683..000000000000 --- a/docs/rulesets.html +++ /dev/null @@ -1,304 +0,0 @@ - -

- This page describes how to write rulesets for - HTTPS Everywhere, - a browser extension that switches sites over from HTTP - to HTTPS automatically. HTTPS Everywhere comes with - thousands - of rulesets that tell HTTPS Everywhere which sites it should switch - to HTTPS and how. If there is a site that offers HTTPS and is not handled by - the extension, this guide will explain how to add that site. -

- -

Rulesets -

- -

- A ruleset is an XML - file describing behavior for a site or group of sites. A ruleset contains - one or more rules. For example, here is - RabbitMQ.xml, - from the plugin distribution: -

- -
-<ruleset name="RabbitMQ">
-        <target host="rabbitmq.com" />
-        <target host="www.rabbitmq.com" />
-
-        <rule from="^http:"
-                to="https:" />
-</ruleset>
-
- -

- The target tag specifies which web sites the ruleset applies - to. The rule tag specifies how URLs on those web sites should be - rewritten. This rule says that any URLs on rabbitmq.com and - www.rabbitmq.com should be modified by replacing "http:" with - "https:". -

- -

- When the browser loads a URL, HTTPS Everywhere takes the host - name (e.g. www.rabbitmq.com) and searches its ruleset database for - rulesets that match that host name. -

- -

- HTTPS Everywhere then tries each rule in those rulesets against the full URL. - If the Regular Expression, or regexp, in one of those rules matches, HTTPS - Everywhere rewrites the URL - according the to attribute of the rule. -

- -

Wildcard Targets -

- -

- To cover all of a domain's subdomains, you may want to specify - a wildcard target like *.twitter.com. Specifying - this type of left-side wildcard matches any host name with - .twitter.com as a suffix, e.g. www.twitter.com - or urls.api.twitter.com. You can also specify a - right-side wildcard like www.google.*. Right-side - wildcards, unlike left-side wildcards, apply only one level - deep. So if you want to cover all countries you'll generally - need to specify www.google.*, www.google.co.*, - and www.google.com.* to cover domains like - www.google.co.uk or www.google.com.au. You should - use wildcard targets only when you have rules that apply to the - entire wildcard space. If your rules only apply to specific hosts, - you should list each host as a separate target. -

- -

-Rules and Regular Expressions -

- -

- The rule tags do the actual rewriting work. The from attribute of - each rule is a regular expression matched against a full URL. You can use rules to rewrite - URLs in simple or complicated ways. Here's a simplified (and now obsolete) example - for Wikipedia: -

- -
-<ruleset name="Wikipedia">
-  <target host="*.wikipedia.org" />
-
-  <rule from="^http://(\w{2})\.wikipedia\.org/wiki/"
-          to="https://secure.wikimedia.org/wikipedia/$1/wiki/"/>
-</ruleset>
-
- -

- The to attribute replaces the text matched by the from - attribute. It can contain placeholders like $1 that are replaced with - the text matched inside the parentheses. -

- -

- This rule 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". -

- -

- Rules are applied in the order they are listed within each ruleset. - Order between rulesets is unspecified. Only the first rule or exception - matching a given URL is applied. -

- -

- Rules are evaluated using Javascript regular - expressions, which are similar but not identical to Perl-style regular - expressions. - Note that if your rules include ampersands (&), they need - to be appropriately XML-encoded: replace each occurrence of - & with &#x26;. -

- -

Exclusions

-

- An exclusion specifies a pattern, using a - regular expression, for URLs where the rule should not be - applied. The Stack Exchange rule contains an exclusion for the OpenID login - path, which breaks logins if it is rewritten: -

- -
-<exclusion pattern="^http://(?:\w+\.)?stack(?:exchange|overflow)\.com/users/authenticate/" />
-
- -

- Exclusions are always evaluated before rules in a given ruleset. Matching any - exclusion means that a URL won't match any rules within the same ruleset. - However, if other rulesets match the same target hosts, the rules in those - rulesets will still be tried. -

- -

Style Guide -

- -

-There are many different ways you can write a ruleset, or regular expression -within the ruleset. It's easier for everyone to understand the rulesets if they -follow similar practices. You should read and follow the -Ruleset -style guide. Some of the guidelines in that document are intended to make Ruleset -testing less cumbersome. -

- -

Secure Cookies -

- -

-Many HTTPS websites fail to correctly set the secure -flag on authentication and/or tracking cookies. HTTPS -Everywhere provides a facility for turning this flag on. For instance: -

- -
<securecookie host="^market\.android\.com$" name=".+" />
- -

-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. For a cookie to be secured, -it must be sent by a target host for that ruleset. It must also be sent over -HTTPS and match the name regexp. For cookies set by Javascript in a web page, -the Firefox extension can't tell which host set the cookie and instead uses -the domain attribute of the cookie to check against target hosts. A cookie whose -domain attribute starts with a "." (the default, if not specified by -Javascript) will be matched as if it was sent from a host -name made by stripping the leading dot. -

- -

Testing -

- -

-We use an automated -checker to run some basic tests on all rulesets. This is described in more -detail in our Ruleset -Testing document, but in short there are two parts: Your ruleset must have -enough test URLs to cover all the various types of URL covered by your rules. -And each of those test URLs must load, both before rewriting and after -rewriting. Every target host tag generates an implicit test URL unless it -contains a wildcard. You can add additional test URLs manually using the -<test url="..."/> tag. The test URLs you add this way should be -real pages loaded from the site, or real images, CSS, and Javascript if you have rules that -specifically affect those resources. -

- -

-You should also manually test your ruleset 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. -

- -

- If you've tested your rule and are sure it would - be of use to the world at large, submit it as a pull - request on our GitHub - repository or 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. -

- -

make-trivial-rule -

- -

-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 cause problems -that make them unsuitable for being enabled by default in everyone's -browsers. Typically when a ruleset has problems we will disable it by -default until someone has time to fix it. You can do this by adding -a default_off attribute to the ruleset element, with a value -explaining why the rule is off. -

-
-<ruleset name="Amazon (buggy)" default_off="breaks site">
-   <target host="www.amazon.*" />
-   <target host="amazon.*" />
-</ruleset>
-
- -

-You can add more details, like a link to a bug report, in the comments for the -file. -

- -

Mixed Content Blocking (MCB) -

- -

- Some rulesets may trigger active mixed content (i.e. scripts loaded over HTTP - instead of HTTPS). This type of mixed content is blocked in both Chrome and - Firefox, before HTTPS Everywhere has a chance to rewrite the URLs to an HTTPS - version. This generally breaks the site. - However, the Tor Browser doesn't block mixed content, in order to allow HTTPS - Everywhere to try and rewrite the URLs to an HTTPS version. -

- -

- To enable a rule only on platforms that allow mixed content (currently - only the Tor Browser), you can add a platform="mixedcontent" - attribute to the ruleset element. -

- -

HTTPS->HTTP downgrade rules -

- -

- By default, HTTPS Everywhere will refuse to allow rules that - would downgrade a URL from HTTPS to HTTP. Occasionally, this is necessary - because the extension rewrites a page to HTTPS, and that page contains relative - links to resources which do not exist on the HTTPS part of the site. - This is very rare, especially because these resources will typically be blocked - by Mixed Content Blocking. If it necessary, you can - add a downgrade="1" attribute to the rule to make it easier to audit - the ruleset library for such rules. -

diff --git a/docs/rulesets.md b/docs/rulesets.md new file mode 100644 index 000000000000..1def63c41232 --- /dev/null +++ b/docs/rulesets.md @@ -0,0 +1,105 @@ +This page describes how to write rulesets for [HTTPS Everywhere](https://eff.org/https-everywhere), a browser extension that switches sites over from HTTP to HTTPS automatically. HTTPS Everywhere comes with [thousands](http://www.eff.org/https-everywhere/atlas/) of rulesets that tell HTTPS Everywhere which sites it should switch to HTTPS and how. If there is a site that offers HTTPS and is not handled by the extension, this guide will explain how to add that site. + +#### [Rulesets](#rulesets) + +A `ruleset` is an [XML](http://www.xml.com/pub/a/98/10/guide0.html?page=2) file describing behavior for a site or group of sites. A ruleset contains one or more `rules`. For example, here is [`RabbitMQ.xml`](https://github.com/efforg/https-everywhere/blob/master/src/chrome/content/rules/RabbitMQ.xml), from the addon distribution: + +```xml + + + + + + +``` + +The `target` tag specifies which web sites the ruleset applies to. The `rule` tag specifies how URLs on those web sites should be rewritten. This rule says that any URLs on `rabbitmq.com` and `www.rabbitmq.com` should be modified by replacing "http:" with "https:". + +When the browser loads a URL, HTTPS Everywhere takes the host name (e.g. www.rabbitmq.com) and searches its ruleset database for rulesets that match that host name. + +HTTPS Everywhere then tries each rule in those rulesets against the full URL. If the [Regular Expression](http://www.regular-expressions.info/quickstart.html), or regexp, in one of those rules matches, HTTPS Everywhere [rewrites the URL](#rules-and-regular-expressions) according the `to` attribute of the rule. + +#### [Wildcard Targets](#wildcard-targets) + +To cover all of a domain's subdomains, you may want to specify a wildcard target like `*.twitter.com`. Specifying this type of left-side wildcard matches any host name with `.twitter.com` as a suffix, e.g. `www.twitter.com` or `urls.api.twitter.com`. You can also specify a right-side wildcard like `www.google.*`. Right-side wildcards, unlike left-side wildcards, apply only one level deep. So if you want to cover all countries you'll generally need to specify `www.google.*`, `www.google.co.*`, and `www.google.com.*` to cover domains like `www.google.co.uk` or `www.google.com.au`. You should use wildcard targets only when you have rules that apply to the entire wildcard space. If your rules only apply to specific hosts, you should list each host as a separate target. + +#### [Rules and Regular Expressions](#rules-and-regular-expressions) + +The `rule` tags do the actual rewriting work. The `from` attribute of each rule is a [regular expression](http://www.regular-expressions.info/quickstart.html) matched against a full URL. You can use rules to rewrite URLs in simple or complicated ways. Here's a simplified (and now obsolete) example for Wikipedia: + +```xml + + + + + +``` + +The `to` attribute replaces the text matched by the `from` attribute. It can contain placeholders like `$1` that are replaced with the text matched inside the parentheses. + +This rule 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". + +Rules are applied in the order they are listed within each ruleset. Order between rulesets is unspecified. Only the first rule or exception matching a given URL is applied. + +Rules are evaluated using [Javascript regular expressions](http://www.regular-expressions.info/javascript.html), which are similar but not identical to [Perl-style regular expressions.](http://www.regular-expressions.info/pcre.html) Note that if your rules include ampersands (&), they need to be appropriately XML-encoded: replace each occurrence of **&** with **&#x26;**. + +#### [Exclusions](#exclusions) + +An exclusion specifies a pattern, using a regular expression, for URLs where the rule should **not** be applied. The Stack Exchange rule contains an exclusion for the OpenID login path, which breaks logins if it is rewritten: + +```xml + +``` + +Exclusions are always evaluated before rules in a given ruleset. Matching any exclusion means that a URL won't match any rules within the same ruleset. However, if other rulesets match the same target hosts, the rules in those rulesets will still be tried. + +#### [Style Guide](#style-guide) + +There are many different ways you can write a ruleset, or regular expression within the ruleset. It's easier for everyone to understand the rulesets if they follow similar practices. You should read and follow the [Ruleset style guide](https://github.com/EFForg/https-everywhere/blob/master/ruleset-style.md). Some of the guidelines in that document are intended to make [Ruleset testing](https://github.com/EFForg/https-everywhere/blob/master/ruleset-testing.md) less cumbersome. + +#### [Secure Cookies](#secure-cookies) + +Many HTTPS websites fail to correctly set the [secure flag](https://secure.wikimedia.org/wikipedia/en/wiki/HTTP_cookie#Secure_and_HttpOnly) on authentication and/or tracking cookies. HTTPS Everywhere provides a facility for turning this flag on. For instance: + +```xml + +``` + +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. For a cookie to be secured, it must be sent by a target host for that ruleset. It must also be sent over HTTPS and match the name regexp. For cookies set by Javascript in a web page, the Firefox extension can't tell which host set the cookie and instead uses the domain attribute of the cookie to check against target hosts. A cookie whose domain attribute starts with a "." (the default, if not specified by Javascript) will be matched as if it was sent from a host name made by stripping the leading dot. + +#### [Testing](#testing) + +We use an [automated checker](https://github.com/hiviah/https-everywhere-checker) to run some basic tests on all rulesets. This is described in more detail in our [Ruleset Testing](https://github.com/EFForg/https-everywhere/blob/master/ruleset-testing.md) document, but in short there are two parts: Your ruleset must have enough test URLs to cover all the various types of URL covered by your rules. And each of those test URLs must load, both before rewriting and after rewriting. Every target host tag generates an implicit test URL unless it contains a wildcard. You can add additional test URLs manually using the `` tag. The test URLs you add this way should be real pages loaded from the site, or real images, CSS, and Javascript if you have rules that specifically affect those resources. + +You should also manually test your ruleset by placing it in the `HTTPSEverywhereUserRules/` subdirectory in [your Firefox profile directory](http://kb.mozillazine.org/Profile_folder_-_Firefox), 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. + +If you've tested your rule and are sure it would be of use to the world at large, submit it as a [pull request](https://help.github.com/articles/using-pull-requests/) on our [GitHub repository](https://github.com/EFForg/https-everywhere/) or 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. + +#### [make-trivial-rule](#make-trivial-rule) + +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](https://www.eff.org/https-everywhere/development). + +#### [Disabling a ruleset by default](#disabling-a-ruleset-by-default) + +Sometimes rulesets are useful or interesting, but cause problems that make them unsuitable for being enabled by default in everyone's browsers. Typically when a ruleset has problems we will disable it by default until someone has time to fix it. You can do this by adding a `default_off` attribute to the ruleset element, with a value explaining why the rule is off. + +```xml + + + + +``` + +You can add more details, like a link to a bug report, in the comments for the file. + +#### [Mixed Content Blocking (MCB)](#mixed-content-blocking-mcb) + +Some rulesets may trigger active mixed content (i.e. scripts loaded over HTTP instead of HTTPS). This type of mixed content is blocked in both [Chrome](https://trac.torproject.org/projects/tor/ticket/6975) and Firefox, before HTTPS Everywhere has a chance to rewrite the URLs to an HTTPS version. This generally breaks the site. However, the Tor Browser doesn't block mixed content, in order to allow HTTPS Everywhere to try and rewrite the URLs to an HTTPS version. + +To enable a rule only on platforms that allow mixed content (currently only the Tor Browser), you can add a `platform="mixedcontent"` attribute to the ruleset element. + +#### [HTTPS->HTTP downgrade rules](#https-http-downgrade-rules) + +By default, HTTPS Everywhere will refuse to allow rules that would downgrade a URL from HTTPS to HTTP. Occasionally, this is necessary because the extension rewrites a page to HTTPS, and that page contains relative links to resources which do not exist on the HTTPS part of the site. This is very rare, especially because these resources will typically be blocked by [Mixed Content Blocking](#mixed-content-blocking-mcb). If it necessary, you can add a `downgrade="1"` attribute to the rule to make it easier to audit the ruleset library for such rules. From 66149017141d4b2067b18c698b61fca3f9083052 Mon Sep 17 00:00:00 2001 From: William Budington Date: Mon, 7 Nov 2016 17:22:16 -0800 Subject: [PATCH 2/5] Adding FAQ markdown --- docs/faq.md | 136 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 docs/faq.md diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 000000000000..ad73062aa14e --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,136 @@ +## HTTPS Everywhere FAQ + +This page answers frequently-asked questions about EFF's [HTTPS Everywhere](https://www.eff.org/https-everywhere) project. If your question isn't answered below, you can try the resources [listed here](https://www.eff.org/https-everywhere/development). + +- [What if HTTPS Everywhere breaks some site that I use?](#what-if-https-everywhere-breaks-some-site-that-i-use) +- [Why is HTTPS Everywhere preventing me from joining this hotel/school/other wireless network?](#why-is-https-everywhere-preventing-me-from-joining-this-hotelschoolother-wireless-network) +- [Will there be a version of HTTPS Everywhere for IE, Safari, or some other browser?](#will-there-be-a-version-of-https-everywhere-for-ie-safari-or-some-other-browser) +- [Why use a whitelist of sites that support HTTPS? Why can't you try to use HTTPS for every last site, and only fall back to HTTP if it isn't available?](#why-use-a-whitelist-of-sites-that-support-https-why-cant-you-try-to-use-https-for-every-last-site-and-only-fall-back-to-http-if-it-isnt-available) +- [How do I get rid of/move the HTTPS Everywhere button in the toolbar?](#how-do-i-get-rid-ofmove-the-https-everywhere-button-in-the-toolbar) +- [When does HTTPS Everywhere protect me? When does it not protect me?](#when-does-https-everywhere-protect-me-when-does-it-not-protect-me) +- [What does HTTPS Everywhere protect me against?](#what-does-https-everywhere-protect-me-against) +- [How do I get support for an additional site in HTTPS Everywhere?](#how-do-i-get-support-for-an-additional-site-in-https-everywhere) +- [What if the site doesn't support HTTPS, or only supports it for some activities, like entering credit card information?](#what-if-the-site-doesnt-support-https-or-only-supports-it-for-some-activities-like-entering-credit-card-information) +- [Isn't it more expensive or slower for a site to support HTTPS compared to regular HTTP?](#isnt-it-more-expensive-or-slower-for-a-site-to-support-https-compared-to-regular-http) +- [Why should I use HTTPS Everywhere instead of just typing https:// at the beginning of site names?](#why-should-i-use-https-everywhere-instead-of-just-typing-https-at-the-beginning-of-site-names) +- [Why does HTTPS Everywhere include rules for sites like PayPal that already require HTTPS on all their pages?](#why-does-https-everywhere-include-rules-for-sites-like-paypal-that-already-require-https-on-all-their-pages) +- [What do the different colors for rulesets in the Firefox toolbar menu mean?](#what-do-the-different-colors-for-rulesets-in-the-firefox-toolbar-menu-mean) +- [What do the different colors of the HTTPS Everywhere icon mean?](#what-do-the-different-colors-of-the-https-everywhere-icon-mean) +- [I'm having a problem installing the browser extension.](#im-having-a-problem-installing-the-browser-extension.) +- [How do I uninstall/remove HTTPS Everywhere?](#how-do-i-uninstallremove-https-everywhere) +- [How do I add my own site to HTTPS Everywhere?](#how-do-i-add-my-own-site-to-https-everywhere) +- [Can I help translate HTTPS Everywhere into my own language?](#can-i-help-translate-https-everywhere-into-my-own-language) + +### [What if HTTPS Everywhere breaks some site that I use?](#what-if-https-everywhere-breaks-some-site-that-i-use) + +This is occasionally possible because of inconsistent support for HTTPS on sites (e.g., when a site seems to support HTTPS access but makes a few, unpredictable, parts of the site unavailable in HTTPS). If you [report the problem to us](https://github.com/EFForg/https-everywhere/issues), we can try to fix it. In the meantime, you can disable the rule affecting that particular site in your own copy of HTTPS Everywhere by clicking on the HTTPS Everywhere toolbar button and unchecking the rule for that site. + +You can also report the problem to the site, since they have the power to fix it! + +### [Why is HTTPS Everywhere preventing me from joining this hotel/school/other wireless network?](#why-is-https-everywhere-preventing-me-from-joining-this-hotelschoolother-wireless-network) + +Some wireless networks hijack your HTTP connections when you first join them, in order to demand authentication or simply to try to make you agree to terms of use. HTTPS pages are protected against this type of hijacking, which is as it should be. If you go to a website that isn't protected by HTTPS Everywhere (currently, nytimes.com is one such site) that will allow your connection to be captured and redirected to the authentication or terms of use page. + +### [Will there be a version of HTTPS Everywhere for IE, Safari, or some other browser?](#will-there-be-a-version-of-https-everywhere-for-ie-safari-or-some-other-browser) + +As of early 2012, the Safari extension API does not offer a way to perform secure rewriting of http requests to https. But if you happen to know a way to perform secure request rewriting in these browsers, feel free to let us know at https-everywhere at EFF.org (but note that modifying document.location or window.location in JavaScript is not secure). + +### [Why use a whitelist of sites that support HTTPS? Why can't you try to use HTTPS for every last site, and only fall back to HTTP if it isn't available?](#why-use-a-whitelist-of-sites-that-support-https-why-cant-you-try-to-use-https-for-every-last-site-and-only-fall-back-to-http-if-it-isnt-available) + +There are several problems with the idea of trying to automatically detect HTTPS on every site. There is no guarantee that sites are going to give the same response via HTTPS that they give via HTTP. Also, it's not possible to test for HTTPS in real time without introducing security vulnerabilities (What should the extension do if the HTTPS connection attempt fails? Falling back to insecure HTTP isn't safe). And in some cases, HTTPS Everywhere has to perform quite complicated transformations on URIs — for example until recently the Wikipedia rule had to turn an address like `http://en.wikipedia.org/wiki/World_Wide_Web` into one like `https://secure.wikimedia.org/wikipedia/en/wiki/World_Wide_Web` because HTTPS was not available on Wikipedia's usual domains. + +### [How do I get rid of/move the HTTPS Everywhere button in the toolbar?](#how-do-i-get-rid-ofmove-the-https-everywhere-button-in-the-toolbar) + +The HTTPS Everywhere button is useful because it allows you to see, and disable, a ruleset if it happens to be causing problems with a site. But if you'd rather disable it, go to View->Toolbars->Customize, and drag the button out of the toolbar into the Addons bar at the bottom of the page. Then you can hide the Addons bar. (In theory you should be able to drag it into the tray of available icons too, but that may trigger [this bug](https://trac.torproject.org/projects/tor/ticket/6276). + +### [When does HTTPS Everywhere protect me? When does it not protect me?](#when-does-https-everywhere-protect-me-when-does-it-not-protect-me) + +HTTPS Everywhere protects you only when you are using _encrypted portions of supported web sites_. On a supported site, it will automatically activate HTTPS encryption for all known supported parts of the site (for some sites, this might be only a portion of the entire site). For example, if your web mail provider does not support HTTPS at all, HTTPS Everywhere can't make your access to your web mail secure. Similarly, if a site allows HTTPS for text but not images, someone might be able to see which images your browser loads and guess what you're accessing. + +HTTPS Everywhere depends entirely on the security features of the individual web sites that you use; it _activates_ those security features, but it can't _create_ them if they don't already exist. If you use a site not supported by HTTPS Everywhere or a site that provides some information in an insecure way, HTTPS Everywhere can't provide additional protection for your use of that site. Please remember to check that a particular site's security is working to the level you expect before sending or receiving confidential information, including passwords. + +One way to determine what level of protection you're getting when using a particular site is to use a packet-sniffing tool like [Wireshark](https://www.wireshark.org/) to record your own communications with the site. The resulting view of your communications is about the same as what an eavesdropper on your wifi network or at your ISP would see. This way, you can determine whether some or all of your communications would be protected; however, it may be quite time-consuming to make sense of the Wireshark output with enough care to get a definitive answer. + +You can also turn on the "Block all HTTP requests" feature for added protection. Instead of loading insecure pages or images, HTTPS Everywhere will block them outright. + +### [What does HTTPS Everywhere protect me against?](#what-does-https-everywhere-protect-me-against) + +On supported parts of supported sites, HTTPS Everywhere enables the sites' HTTPS protection which can protect you against eavesdropping and tampering with the contents of the site or with the information you send to the site. Ideally, this provides some protection against an attacker learning the content of the information flowing in each direction — for instance, the text of e-mail messages you send or receive through a webmail site, the products you browse or purchase on an e-commerce site, or the particular articles you read on a reference site. + +However, HTTPS Everywhere **does not conceal the identities of the sites you access**, the amount of time you spend using them, or the amount of information you upload or download from a particular site. For example, if you access `http://www.eff.org/issues/nsa-spying` and HTTPS Everywhere rewrites it to `https://www.eff.org/issues/nsa-spying`, an eavesdropper can still trivially recognize that you are accessing www.eff.org (but might not know which issue you are reading about). In general, the entire hostname part of the URL remains exposed to the eavesdropper because this must be sent repeatedly in unencrypted form while setting up the connection. Another way of saying this is that HTTPS was never designed to conceal the identity of the sites that you visit. + +Researchers have also shown that it may be possible for someone to figure out more about what you're doing on a site merely through careful observation of the amount of data you upload and download, or the timing patterns of your use of the site. A simple example is that if the site only has one page of a certain total size, anyone downloading exactly that much data from the site is probably accessing that page. + +If you want to protect yourself against monitoring of the sites you visit, consider using HTTPS Everywhere together with software like [Tor](https://www.torproject.org/). + +### [How do I get support for an additional site in HTTPS Everywhere?](#how-do-i-get-support-for-an-additional-site-in-https-everywhere) + +You can learn [how to write rules](https://www.eff.org/https-everywhere/rulesets) that teach HTTPS Everywhere to support new sites. You can install these rules in your own browser or send them to us for possible inclusion in the official version. + +### [What if the site doesn't support HTTPS, or only supports it for some activities, like entering credit card information?](#what-if-the-site-doesnt-support-https-or-only-supports-it-for-some-activities-like-entering-credit-card-information) + +You could try to contact the site and point out that using HTTPS for all site features is an increasingly common practice nowadays and protects users (and sites) against a variety of Internet attacks. For instance, it defends against the ability of other people on a wifi network to spy on your use of the site or even take over your account. You can also point out that credit card numbers aren't the only information you consider private or sensitive. + +Sites like Google, Twitter, and Facebook now support HTTPS for non-financial information — for general privacy and security reasons. + +### [Isn't it more expensive or slower for a site to support HTTPS compared to regular HTTP?](#isnt-it-more-expensive-or-slower-for-a-site-to-support-https-compared-to-regular-http) + +It can be, but some sites have been pleasantly surprised to see how practical it can be. Also, experts at Google are currently implementing several enhancements to the TLS protocol that make HTTPS dramatically faster; if these enhancements are added to the standard soon, the speed gap between the two should almost disappear. See [Adam Langley's description of the HTTPS deployment situation](https://www.imperialviolet.org/2010/06/25/overclocking-ssl.html) for more details on these issues. Notably, Langley states: "In order to [enable HTTPS by default for Gmail] we had to deploy no additional machines and no special hardware. On our production frontend machines, SSL/TLS accounts for less than 1% of the CPU load, less than 10KB of memory per connection and less than 2% of network overhead." + +It used to be expensive to purchase a certificate for HTTPS usage, but they can now be obtained for free from [Let's Encrypt](https://letsencrypt.org/) as well. + +### [Why should I use HTTPS Everywhere instead of just typing https:// at the beginning of site names?](#why-should-i-use-https-everywhere-instead-of-just-typing-https-at-the-beginning-of-site-names) + +Even if you normally type https://, HTTPS Everywhere might protect you if you occasionally forget. Also, it can rewrite other people's links that you follow. For instance, if you click on a link to `http://en.wikipedia.org/wiki/EFF_Pioneer_Award`, HTTPS Everywhere will automatically rewrite the link to `https://en.wikimedia.org/wikipedia/en/wiki/EFF_Pioneer_Award`. Thus, you might get some protection even if you wouldn't have noticed that the target site is available in HTTPS. + +### [Why does HTTPS Everywhere include rules for sites like PayPal that already require HTTPS on all their pages?](#why-does-https-everywhere-include-rules-for-sites-like-paypal-that-already-require-https-on-all-their-pages) + +HTTPS Everywhere, like the [HSTS spec](https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security), tries to address an attack called [SSL stripping](https://moxie.org/software/sslstrip/). Users are only protected against the SSL stripping attack if their browsers don't even _try_ to connect to the HTTP version of the site — even if the site would have redirected them to the HTTPS version. With HTTPS Everywhere, the browser won't even attempt the insecure HTTP connection, even if that's what you ask it to do. (Note that HTTPS Everywhere currently does not include a comprehensive list of such sites, which are mainly financial institutions.) + +### [What do the different colors for rulesets in the Firefox toolbar menu mean?](#what-do-the-different-colors-for-rulesets-in-the-firefox-toolbar-menu-mean) + +The colors are: + +Dark Green: ruleset was active in loading the resources in the current page. + +Light Green: ruleset was ready to prevent HTTP loads in the current page, but everything that the ruleset would have covered was loaded over HTTPS anyway (in the code, light green is called a "moot rule"). + +Dark Brown or Clockwise Red Arrow: broken rule -- the ruleset is active but the server is redirecting at least some URLs back from HTTPS to HTTP. + +Gray: the ruleset is disabled. + +### [What do the different colors of the HTTPS Everywhere icon mean?](#what-do-the-different-colors-of-the-https-everywhere-icon-mean) + +The colors are: + +Light Blue: HTTPS Everywhere is enabled. + +Dark Blue: HTTPS Everywhere is both enabled and active in loading resources in the current page. + +Red: All unencrypted requests will be blocked by HTTPS Everywhere. + +Gray: HTTPS Everywhere is disabled. + +### [I'm having a problem installing the browser extension.](#im-having-a-problem-installing-the-browser-extension.) + +Some people report that installing HTTPS Everywhere gives them the error: "The addon could not be downloaded because of a connection failure on www.eff.org." This may be caused by Avast anti-virus, which blocks installation of browser extensions. You may be able to [install from addons.mozilla.org instead](https://addons.mozilla.org/en-US/firefox/addon/https-everywhere/). + +### [How do I uninstall/remove HTTPS Everywhere?](#how-do-i-uninstallremove-https-everywhere) + +In Firefox: Click the menu button in the top right of the window at the end of the toolbar (it looks like three horizontal lines), and then click "Add-ons" (it looks like a puzzle piece). Scroll until you see HTTPS Everywhere, and then click the "Remove" button all the way on the right. You can then safely close the Add-ons tab. + +In Chrome: Click the menu button in the top right of the window at the end of the toolbar (it looks like three horizontal lines), and then click "Settings" near the bottom. On the left, click "Extensions". Scroll until you see HTTPS Everywhere, and then click the trash can icon on the right, and then click "Remove" to confirm removal. You can then safely close the Settings tab. + +### [How do I add my own site to HTTPS Everywhere?](#how-do-i-add-my-own-site-to-https-everywhere) + +We're excited that you want your site in HTTPS Everywhere! However, remember that not everyone who visits your site has our extension installed. If you run a web site, you can make it default to HTTPS for everyone, not just HTTPS Everywhere users. And it's less work! The steps you should take, in order, are: + +1. Set up a [redirect](https://www.sslshopper.com/apache-redirect-http-to-https.html) from HTTP to HTTPS on your site. +2. [Add the Strict-Transport-Security (HSTS) header on your site.](https://raymii.org/s/tutorials/HTTP_Strict_Transport_Security_for_Apache_NGINX_and_Lighttpd.html) +3. [Add your site to the HSTS Preload list.](https://hstspreload.appspot.com/) + +These steps will give your site much better protection than adding it to HTTPS Everywhere. Generally speaking, once you are done, there is no need to add your site to HTTPS Everywhere. However, if you would still like to, please follow the [instructions on writing rulesets](https://eff.org/https-everywhere/rulesets), and indicate that you are the author of the web site when you submit your pull request. + +### [Can I help translate HTTPS Everywhere into my own language? ](#can-i-help-translate-https-everywhere-into-my-own-language) + +Yes! We use the Tor Project's Transifex account for translations, please sign up to help translate at [https://www.transifex.com/otf/torproject](https://www.transifex.com/otf/torproject). From 5832f4372bdd0d7a04487ebc821a4682c9db875c Mon Sep 17 00:00:00 2001 From: William Budington Date: Mon, 7 Nov 2016 17:22:40 -0800 Subject: [PATCH 3/5] Add header to rulesets markdown --- docs/rulesets.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/rulesets.md b/docs/rulesets.md index 1def63c41232..1f4a8b7685cc 100644 --- a/docs/rulesets.md +++ b/docs/rulesets.md @@ -1,3 +1,5 @@ +## HTTPS Everywhere Rulesets + This page describes how to write rulesets for [HTTPS Everywhere](https://eff.org/https-everywhere), a browser extension that switches sites over from HTTP to HTTPS automatically. HTTPS Everywhere comes with [thousands](http://www.eff.org/https-everywhere/atlas/) of rulesets that tell HTTPS Everywhere which sites it should switch to HTTPS and how. If there is a site that offers HTTPS and is not handled by the extension, this guide will explain how to add that site. #### [Rulesets](#rulesets) From 5681cfe4d14268e7aa5923b185468c40570879ba Mon Sep 17 00:00:00 2001 From: William Budington Date: Mon, 7 Nov 2016 17:45:34 -0800 Subject: [PATCH 4/5] Creating a development page markdown --- docs/development.md | 82 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 82 insertions(+) create mode 100644 docs/development.md diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 000000000000..0388e2573ea7 --- /dev/null +++ b/docs/development.md @@ -0,0 +1,82 @@ +## HTTPS Everywhere Development + +### Pointers for developers + +- **License:** GPL version 3+ (although most of the code is GPL-2 compatible) +- **Source code:** Available via Git with `git clone https://github.com/EFForg/https-everywhere.git`. You can fork and open pull requests using Github at [https://github.com/EFForg/https-everywhere](https://github.com/EFForg/https-everywhere). +- **Translations:** If you would like to help translate HTTPS Everywhere into another language, you can do that [through Transifex](https://www.transifex.com/otf/torproject/). +- **Bug tracker:** Use the [GitHub issue tracker](https://github.com/EFForg/https-everywhere/issues/) or the [Tor Project issue tracker](https://trac.torproject.org/projects/tor/report/19). For the Tor Project issue tracker, you can make an account or use the anonymous one — "cypherpunks"/"writecode". You won't see replies unless you put an email address in the CC field. Bugs that are caused by rulesets should be tagged "httpse-ruleset-bug", and can be viewed [in this report](https://trac.torproject.org/projects/tor/report/48). +- **Mailing lists:** The [https-everywhere](https://lists.eff.org/mailman/listinfo/https-everywhere) list ([archives](https://lists.eff.org/pipermail/https-everywhere/)) is for discussing the project as a whole; the [https-everywhere-rules](https://lists.eff.org/mailman/listinfo/https-everywhere-rules) mailing list ([archives](https://lists.eff.org/pipermail/https-everywhere-rules)) is for discussing the [rulesets](https://www.eff.org/https-everywhere/rulesets) and their contents, including patches and git pull requests. +- **IRC:** `#https-everywhere` on `irc.oftc.net`. If you ask a question, be sure to stay in the channel — someone may reply a few hours or a few days later. + +### Testing and contributing changes to the source code + +HTTPS Everywhere consists of a large number of rules for switching sites from HTTP to HTTPS. You can read more about how to write these rules [here](https://www.eff.org/https-everywhere/rulesets). + +If you want to create new rules to submit to us, we expect them to be in the src/chrome/content/rules directory. That directory also contains a useful script, make-trivial-rule, to create a simple rule for a specified domain. There is also a script called trivial-validate.py, to check all the pending rules for several common errors and oversights. For example, if you wanted to make a rule for the example.com domain, you could run + + bash ./make-trivial-rule example.com + +inside the rules directory. This would create Example.com.xml, which you could then take a look at and edit based on your knowledge of any specific URLs at example.com that do or don't work in HTTPS. + +Before submitting your change, you should test it in Firefox and/or Chrome, as applicable. You can build the latest version of the extension and run it in a standalone Firefox profile using: + + bash ./test.sh --justrun + +Similarly, to build and run in a standalone Chromium profile, run: + + bash ./run-chromium.sh + +You should thoroughly test your changes on the target site: Navigate to as wide a variety of pages as you can find. Try to comment or log in if applicable. Make sure everything still works properly. + +After running your manual tests, run the automated tests and the fetch tests: + + bash ./test.sh + + bash ./fetch-test.sh + +This will catch some of the most common types of errors, but is not a guaranteed of correctness. + +Once you've tested your changes, you can submit them for review via any of the following: + +- Open a pull request at [https://github.com/EFForg/https-everywhere](https://github.com/EFForg/https-everywhere). +- Email https-everywhere-rules@eff.org to tell us about your changes. You can use the following command to create a patch file: `git format-patch` + +### A quick HOWTO on working with Git + +You may want to also look at the [Git Reference](http://gitref.org/), [GitHub Help Site](https://help.github.com/) and the [Tor Project's Git documentation](https://gitweb.torproject.org/githax.git/tree/doc/Howto.txt) to fill in the gaps here, but the below should be enough to get the basics of the workflow down. + +First, tell git your name: + + git config --global user.name "Your Name" git config --global user.email "you@example.com" + +Then, get a copy of the 'origin' repository: + + git clone https://github.com/EFForg/https-everywhere.git + cd https-everywhere + +Alternatively, if you already have a Github account, you can create a "fork" of the repository on Github at [https://github.com/EFForg/https-everywhere](https://github.com/EFForg/https-everywhere). See [this page](https://help.github.com/articles/fork-a-repo) for a tutorial. + +Once you have a local copy of the repository, create a new branch for your changes and check it out: + + git checkout -b my-new-rules master + +When you want to send us your work, you'll need to add any new files to the index with git add: + + git add ./src/chrome/content/rules/MyRule1.xml + git add ./src/chrome/content/rules/MyRule2.xml + +You can now commit your changes to the local branch. To make things easier, you should commit each xml file individually: + + git commit ./src/chrome/content/rules/MyRule1.xml + git commit ./src/chrome/content/rules/MyRule2.xml + +Now, you need a place to publish your changes. You can create a github account here: [https://github.com/join](https://help.github.com/). [https://help.github.com/](https://help.github.com/) describes the account creation process and some other github-specific things. + +Once you have created your account and added your remote in your local checkout, you want to push your branch to your github remote: + + git push github my-new-rules:my-new-rules + +Periodically, you should re-fetch the master repository: + + git pull master From 0b50b4b692f9187c1caa3db5b742c60450f11c09 Mon Sep 17 00:00:00 2001 From: William Budington Date: Mon, 7 Nov 2016 18:37:53 -0800 Subject: [PATCH 5/5] Adding README.md to documentation --- docs/README.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 docs/README.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000000..3a7d52816e87 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,7 @@ +# HTTPS Everywhere Documentation + +The markdown files contained in this path provide documentation for contributing to HTTPS Everywhere. These files are also templates that can be used to generate the markup for HTTPS Everywhere pages under `https://www.eff.org/https-everywhere`. To do so, install the program `pandoc` and run + + pandoc faq.md + +Copy the output, excluding the header on the first line, to the source of the relevant page within the CMS. Note that some of the pages are dynamically generated and are not generated from templates contained here.