wiki:torbirdy

Codename: TorBirdy

TorBirdy is Torbutton for Thunderbird, Icedove and related Mozilla mail clients. It may also work with other non-web browser Mozilla programs such as Sunbird.

Installation | Mozilla Add-ons (XPI) | Source Code | Tickets

Status

TorBirdy is in beta and should be considered experimental. Please make sure that before using it, you are aware of the known issues and leaks by reading the Before using TorBirdy and Known TorBirdy Issues sections below.

You may also read our design goals document (PDF) to understand what we are trying to accomplish with TorBirdy for our users.

Quick Setup Guide

This short guide should help you to set up your Thunderbird email client to send and fetch email via Tor. It can be used for both new and existing email accounts in Thunderbird.

Please bear in mind that email accounts that have been used without Tor before offer less privacy/anonymity/weaker pseudonyms than email accounts that have always been accessed with Tor. But nevertheless, TorBirdy is still useful for existing accounts or real-name email addresses. For example, if you are looking for location anonymity -- you travel a lot and don't want to disclose all your locations by sending emails, TorBirdy works wonderfully!

TorBirdy works with SMTP and IMAP/POP3 but POP3 is recommended over IMAP because POP3 is a much simpler protocol and less likely to have or introduce any new sketchy features.

We have a screencast (ogv) that covers email account configuration (inserting the correct mailserver domain, username, ...) with TorBirdy for a Gmail account. JonDo also has a guide that details configuring your email accounts for use with TorBirdy, among other helpful information.

Before using TorBirdy

The preferences TorBirdy changes are documented here.

When you install TorBirdy, it modifies and adds many preferences to configure Thunderbird to be used securely over the Tor network.

TorBirdy enforces the preferences it sets and attempts to change them using Thunderbird's settings or the configuration editor will not work as all such changes will be discarded when Thunderbird restarts. This is because we believe that these preferences should not be changed, whether deliberately, by mistake, or due to another extension, as doing so can compromise your anonymity. There are however some preferences that can be changed and they can be accessed through TorBirdy's preferences dialog. Please note that if you are not an advanced user, you should NOT change any setting unless you are very sure of what you are doing.

The preferences that TorBirdy changes are restored to their original values when it is uninstalled or disabled, thus restoring your Thunderbird's state to exactly what it was prior to TorBirdy's installation. If you find that TorBirdy leaves evidence of its installation in any way, please file a bug report.

Configuration

See the preferences page for information about TorBirdy preferences and how you can configure them.

Required Software

TorBirdy is currently available in two forms:

Standalone TorBirdy

Available through Mozilla Add-ons: https://addons.mozilla.org/en-us/thunderbird/addon/torbirdy/

Standalone TorBirdy is just the TorBirdy extension. You need to have the Tor binary available, whether through the daemon or the Tor Browser Bundle for the standalone version of TorBirdy to function. This is considered stable and is the recommended method of using TorBirdy.

  • Components Required
    • Thunderbird
    • Tor

TorBirdy with Tor and Tor Launcher

Distributed using torproject.org: https://people.torproject.org/~sukhbir/torbirdy/

Starting 0.1.2, TorBirdy is also available in a single bundle (extension) with Tor and Tor Launcher. Because all required components are bundled in a single package, you do not need the Tor daemon or the Tor Browser Bundle. Only advanced users should be using this bundle as it is still in the alpha stage and bugs are to be expected.

  • Components Required
    • Thunderbird

To use the above package, it is recommended that you create a new profile or use this inside a VM. Creating and using profiles in Thunderbird is described on Thunderbird support. After that, simply install the extension corresponding to your relevant platform. You will be presented with an option to add two extensions: TorBirdy and Tor Launcher. Click on Install and then Thunderbird will restart and Tor Launcher will attempt to connect to Tor automatically and once that is done, Thunderbird will start with TorBirdy and Tor enabled.

