Tor Messenger Design Document (Beta)

Tor Messenger is an instant messaging client that is designed to make connections over the Tor anonymity network. Based on the Instantbird IM client, Tor Messenger:

  • sends all traffic over Tor,
  • uses Off-the-Record (OTR) encryption of conversations by default,
  • can be used with a wide variety of chat networks (including IRC, Jabber/XMPP, Google Talk, Twitter),
  • has an easy-to-use graphical user interface localized in multiple languages.


Logging of all conversations is disabled by setting purple.logging.log_chats,purple.logging.log_ims, purple.logging.log_system to false.


Tor Messenger sends all traffic over Tor. We set the following preferences: network.proxy.socks_remote_dns (true), network.dns.disablePrefetch (true), network.proxy.socks_version (SOCKS5), network.proxy.socks_port (9152).

Messaging Window

Hyperlinks are removed and converted to plain text. (Future work: we should ask the users for the desired action when they click a link.) Caching is disabled.


We disable SSL and set the minimum supported protocol to TLS. (security.tls.version.min is set to 1). Strict certificate pinning is enforced.


Access to the webcam (for setting account profile pictures) is disabled from source.


Tor Messenger does not automatically connect accounts to prevent automatic login. Reporting of idle status or away messages is also disabled to help users preserve their privacy.

Tor Messenger sets the user-agent to Instantbird stable on Windows for all platforms: "Mozilla/5.0 (Windows NT 6.1; rv:25.0) Gecko/20100101 Instantbird/1.5".


Starting with version 0.2.0b2, Tor Messenger will automatically update on all platforms, similar to Tor Browser. When a new update is available, users will get a notification to install the update.


The recommended IRC server is OFTC (there is no default server). OFTC blocks Tor occasionally so if you can't connect to OFTC over Tor/Tor Messenger, there isn't much you can do except wait for the ban to go away.

CTCP PING is disabled from source. CTCP TIME returns the time in UTC

XMPP (Jabber)

To enable users to connect to the popular Jabber servers (like without the scary certificate warnings, we bundle a custom cert_override.txt for them. The servers and their fingerprints can be found in projects/instantbird/cert_override.txt.


We perform automated builds of Tor Messenger for Linux, Windows and OS X using Nicolas Vigier's rbm (Reproducible Builds Manager). Linux (32- and 64-bit) builds are reproducible, and Windows and OS X builds will be reproducible in the future. The current builds are signed with the 0xB01C8B006DA77FAA key.


Tor Messenger does not allow plugins to be loaded in the process space. We borrow the patch for this from Tor Browser, but additionally, we also block Flash.


Instantbird includes libpurple to support a wider range of transport protocols. This is opt-in behaviour in the build system which we omit. All transport protocols included in Tor Messenger are written in a memory safe language, namely JavaScript. The bundled protocols include:

  • Google Talk
  • IRC
  • Odnoklassniki
  • Twitter
  • XMPP (Jabber)


However, we compile and ship libotr in Tor Messenger, and use js-ctypes bindings to interface with it. This is so that cryptographic operations are known to be done in constant time and we have a reliable implementation of the protocol.

For the moment, we're building libotr linking to libgcrypt. However, when the extension gets upstreamed, in order to avoid having two cryptography libraries to maintain, we're going to shim the necessary symbols with libnss.

Although libotr supports v3 of the protocol (which adds instance tags for multiple simultaneous sessions with the same contact), we are only offering v2 until the UI for it is properly implemented.

Last modified 3 years ago Last modified on Nov 9, 2016, 5:21:31 PM