Introduction

First of all, we recommend to follow this guide with a friend who also wants to use this technology. Then you can help each other out and immediately test if everything works. Aside from that, there are already enough XMPP users with empty contact lists around :’(

Parts of this guide on are based on articles written by Mathias Renner on how to set-up Conversations and Gajim.

This is a guide for Conversations (Android), ChatSecure(iOS) and Gajim(desktop Win/Lin)

Registering an account

To begin with, you will need a XMPP account! These look like e-mail adresses (username@servername.com) and can be registered with XMPP servers. To get such an account there are a few options:

Host your own XMPP server at home. We’ve written a guide on how to do so, including on how to add user accounts.

If you don’t want to or can’t set up your own XMPP server:

• Find a friend who runs an XMPP server and ask her for a user account!

• Have a look at the list of public XMPP servers. There are some things to look out for however. Make sure they are compliant with all the modern server extensions or you won’t get the user experience you are looking for[ref]It is also possible to test other servers yourself using this compliance tester[/ref]. Also look out for services requiring your phone number to register, it is not needed for XMPP and it would defeat the purpose of taking back the reins of your messaging horse.

• Register an account with https://conversations.im/, the server run by the developer of Conversations. It is well maintained and running the latest features[ref]The first six months are free, afterwards there is a monthly fee that goes to support and sustain the ongoing labour into Conversations and free open-source messaging protocols[/ref].

Considering XMPP clients

Then you need to pick and install a client (also known as an app or a software package). There are many clients avaible that support XMPP chats, both for mobile, desktop and web-based environments. The nice thing about using XMPP is that your account and your client are not intertwined, as is the case with Whatsapp, Telegram, Signal and the others. These applications offer a full chat service, which includes the facilitation and hosting of your messages over the network, and the interface options of your client. By separating the two, you have the option to choose. To pick from all the available clients we made a list of criteria of what we considered essential requirements and started crossing off all those applications that didn’t meet them:

• free & open source software —  the technology is open, and therefore it’s possible to install use the software on your own terms.

• works with federated servers —  servers are not all controlled by a single company or organization, but can also be run by volunteers, organizations, companies, you and me.

• highly secure (which means support for encryption) —  the software takes security to heart and offers things like end-to-end OMEMO encryption.

• the project is recently updated —  There are many XMPP clients available, but not all of them are still maintained. For example: many iOS clients have not been updated for a long time.

• support for easy image sharing — Essential in order to be able to share dank memes and food pictures.

• relative ease of use - Need we explain more?

This (apparently) rather rigorous list of requirements left us with three applications that we will discuss in this guide: Conversations for Android, ChatSecure for iOS and Gajim for the desktop computer. There are many other XMPP clients however, and while most of these did not meet our requirements for use, they might be ok for you. Have a look at this extensive list of XMPP clients in general and this list of clients that (plan to) support OMEMO. Additionally you might want to make sure your client supports some of the ‘modern’ XMPP Extensions[ref]XEP-0163: Personal Eventing Protocol (for avatars and OMEMO), XEP-0198: Stream Management(for better experience using flaky mobile connections), XEP-0280: Message Carbons(sync messages between your different clients), XEP-0313: Message Archive Management(receive messages while offline), XEP-0363: HTTP File Upload(send images, share files in groupchats and with offline contacts.)[/ref].

 _______
< OMEMO >
 -------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

Conversations, Android

Download the Conversations app on your Smartphone.

Conversations is available via Google Play for €2,39. The sale of the app goes towards the ongoing development of te software.

In case you don’t use Google apps or want it for free, you need to install the alternative ‘app store’ f-droid before. F-droid works like the app store Google Play, except that it isn’t a store and only offers apps that are free and open source software. See instructions in the next paragraph how to install f-droid.

If you decided for f-droid, open the website (https://f-droid.org/) with your phone’s browser. Press the big download button on the website, which will download f-droid’s installer. After download, press the downloaded file and the installer should start. Next, start f-droid, update the repositories and search for the app Conversations.

Start the messenger app and register/log in

Now, start Conversations. If you already have an XMPP account, you can log in with your so-called JID (jabber id, username@server.com) and password. Otherwise, if your server of choice has the option for application-based registration enabled, it is also possible to register a new account in this menu, by selecting the “register new account on server” option.

After you clicked Next, the registration process might take up to 20 seconds.

Start chatting.

To start a chat you need to add another Jabber friend under the ‘+’ in the menu and insert your friend’s Jabber ID, e.g. your-friend@a-jabber-server.com. That’s it. You can now chat with your friend. However, this will be unencrypted!

Encryption

So let’s activate OMEMO encryption by pressing the padlock in the top menu bar:

OMEMO is an extension to XMPP for multi-client end-to-end encryption. OMEMO only works if the fingerprint of your and your friend’s device match. To compare them, open one of your conversations and click on your profile picture next to one of your messages. At the same time, your friend clicks on your icon on his phone.

Now, both of you should see a fingerprint that you can check. If they match, change the slider as you see in the screenshot to the right.

If OMEMO cannot be activated, just send a message in the chat window. This sometimes helps. Also, it may help to end a conversation by pressing the menu on the top right inside a conversation, and then re-open the conversation again.

After you activated OMEMO, the input field at the bottom should say you can now send encrypted messages:

Troubleshooting Conversations

If OMEMO cannot be activated, just send a message in the chat window. This sometimes helps. Also, it may help to end a conversation by pressing the menu on the top right inside a conversation as shown in the following screenshot, and then re-open the conversation again.

Allow presence updates, this is used by OMEMO to exchange keys: In a conversation, click on the icon/image of your chat partner. In the new screen (as shown below), make sure that all checkboxes are activated:

Check fingerprints: You might be asked to trust fingerprints like this:

If you run into problems try asking for help in the Conversations XMPP groupchat: conversations@conference.siacs.eu

ChatSecure, iOS

Download the ChatSecure app.

Get ChatSecure from the AppStore. ¯\_(ツ)_/¯

Start the messenger app and register / log in.

Choose whether to create a new account or login with an existing one:

> >

If you already have an XMPP account, you can log in with your username@hostname and password. After you selected “Add Existing Account” you have the option to connect with “XMPP” or with “Google Talk”. Select “XMPP” and fill in your Nickname, Username (username@server.net) and password. Optionally fill in the Hostname of your XMPP server and select if you want to use Tor or not. If you’re doubting about the port, 5222 is the default XMPP port and would likely be on your server as well.

Enabling Push

After you’ve logged in, the app proposes to establishe secure connections by sending an empty message to offline contacts. You have the option to “Enable push” or “skip” this part. iOS typically end the connection when an app runs in the background and requires use of Apple’s Push servers to wake up and receive a message. By sending empty messages ChatSecure limits the data being sent to the Apple Cloud’s Push Server but obviously still provide their vertically integrated cloud platform with meta-data. Read more about the Push issues here and here

In the next screen you can “Share invite” (let people on social media know about the app) or tap the ‘✓’ symbol in the top right corner to continue. This takes you to the general ‘Settings’ menu.

> >

If you are successfully connected, the word “Connected” appears right under your username. Before you can edit your account settings, you need to log out. To do this, click your account/nickname in the settings menu and select “Log Out”.

Create New Account

> >

Choose “Create New Account” and give your preferred nickname. Under “show advanced options” you can customize your username, generate an automatic password, enable TOR (we didn’t test it) and select a server where you would like to register your account on. This is the server you will use to communicate with other people’s selected servers, and depending on the server settings it will also store your (encrypted) messages. ChatSecure let’s you choose between 3 built-in servers options. Default is DuckDuckGo, but when you tap on “DuckDuckGo” the app will take you to the server selection screen where you can choose between DuckDuckGo, Calyxinstitute.org and OTR.im[ref]All three of these servers score poorly on the modern XMPP compliance test[/ref], it also offers you the option to select another, custom, server. Here you can fill in the hostname of the XMPP server of a friend.

Adding contacts

> >

From the settings menu, tap ‘Chats’ (top left) to start chatting and adding friends. To add friends tap the ‘Compose’ icon, top left corner. Then tap “Add Buddy” and fill in your friends username and hostname (username@hostname) or scan their QR code.

Click the “+” icon when you are ready. Your friend will now appear in the “Chats” list and will be available for conversation after being approved by the other side (“pending approval”). After this, tap your friends name to start chatting

If you get a friend request, their nickname will appear in the “Chats” list.

Encryption

When in a chat, tap the information icon on the top right (i) to change your encryption settings. The information menu displays your current and past verified fingerprints and allows you to specify an encryption method by tapping “Show Advanced Encryption Sett…”.

> >

At the time of writing OMEMO works well with other OMEMO clients, images shared over HTTPUpload however are not displayed inline but rather as a URL. If you click that your browser will open it and fail to decrypt the OMEMO encoded image, because it has no notion of your OMEMO fingerprints. So for now the images shared over HTTPUpload have to be shared using plaintext.

ChatSecure implements OMEMO and OTR on a TOFU or “trust on first use” basis. New “buddies” are automatically trusted.

>

You can also untrust your friends devices/fingerprints by sliding the green “Verified” button and share fingerprints by tapping them and selecting a medium to share your fingerprint over.

If OMEMO cannot be activated, just send a message in the chat window. This sometimes helps. Also, it may help to relaunch the app…If you’re chatting with someone using something else than ChatSecure, for example Conversations on Android it helps when the Android side allows for receiving and sending presence updates. For specifics refer to the Conversations section of this guide.

Gajim, Desktop Windows / Linux

These instructions are for Debian / Linux. For windows it is possible to download the binaries here.

Getting the latest version of Gajim

The version that is packaged in the repositories of Debian does not support OMEMO unfortunately. As a way around, you can download and install the latest version of Gajim from the Debian backports repositories.

In case you don’t have backports on your sources.list, follow these instructions before you start:

For wheezy add this line to your sources.list (or add a new file with the “.list” extension to /etc/apt/sources.list.d/) You can also find a list of other mirrors at https://www.debian.org/mirror/list:

deb http://ftp.debian.org/debian wheezy-backports main

For jessie add this line to your sources.list:

deb http://ftp.debian.org/debian jessie-backports main

Afterwards :::console sudo apt-get update

Now we are ready to go!

Installing Gajim & other dependencies from backports

To install gajim:

apt-get -t jessie-backports install gajim

Now you’ll also need to install Python-axolotl, which will allow you to setup a security layer on top of XMPP. Run:

apt-get install python-axolotl

Next, you have to downgrade protobuf due to a bug in python-axolotl:

sudo pip2 install protobuf==2.6.1

And now for OMEMO! There is a package gajim-omemo on Debian Backports. So run:

apt-get -t jessie-backports install gajim-omemo

Starting Gajim and installing plugins

Next, start Gajim. After Gajim has started, wait some seconds until it requests your permission to install updates:

Allow this. Afterwards, a new window will open that lists all components that can be installed and updated. In this list, activate the checkbox next to the following plugins:

OMEMO

HttpUpload

Image

Url image preview

These plugins allow for encryption (OMEMO) and the easy sharing and display of images across different clients (HttpUpload, Image, Url Image preview)

Then, click the button Install/Upgrade on the bottom left on that window.

After the update has finished, go to the other tab Installed. There, make sure that all components are activated via the checkbox. Afterwards, click close on the bottom right of the window.

Then, you should see a wizard to setup your XMPP account. Select the option that you already have an account and follow all instructions yourself using the default settings.

After you finished the wizard successfully, Gajim will show your status as Available. Congratulations! Now, let’s send messages to your friends.

To do so, click on the Gajim window and move your mouse to the top of the screen. There, a menu should appear. Go to Actions -> Start chat… . In the new window, add the XMPP ID of your friend and click ok.

Go to the main menu again and select View -> Show offline contacts… . In the Gajim window, you should see your friend. Right click on the name of your friend and select Manage contact -> Add to roster. In the pop up, just click Add. Now your friend is permanently added to your list of contacts. Next, right click on your friend and select Manage contact -> Allow subscription -> Allow contact to see my status.

Your friend should see a request like this:

Your friend should click Authorize, which enables her to see if you are online or not. Also, this step is necessary for activating the encryption.

Next, make sure that your friend also allows you to see her status.

Now, when you open the chat window to your friend, it should say OMEMO encryption enabled and show a red shield next to the input field, like this:

If you don’t see the OMEMO encryption enabled — just restart Gajim and have a look again.

You might at some point be confronted with a window about trusting fingerprints.

Fingerprints

Simply put, a fingerprint is an ID of a device someone uses for the messaging. In order to make sure that you communicate with exact the devices, which your friend uses, you need to see if the fingerprints listed in this window match with the ones your friend really has.

So, ask your friend to list her fingerprints on her desktop. On her computer, in the chat window with you, she should click on the setting symbol below the text input field (grey, with wheels). From there to OMEMO encryption -> Fingerprints. She should now see the same window as you.

She should chose the tab Own devices, while you chose the tab Contact. Now, select a fingerprint that matches with the one of your friend and press the button Trust/Revoke Fingerprint. Also press yes in the window that appears.

Finally, all fingerprints should be green like this:

Troubleshooting

Sometimes, a restart of Gajim just helps :)

If OMEMO encryption or the fingerprint option is grey and cannot be activated, just send a message in the chat window. This sometimes helps.

If you wish to know more about Gajim check out the documentation. For more advanced issues check out Gajim’s XMPP chatroom