---
title: OTR Message Encryption
description: How to setup OTR encryption in CProof
sidebar:
  order: 4
  label: OTR
---

## Generating a private key

Before you can start using OTR for a particular account, you must generate a private key. Use the following command:

```bash
/otr gen
```

A message will appear informing you that the key is being generated which may take a few minutes.

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.

![CProof OTR](@assets/key_generated.png)

Once you have generated a key, you will not need to do so again.

## Starting a private conversation

Once you have a private key, you may start OTR encrypted sessions with other contacts who have OTR enabled.

To start a new conversation using OTR encryption:

```bash
/otr start bob@ejabberd.local
```

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

```bash
/otr start
```

![CProof OTR Started](@assets/started.png)

The [*untrusted*] shown in the titlebar indicates that although this conversation is encrypted, the contact has not yet been authenticated.

## Authenticating a contact

The previous conversations were encrypted, however as the recipient noticed, neither user can be certain of the identity of the other.

Authentication is for each OTR key that the contact may have generated. For example if your contact has different OTR keys on different devices, you will need to authenticate each device separately.

Once a particular contact (and client) has been authenticated, this information is saved.

OTR supports three ways to authenticate a contact, question and answer, shared secret, and manual fingerprint verification.

### Question and answer

Question and answer verification allows one user to verify the identity of another by asking a question with an expected answer.

Once in an OTR session, a user may ask the recipient a question supplying their expect answer, for example if Alice wishes to authenticate Bob:

```bash
/otr question "What is the name of your best friends rabbit?" fiffi
```

A message will be displayed showing that the authentication process has started.

![CProof Question Send](@assets/question_sent.png)

If Bob answers correctly a message will be shown indicating that Bob is now trusted by Alice.

![CProof Question Received Success](@assets/question_received_success.png)

If Bob answers incorrectly a message will be shown indicating that Bob is not trusted by Alice.

![CProof Question Received Fail](@assets/question_received_fail.png)

Bob may also wish to authenticate Alice. If he does, Alice will receive a message showing Bob's question, and prompting her to answer. Alice may answer using the _/otr answer_ command:

```bash
/otr answer red
```

![CProof Question](@assets/bobquestion.png)

Note that question and answer authentication is a way for one contact to verify the identity of another. If the recipient answers correctly then the sender has authenticated them, however the recipient must also authenticate the sender with another question.

### Shared secret

Shared secret verification is a way for both parties to authenticate each other at the same time using a shared passphrase that only the two of them know.

In an OTR session, one user may start shared secret authentication with the /otr secret command, supplying the secret, for example Alice initiates the authentication:

```bash
/otr secret 5up3r53cr3t
```

Bob enters the same secret using his client, Alice and Bob now trust each other.

![CProof Secret Received Success](@assets/secret_received_success.png)

If Bob started the shared secret authentication, Alice will receive a message asking her to enter the secret using the /otr secret command:

```bash
/otr secret 5up3r53cr3t
```

![CProof Secret Sent Success](@assets/secret_sent_success.png)

### Manual fingerprint authentication

The above two methods allow you to verify the fingerprint of a contact's OTR key without having to know the fingerprint. The final method is to manually verify the fingerprint.

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

```bash
/otr myfp
```

![CProof FP](@assets/myfp.png)

To view the fingerprint of a contact whilst in an OTR session, use the following command:

```bash
/otr theirfp
```

![CProof FP](@assets/theirfp.png)

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

```bash
/otr trust
```

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

```bash
/otr untrust
```

## Setting OTR policy

By default, OTR sessions must be started manually using the _/otr start_ command.

The policy may be set at three levels, global, per account, and per contact with the order of preference being the most specific first:

1 - Use the policy for the contact, if no setting found:
2 - Use the policy for the account, if no setting found:
3 - Use the global policy

The following three settings are available for each level:

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

**opportunistic** - Upon sending an unencrypted message with the _/msg_ command, CProof will attempt to start an OTR session with the contact. The contact's policy must be set to _opportunistic_ or _always_ for the session to start.

**always** - An error message will be displayed if you try to start a conversation without starting an OTR session and the message will not be sent.

### Setting global policy

To set the global policy:

```bash
/otr policy <setting>
```

The current global setting can be viewed with the following command:

```bash
/prefs otr
```

### Setting account policy

To set the policy for a particular account:

```bash
/account set <account_name> otr <setting>
```

The account setting can be viewed with the following command:

```bash
/account show <account_name>
```

### Setting contact policy

To set the policy for a particular contact (you must be logged in):

```bash
/otr policy <setting> <contact>
```

Contact policy settings can also be viewed with:

```bash
/account show <account_name>
```

## User Interface options

By default, an indicator is displayed in the titlebar when no encryption is being used (including <a href="./guide/latest/pgp.html" target="_blank" rel="noopener noreferrer">PGP</a> and <a href="./guide/latest/omemo.html" target="_blank" rel="noopener noreferrer">OMEMO</a>).

![CProof encwarn](@assets/encwarn.png)

This indicator can be removed using the [`/encwarn`](/command-reference#encwarn) command.

```bash
/encwarn off
```

![CProof encwarn](@assets/encwarnoff.png)

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

![CProof encwarn](@assets/plainchar.png)

By default OTR encrypted messages are preceeded by the '~' character.

![CProof encwarn](@assets/otrchar.png)

This character can be changed using the _/otr char_ command.

```bash
/otr char O
```

![CProof encwarn](@assets/newchar.png)

## OTR message logging

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

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

For the _on_ and _redact_ settings, chat logging must also be enabled with the [`/chlog`](/command-reference#chlog) command.

## Importing OTR keys

Since CProof uses the libotr library to store keys and trusted fingerprints, files created by another client which uses libotr should also work with CProof.

The files need to be placed in the following locations:

```plaintext
$XDG_DATA_HOME/profanity/otr//keys.txt
$XDG_DATA_HOME/profanity/otr//fingerprints.txt
```

On most systems _$XDG_DATA_HOME_ is _~/.local/share_. The folder is the account name with \_at\_ replacing the @ symbol, for example account `my.account@server.org` will have the above two files stored as:

```plaintext
~/.local/share/profanity/otr/my.account_at_server.org/keys.txt
~/.local/share/profanity/otr/my.account_at_server.org/fingerprints.txt
```
