Profanity Illustration

User Guide

OMEMO Encryption

Contents

Current state

Profanity has OMEMO support since 0.7.0. Regular 1:1 chats should work without problems. We consider OMEMO MUC as experimental. You might encounter problems there. Make sure to check our tracker bug for details. And report anything you find on the issue tracker.

Enabling carbons (/carbons on) is recommended in order to enhance OMEMO and overall chat experience.

To be able to read on other devices (eg your phone) what you wrote on profanity you need to trust the fingerprints of your other devices manually (/omemo fingerprint ).

Filetransfer is not OMEMO encrypted since this is not part of the original XEP-0384 but only a proto XEP.

/omemo fingerprint does autocomplete all fingerprints not just the ones for the JID mentioned.

Building with OMEMO support

OMEMO is an XMPP Extension Protocol (XEP) for secure multi-client end-to-end encryption. It is an open standard based on a Double Ratchet and PEP.

Profanity supports OMEMO only if you build from current git master. Support is planned for the 0.7.0 release.

If you have libsignal-protocol-c installed, support will be included by default. To force the build to fail if support cannot be included, configure with the following:

./configure --enable-omemo

Supported libsignal-protocol-c versions are 2.3.1, and 2.3.2.

Setup

Generating Crypto Materials

Before you can start using OMEMO for a particular account, you must generate the cryptographic material. Use the following command:

/omemo gen

A message will appear informing you that the key is being generated which may take a few minutes. We use /dev/random for this.

If the generation takes a long time you can try to move the mouse or install an entropy daemon, such as haveged, to increase the available entropy.



Once you have generated a key, you will not need to do so again. If you want to check your own fingerprint or see the fingerprints of your other devices type:

/omemo fingerprint

Hint: To be able to receive messages from your other devices you need to enable carbons. Also trust your own devices analogous to your buddies fingerprints, as described in the next paragraph.

/carbons on

Fingerprint authentication

Before you can start talking with a contact you need to authenticate him by trusting his fingerprint(s).

You should exchange fingerprints with your contact's via another secure communication channel. To display your fingerprint, use the following command:

/omemo fingerprint


To view the fingerprint of a contact use the following command:

/omemo fingerprint bob


If the fingerprint you see matches the fingerprint you communicated via another means, you can manually authenticate the contact with the following command:

/omemo trust 7ef54f6a-af23d766-efc9a4ea-da6fca40-3e8a5c82-9c46e4a4-e4c7230f-937b9144

You can untrust a contact at anytime using the following command:

/omemo untrust 7ef54f6a-af23d766-efc9a4ea-da6fca40-3e8a5c82-9c46e4a4-e4c7230f-937b9144

Starting a private conversation

Once the cryptographic material is present and you trusted your contacts fingerprint(s) you can start a private conversation with another contact that uses an OMEMO capable client

To start a new conversation using OMEMO:

/omemo start bob@ejabberd.local

If you are already in a conversation window without OMEMO, you can start sending encrypted messages with the same command omitting the contact:

/omemo start bob


The [OMEMO] shown in the titlebar indicates that the conversation is now encrypted.

Setting OMEMO policy

By default, OMEMO sessions must be started manually using the /omemo start command.

The following three settings are available:

manual - The default. Unencrypted messaging is allowed, OMEMO sessions must be started manually.

automatic - If you start an OMEMO session with a contact once via /omemo start it will remember the OMEMO session for this contact. So if you restart Profanity and use /msg bob@ejabberd.local it will OMEMO encrypt the conversation. You can stop this with /omemo stop.

always - OMEMO sessions are always started. Until you use /omemo stop.

User Interface options

By default, an indicator is displayed in the titlebar when no encryption is being used.



This indicator can be removed using the /encwarn command.

/encwarn off


Both incoming and outgoing plaintext messages are always preceeded by the '-' character.



By default OMEMO encrypted messages are preceeded by the '*' character.



This character can be changed using the /omemo char command.

/omemo char O


OMEMO message logging

The /omemo log command may be used with the following options to control if and how OMEMO messages are recorded in chat logs.

on
OMEMO messages will be logged in plaintext
redact
OMEMO messages will be logged, but the message will be replaced with the text '[redacted]'.
off
OMEMO messages will not be logged.

For the on and redact settings, chat logging must also be enabled with the /chlog command.