Note that Tor has to start successfully for Thunderbird to be loaded; if Tor is unable to start and connect to the network, Thunderbird will not start because Tor Launcher will close it. We plan to fix this soon, but for now, you can set the environment variable TOR_SKIP_LAUNCH to 1 and then Tor Launcher will not start and you can use Thunderbird normally.

Setup Steps

  1. Install Tor:
  • On Windows and OS X, download and install the Tor Browser Bundle. When you want to use TorBirdy, you have to start the Bundle (if it is not already running.)
    • If you have never used the Tor Browser Bundle before, please follow the detailed guide by Security in-a-box.
  • On Unix, Linux and BSD you should use your distributor's packages, or if available, the ones provided by the torproject. You can of course also use the Tor Browser Bundle.
  • Regardless of the OS, make sure Tor is running with default client settings (SocksPort is listening on 127.0.0.1:9150).
  1. Install the TorBirdy extension:

NOTE: You can no longer install TorBirdy from Thunderbird's add-on manager because TorBirdy is preliminary reviewed by Mozilla. To get a full review, we have to allow the toggling of all preferences we set. As discussed above, we do not want to do that and therefore we have a preliminary and not a full review.

  • You can skip this step if you already have the TorBirdy XPI. If not, go to the Mozilla Add-ons page for TorBirdy at https://addons.mozilla.org/en-us/thunderbird/addon/torbirdy/. Right-click on Download Now and click Save Link As. Save the file to some location on your computer.
  • Start Thunderbird and go to Tools and then select Add-ons. On the right side, click on the Settings-like icon (click here for an example) next to the Search all add-ons text box. Then select Install Add-on From File and go to the location where you saved the XPI. Select it and click Open. Then finally click on Install. Thunderbird will then you to restart it; click on Restart Now. Now you should be ready to go, there is no further configuration required.

If you are using the TorBirdy with Tor bundle, you just need to follow step (2) above. We also have a video of this that shows how easy it is to use the TorBirdy + Tor bundle!

(If you have never done this before, we also have step-by-step instructions with screenshots of the above process on a Windows machine.)

Verifying the XPI

The TorBirdy XPI is signed by Jacob Appelbaum with the key 0x1245F783. As an example, verifying the current stable release of TorBirdy:

$ gpg --verify torbirdy-current.xpi.asc torbirdy-current.xpi
gpg: Signature made Mon 04 Nov 2013 06:43:51 AM EST using RSA key ID 1245F783
gpg: Good signature from "Jacob Appelbaum (offline long term identity key) <jacob@appelbaum.net>"
gpg:                 aka "Jacob Appelbaum (offline long term identity key) <jacob@torproject.org>"
gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
Primary key fingerprint: 228F AD20 3DE9 AE7D 84E2  5265 CF9A 6F91 4193 A197
     Subkey fingerprint: E729 FE2D EE92 DB51 1AC9  FF91 590C 7D91 1245 F783

The signature and TorBirdy releases are available at https://www.torproject.org/dist/torbirdy/.

Instructions for verifying the XPI on Windows and OS X are available on the verifying signatures page.

Installing TorBirdy in Debian

TorBirdy is in Debian starting version 0.1.2 (package: xul-ext-torbirdy). To install TorBirdy in Debian:

apt-get install xul-ext-torbirdy

Troubleshooting

If things don't work for you:

  1. Make sure Tor is running and listening on 127.0.0.1 (localhost) on port 9150.
  2. If you are using the Tor Browser Bundle, have a look at Vidalia's "Tor Network Map" to confirm that something is trying to use the Tor instance to connect to an SMTP/POP3/IMAP port while sending/fetching emails. If nothing is using your running Tor instance, Thunderbird is not connecting to your running Tor instance correctly. This could be because of the following reasons:
    • tor is not running
    • tor's SocksPort is not running on the expected port 127.0.0.1:9150.
    • TorBirdy was configured to connect to something else then 127.0.0.1:9150
  3. If you see Thunderbird connecting to Tor and it is still not working, try hitting the "New Identity" button in Vidalia; it might be the case that the mail server you are trying to connect to does not like your source IP address (bad exit node).

