Initial commit

src/content/docs/guides/Encryption/omemo.md

@@ -0,0 +1,150 @@
+---
+title: OMEMO Encryption
+description: How to setup OMEMO encryption in CProof
+sidebar:
+  order: 2
+  label: OMEMO
+---
+
+## Setup
+
+### Generating Crypto Materials
+
+Before you can start using OMEMO for a particular account, you must generate the cryptographic material. Use the following command:
+
+```bash
+/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.
+
+![CProof key generated](@assets/key_generated-2.png)
+
+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:
+
+```bash
+/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.
+
+```bash
+/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:
+
+```bash
+/omemo fingerprint
+```
+
+![CProof key generated](@assets/myfp-2.png)
+
+To view the fingerprint of a contact use the following command:
+
+```bash
+/omemo fingerprint bob
+```
+
+![CProof key generated](@assets/theirfp-2.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
+/omemo trust 7ef54f6a-af23d766-efc9a4ea-da6fca40-3e8a5c82-9c46e4a4-e4c7230f-937b9144
+```
+
+You can untrust a contact at anytime using the following command:
+
+```bash
+/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:
+
+```bash
+/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:
+
+```bash
+/omemo start bob
+```
+
+![CProof started](@assets/started-2.png)
+
+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 CProof 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.
+
+![CProof encwarn](@assets/encwarn-3.png)
+
+This indicator can be removed using the [/encwarn](/command-reference#encwarn) command.
+
+```bash
+/encwarn off
+```
+
+![CProof encwarn](@assets/encwarnoff-3.png)
+
+Both incoming and outgoing plaintext messages are always preceeded by the '-' character.
+
+![CProof encwarn](@assets/plainchar-3.png)
+
+By default OMEMO encrypted messages are preceeded by the '\*' character.
+
+![CProof encwarn](@assets/omemochar.png)
+
+This character can be changed using the _/omemo char_ command.
+
+```bash
+/omemo char O
+```
+
+![CProof newchar](@assets/newchar-3.png)
+
+## 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-reference#chlog) command.
+
+## Current State
+
+CProof has OMEMO support. Regular 1:1 chats should work without problems. We consider OMEMO MUC as experimental. You might encounter problems there. Make sure to check this <a href="https://github.com/profanity-im/profanity/issues/1070" target="_blank" rel="noopener noreferrer">tracker bug</a> 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 CProof you need to trust the fingerprints of your other devices manually (`/omemo fingerprint`).
+
+Filetransfer is OMEMO encrypted via the <a href="https://xmpp.org/extensions/inbox/omemo-media-sharing.html" target="_blank" rel="noopener noreferrer">OMEMO Media sharing XEP</a>.
+
+`/omemo fingerprint` does autocomplete **all** fingerprints not just the ones for the JID mentioned.