OTR

This plugin implements Off The Record messaging.

This is a plugin used to encrypt a one-to-one conversation using the OTR encryption method. You can use it if you want good privacy, deniability, authentication, and strong secrecy. Without this encryption, your messages are encrypted at least from your client (poezio) to your server. The message is decrypted by your server and you cannot control the encryption method of your messages from your server to your contact’s server (unless you are your own server’s administrator), nor from your contact’s server to your contact’s client.

This plugin does end-to-end encryption. This means that only your contact can decrypt your messages, and it is fully encrypted during all its travel through the internet.

Note that if you are having an encrypted conversation with a contact, you can not send XHTML-IM messages to them (or correct messages, or anything more than raw text). All formatting will be removed and be replaced by plain text messages.

This is a limitation of the OTR protocol, and it will never be fixed. Some clients like Pidgin-OTR try do do magic stuff with html unescaping inside the OTR body, and it is not pretty.

Installation

To use the OTR plugin, you must first install pure-python-otr and pycrypto (for python3).

You have to install it from the git because a few issues were found with the python3 compatibility while writing this plugin, and the fixes did not make it into a stable release yet.

Install the python module:

git clone https://github.com/afflux/pure-python-otr.git
cd pure-python-otr
python3 setup.py install --user

You can also use pip in a virtualenv (built-in as pyvenv with python since 3.3) with the requirements.txt at the root of the poezio directory.

Usage

Command added to Conversation Tabs and Private Tabs:

/otr

Usage: /otr [start|refresh|end|fpr|ourfpr|trust|untrust]

This command is used to manage an OTR private session.

  • The start (or refresh) command starts or refreshs a private OTR session

  • The end command ends a private OTR session

  • The fpr command gives you the fingerprint of the key of the remote entity

  • The ourfpr command gives you the fingerprint of your own key

  • The trust command marks the current remote key as trusted for the current remote JID

  • The untrust command removes that trust

  • Finally, the drop command is used if you want to delete your private key (not recoverable).

Warning

With drop, the private key is only removed from the filesystem, NOT with multiple rewrites in a secure manner, you should do that yourself if you want to be sure.

/otrsmp

Usage: /otrsmp <ask|answer|abort> [question] [secret]

Verify the identify of your contact by using a pre-defined secret.

  • The abort command aborts an ongoing verification

  • The ask command start a verification, with a question or not

  • The answer command sends back the answer and finishes the verification

Managing trust

An OTR conversation can be started with a simple /otr start and the conversation will be encrypted. However it is very often useful to check that your are talking to the right person.

To this end, two actions are available, and a message explaining both will be prompted each time an untrusted conversation is started:

  • Checking the knowledge of a shared secret through the use of /otrsmp

  • Exchanging fingerprints (/otr fpr and /otr ourfpr) out of band (in a secure channel) to check that both match, then use /otr trust to add then to the list of trusted fingerprints for this JID.

Files

This plugin creates trust files complatible with libotr and the files produced by gajim.

The files are located in $XDG_DATA_HOME/poezio/otr/ by default (so ~/.local/share/poezio/otr in most cases).

Two files are created:

  • An account_jid.key3 (example@example.com.key3) file, which contains the private key

  • An account_jid.fpr (example@example.com.fpr) file, which contains the list of trusted (or untrusted) JIDs and keys.

Configuration

decode_entities

Default: true

Decode XML and HTML entities (like &amp;) even when the document isn't valid (if it is valid, it will be decoded even without this option).

decode_newlines

Default: true

Decode <br/> and <br> tags even when the document isn't valid (if it is valid, it will be decoded even without this option for <br/>, and <br> will make the document invalid anyway).

decode_xhtml

Default: true

Decode embedded XHTML.

keys_dir

Default: $XDG_DATA_HOME/poezio/otr

The directory in which you want keys and fpr to be stored.

log

Default: false

Log conversations (OTR start/end marker, and messages).

require_encryption

Default: false

If true, prevents you from sending unencrypted messages, and tries to establish OTR sessions when receiving unencrypted messages.

timeout

Default: 3

The number of seconds poezio will wait until notifying you that the OTR session was not established. A negative or null value will disable this notification.

The require_encryption, decode_xhtml, decode_entities and log configuration parameters are tab-specific.

Important details

The OTR session is considered for a full JID (e.g. toto@example/client1), but the trust is set with a bare JID (e.g. toto@example). This is important in the case of Private Chats (in a chatroom), since you cannot always get the real JID of your contact (or check if the same nick is used by different people).