If none of the above works for you, come and talk to us! When asking for support, please make sure you include the version of Thunderbird and TorBirdy you are using (including the platform.) An easier and better way of getting this information is using Thunderbird itself: go to the Help menu, choose Troubleshooting and then select Copy text to clipboard. Before sending it to us, make sure you review the text to remove any information that you consider confidential. (By default, there is no information that can be used to identify you, but please check just to be sure.) The sections in the report that we need to help troubleshoot are Application Basics, Mail and News Accounts, and Extensions; feel free to remove other sections from the text.

Mailing List: | tor-talk

IRC: #tor, #tor-dev [irc.oftc.net]

FAQ

I am changing a preference but its value is reset when Thunderbird restarts. Why is this happening?

This is expected behaviour; please read the Before using TorBirdy section for more information.

How do I send and receive HTML emails?

HTML email is disabled both for sending and receiving mail. This is because HTML emails are unsafe and can compromise your identity; emails you send will be in plain text and HTML emails you receive will be sanitized and converted to plain text. You cannot change this behavior. (And you should not be sending HTML emails anyways!)

I noticed that the time information on received/sent messages is incorrect. Why is that?

The time is not incorrect but it is being reported in UTC (+0000) and not your local time zone. This is a side-effect of Thunderbird setting the time zone to UTC to prevent your local time zone (and thus your location) from being revealed. Please see the preferences page for more information.

Why is Thunderbird not checking for new messages automatically?

TorBirdy prevents Thunderbird from automatically checking for new messages at startup and after a fixed time interval (usually ten minutes). Please see the preferences page for more information.

Why are draft messages for IMAP accounts saved in Local Folders instead of the remote server?

Please see #10309 for more information. If you have multiple identities for an account that was created after TorBirdy was installed, please read comment:7:ticket:10309.

TorBirdy with Gmail

We have a screencast (ogv) that shows how you can configure a Gmail account with TorBirdy's manual account configuration wizard.

TorBirdy works fine with Gmail and there should be no issues except in rare cases where certain exit nodes cause Gmail to lock an account (and therefore POP/IMAP access) until the user logs in through the web interface and enters a CAPTCHA.

Mike Hearn from Google addressed this issue on tor-talk:

Access to Google accounts via Tor (or any anonymizing proxy service) is not allowed unless you have established a track record of using those services beforehand. You have several ways to do that:

1) With Tor active, log in via the web and answer a security quiz, if any is presented. You may need to receive a code on your phone. If you don't have a phone number on the account the access may be denied.

2) Log in via the web without Tor, then activate Tor and log in again WITHOUT clearing cookies. The GAPS cookie on your browser is a large random number that acts as a second factor and will whitelist your access.

Once we see that your account has a track record of being successfully accessed via Tor the security checks are relaxed and you should be able to use TorBirdy.

Operation

When TorBirdy is installed and starts for the first time:

  • it saves (all) the current proxy settings so that they can be restored when TorBirdy is uninstalled/disabled.
  • then it clears the proxy settings.
    • Proxy Type
    • SSL Host, Port.
    • SOCKS Host, Port.
    • HTTP Host, Port.
  • all plugins are disabled. (note: just plugins, not extensions.)
  • for IMAP accounts, the location of the drafts folder is changed from the remote folder to Local Folders
  • account-specific settings for all the accounts are saved so that they can also be restored later.
    • check_new_mail
    • login_at_startup
    • check_time
    • download_on_biff
    • socketType
    • port
    • authMethod
  • the recommended security settings for existing accounts are set.
  • finally, all the recommended TorBirdy settings in TorBirdyPrefs in components/torbirdy.js are set.

The last step is repeated every time Thunderbird starts.

When TorBirdy is uninstalled:

  • all the TorBirdy preferences are cleared and reset to their original values.
  • the proxy settings we saved earlier are restored.
  • all plugins are re-enabled.
  • all remaining TorBirdy preferences (the custom settings) are cleared.

Known TorBirdy Issues

