# 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).