Info Leaks

  • #6314 leak via Date header field (local timestamp disclosure)
  • #6315 leak via Message-ID header field (local timestamp disclosure)

Usenet

This section is only relevant for Usenet / NNTP users.

  • For NNTP accounts that were created before TorBirdy was installed, NNTPS is enabled, but if you create a NNTP account after installing TorBirdy, please enable SSL manually.
  • (See #8069) Connections over SSL to NNTP servers are failing (with or without TorBirdy installed). We are not sure why this is happening. Try it and tell us if it works for you.

Security Requirements

Proxy Obedience

Except GnuPG which requires a HTTP proxy (fail-closed), all other content in Thunderbird obeys the SOCKS proxy.

Disk Avoidance

TorBirdy does not leave any trace of its installation. Caching is also disabled.

Location Neutrality

The time zone is set to UTC.

Anonymity Set Preservation

No information about the user-agent or locale is leaked.

NOTE: It may however be possible to find out that Thunderbird is being used by looking at the format of the message-ID header in the outgoing messages.

Additional Add-Ons

Enigmail (OpenPGP GPG for Thunderbird)

Enigmail is supported and is safe to use with TorBirdy.

However, Enigmail traffic is fail-closed -- TorBirdy ensures that no information is leaked by redirecting HTTP proxy to port 8118 but you will not be able to use Enigmail for communicating with keyservers until we find a HTTP -> SOCKS5 shim. In most setups, GnuPG requires a HTTP proxy to properly work (not leak) on your system running at port 8118. If you are lucky and you are running gpg with curl (>= 7.21.7) support, gpg can be used without http proxy (gpg on Windows has no curl support).

To determine if your gpg installation has that kind of curl support you can run gpg with debug options and look for "curl version". The version number must be >= 7.21.7:

gpg --keyserver-options debug --search-keys somethingnonexisting

Note that if gpg returns gpgkeys: curl version = GnuPG curl-shim, then SOCKS is not supported. If you are running Debian/ Ubuntu, installing the gnupg-curl package will alleviate this issue.

mixminion and mixmaster remailer for Thunderbird

(See #6020, #8125)

Please see the above tickets for a detailed discussion. In any case, do not mix mixgui with TorBirdy unless you have got some good data or good feedback.

Lightning (Calendar for Thunderbird)

(See #6319)

Lightning is safe to use with TorBirdy and has been tested with Google Calendar/iCal.

Other Add-Ons

Please do not install random add-ons. If they have not been reviewed by the TorBirdy developers, they can harm your anonymity. Open a ticket if you want to use a specific add-on with TorBirdy but are unsure about it.

Hacking

Branches

TorBirdy maintains different preference branches to accomodate its settings:

extensions.torbirdy.custom
Holds the custom preferences that are set through the preferences dialog.
extensions.torbirdy.restore
Holds the preferences whose values are saved when TorBirdy is installed and restored when it is uninstalled.

(Don't change any of these preferences yourself!)

Translations

TorBirdy is currently available in the following languages:

Arabic, Czech, Danish, German, English, Spanish, Basque, French, Hebrew, Italian, Japanese, Latvian, Malay, Dutch, Punjabi, Polish, Portuguese (Brazil), Russian, Swedish, Turkish, Chinese (China), Khmer, Farsi (Persian), Norwegian Bokmål, Korean, Ukrainian, French (Canada).

Submitting Translations

We are always looking for assistance with translations. If you would like to use TorBirdy in the language of your choice, just send us the translation and we will gladly include it.

Translations are handled through two files: torbirdy.dtd and torbirdy.properties. The recommended way of submitting translations is through Transifex. You will need to create an account and submit your translations for both torbirdy.dtd and torbirdy.properties. If you do not want to use Transifex, you can send us a pull request on GitHub. Incomplete translations cause problems and therefore only complete (100%) translations will be included.

Acknowledgements

This project is by Jacob Appelbaum, Sukhbir Singh and tagnaq. JonDo support by Karsten N.

source code on github
tickets

Last modified 5 weeks ago Last modified on Mar 16, 2014 5:16:14 AM