README.md 7.83 KB
Newer Older
Richard Bayerle's avatar
Richard Bayerle committed
1
# lurch 0.6.7-dev
Richard Bayerle's avatar
Richard Bayerle committed
2
/lʊʁç/. In German, an Axolotl is a type of Lurch, which simply means 'amphibian'. This plugin brings _Axolotl_, by now renamed to _double ratchet_, to _libpurple_ applications such as [Pidgin](https://www.pidgin.im/) by implementing the [OMEMO](https://conversations.im/omemo/) _XMPP Extension Protocol (XEP)_.
gkdr's avatar
gkdr committed
3

Richard Bayerle's avatar
Richard Bayerle committed
4
(Plus I thought the word sounds funny.)
gkdr's avatar
gkdr committed
5

Richard Bayerle's avatar
Richard Bayerle committed
6
## News
Richard Bayerle's avatar
Richard Bayerle committed
7
8
9
10
11
12
Version 0.2 of the _OMEMO XEP_ adopted the namespace actually implemented by all the clients, so there is no need for a 'compatible' version of the plugin any longer. This mostly concerns Windows users who used the `lurch_compat.dll`, so don't be confused if it's not there.

If you use a version <0.6.5, you should still definitely update.

## Table of Contents
1. [Installation](#installation)
Richard Bayerle's avatar
Richard Bayerle committed
13
14
15
16
   1. [Linux](#linux)
   1. [Windows](#windows)
   1. [MacOS](#macos)
   1. [Additional plugins](#additional-plugins)
Richard Bayerle's avatar
Richard Bayerle committed
17
2. [Usage](#usage)
Richard Bayerle's avatar
Richard Bayerle committed
18
19
   1. [General](#general)
   1. [Group Chats](#group-chats)
Richard Bayerle's avatar
Richard Bayerle committed
20
21
22
23
3. [Bug Reports](#bug-reports)
4. [FAQ](#faq)
5. [Caveats](#caveats)

gkdr's avatar
gkdr committed
24
## Installation
Richard Bayerle's avatar
Richard Bayerle committed
25
### Linux
Richard Bayerle's avatar
Richard Bayerle committed
26
##### 1. Install the (submodules') dependencies
Richard Bayerle's avatar
Richard Bayerle committed
27
Below you can find the command to install the dependencies for popular distribution families. Make sure that you use at least version 2.7 of _mxml_, and 2.10.10 of _libpurple_.
28

Richard Bayerle's avatar
Richard Bayerle committed
29
__Debian, Ubuntu__
30
``` bash
Richard Bayerle's avatar
Richard Bayerle committed
31
sudo apt install git cmake libpurple-dev, libmxml-dev, libxml2-dev, libsqlite3-dev, libgcrypt20-dev
32
```
Richard Bayerle's avatar
Richard Bayerle committed
33
__ArchLinux, Parabola__
34
``` bash
Richard Bayerle's avatar
Richard Bayerle committed
35
sudo pacman -S base-devel git cmake pidgin libpurple mxml libxml2 sqlite libgcrypt
36
```
Richard Bayerle's avatar
Richard Bayerle committed
37
__Fedora__
38
``` bash
Richard Bayerle's avatar
Richard Bayerle committed
39
sudo dnf install git cmake libpurple-devel mxml-devel libxml2-devel libsqlite3x-devel libgcrypt-devel
40
```
41

Richard Bayerle's avatar
Richard Bayerle committed
42
##### 2A. EITHER: Build and install from source
43
44
45
``` bash
git clone https://github.com/gkdr/lurch/
cd lurch
Richard Bayerle's avatar
Richard Bayerle committed
46
git submodule update --init --recursive
Richard Bayerle's avatar
Richard Bayerle committed
47
make install-home
48
```
49
If you just pull a newer version (`git pull`), remember to also update the submodules as they might have changed!
50

Richard Bayerle's avatar
Richard Bayerle committed
51
The last command compiles the whole thing and copies the plugin into your local _libpurple_ plugin directory.
52

Richard Bayerle's avatar
Richard Bayerle committed
53
The next time you start Pidgin, or another libpurple client, you should be able to activate it in the "Plugins" window.
54

Richard Bayerle's avatar
Richard Bayerle committed
55
##### 2B. OR: Install from a community repo
Richard Bayerle's avatar
Richard Bayerle committed
56
57
* Arch - AUR: https://aur.archlinux.org/packages/libpurple-lurch-git/
* Fedora - COPR:  https://copr.fedorainfracloud.org/coprs/treba/pidgin-lurch/
58

gkdr's avatar
gkdr committed
59

Richard Bayerle's avatar
Richard Bayerle committed
60
61
### Windows
Thanks to [EionRobb](https://github.com/EionRobb), Windows users can use the dlls he compiled and provides here: https://eion.robbmob.com/lurch/
Olivier Mehani's avatar
Olivier Mehani committed
62

Richard Bayerle's avatar
Richard Bayerle committed
63
64
1. Download the plugin (_lurch.dll_) and put it in the `Program Files (x86)\Pidgin\plugins` directory.
2. Download _libgcrypt-20.dll_ and _libgpg-error-0.dll_ and put them in the `Program Files (x86)\Pidgin` directory.
Olivier Mehani's avatar
Olivier Mehani committed
65

Richard Bayerle's avatar
Richard Bayerle committed
66
These instructions can also be found at the provided link.
Olivier Mehani's avatar
Olivier Mehani committed
67

Richard Bayerle's avatar
Richard Bayerle committed
68
69
### MacOS
Homebrew should have all dependencies:
Olivier Mehani's avatar
Olivier Mehani committed
70
71

```
Richard Bayerle's avatar
Richard Bayerle committed
72
brew install cmake pidgin glib libxml2 libmxml sqlite libgcrypt 
Olivier Mehani's avatar
Olivier Mehani committed
73
```
Richard Bayerle's avatar
Richard Bayerle committed
74
This should work on newer versions of MacOS, but if you run into problems check out [#8](https://github.com/gkdr/lurch/issues/8#issuecomment-285937828) for some hints. Complete instructions on how to get this running with Pidgin appreciated!
Olivier Mehani's avatar
Olivier Mehani committed
75

Richard Bayerle's avatar
Richard Bayerle committed
76
Alternatively, if you use Adium, you should definitely check out [shtrom](https://github.com/shtrom)'s [Lurch4Adium](https://github.com/shtrom/Lurch4Adium)!
Olivier Mehani's avatar
Olivier Mehani committed
77

Richard Bayerle's avatar
Richard Bayerle committed
78
### Additional plugins
Richard Bayerle's avatar
Richard Bayerle committed
79
The current version of _libpurple_'s _XMPP_ protocol plugin does not support many _XEPs_ by itself. For more features and compatibility with other clients such as _Conversations_ you can install the pulgins below.
80

Richard Bayerle's avatar
Richard Bayerle committed
81
82
#### carbons
If you have multiple devices and want messages sent and received by one device show up on all others, [XEP-0280: Message Carbons](https://xmpp.org/extensions/xep-0280.html) is what you are looking for.
83

Richard Bayerle's avatar
Richard Bayerle committed
84
You can find my plugin for it here: https://github.com/gkdr/carbons
Richard Bayerle's avatar
Richard Bayerle committed
85

Richard Bayerle's avatar
Richard Bayerle committed
86
87
#### pidgin-xmpp-receipts
In order to support the checkmarks for delivered messages, you could install this plugin implementing [XEP-0184: Message Delivery Receipts](https://xmpp.org/extensions/xep-0184.html):
Richard Bayerle's avatar
Richard Bayerle committed
88

Richard Bayerle's avatar
Richard Bayerle committed
89
 https://app.assembla.com/spaces/pidgin-xmpp-receipts/git/source
Richard Bayerle's avatar
Richard Bayerle committed
90

gkdr's avatar
gkdr committed
91
## Usage
Richard Bayerle's avatar
Richard Bayerle committed
92
93
### General
The first thing you can do to check if this plugin works is enter the `/lurch help` command in any conversation window. You will receive a list of the other commands you can use. I know this is a bit clunky, but using the command interface for interactions makes the plugin usable in clients that do not have a GUI.
gkdr's avatar
gkdr committed
94

Richard Bayerle's avatar
Richard Bayerle committed
95
After you have made sure it was installed correctly, you do not have to activate it specifically for each conversation partner you want to use it with, unlike with e.g. _OTR_. If it detects that the other side is using _OMEMO_ (by the existence of an _OMEMO_ devicelist), the conversation will be encrypted automatically. If you do not want this, you can blacklist the user by typing `/lurch blacklist add` in the conversation window.
gkdr's avatar
gkdr committed
96

Richard Bayerle's avatar
Richard Bayerle committed
97
This plugin will set the window title to notify the user if encryption is enabled or not. If it is, it will generally not send plaintext messages. If a plaintext message is received in a chat that is supposed to be encrypted, the user will be warned.
gkdr's avatar
gkdr committed
98

Richard Bayerle's avatar
Richard Bayerle committed
99
100
101
102
### Group Chats
Group chats (via [XEP-0045: Multi-User Chat](https://xmpp.org/extensions/xep-0045.html) aka MUCs) are __not__ part of the _OMEMO_ specification, but can work under specific circumstances as outlined on the [_Conversations_ README](https://github.com/siacs/Conversations/blob/master/README.md#omemo). These are:
* The MUC has to be non-anonymous so the real JID of each participant is visible. The channel owner has to set this property. In Pidgin you can get there by typing `/config`.
* Every participant has to be in every other participant's contact list! This is why this really only makes sense for member-only MUCs.
gkdr's avatar
gkdr committed
103

Richard Bayerle's avatar
Richard Bayerle committed
104
Once you have confirmed these conditions are met, every member has to activate _OMEMO_ him- or herself. Using this plugin it works by typing `/lurch enable`. Warning messages are displayed if it does not work for every user in the conference, hopefully helping to fix the issue.
105

Richard Bayerle's avatar
Richard Bayerle committed
106
It is __recommended__ you confirm the fingerprints look the same on each device, including among your own.To do this, you can e.g. display all fingerprints participating in a conversation using `/lurch show fp conv`.
gkdr's avatar
gkdr committed
107

Richard Bayerle's avatar
Richard Bayerle committed
108
## Bug Reports
109
If something does not work as expected, don't hesitate to open an issue.
Richard Bayerle's avatar
Richard Bayerle committed
110
You can also reach me on the Pidgin IRC channel (#pidgin on freenode) as `riba`, or send me an email.
111
112
113
114
115
116
117
118
119
120
121

It will usually be helpful (i.e. I will probably ask for it anyway) if you provide me with some information from the debug log, which you can find at _Help->Debug Window_ in Pidgin.

In case it is more serious and Pidgin crashes, I will have to ask you for a backtrace.
You can obtain it in the following way:
* Open Pidgin in gdb: `gdb pidgin`
* Run it: `run`
* Do whatever you were doing to make it crash
* When it does crash, type `bt` (or `backtrace`)
* Copy the whole thing

Richard Bayerle's avatar
Richard Bayerle committed
122
## FAQ
Richard Bayerle's avatar
Richard Bayerle committed
123
124
### Can it talk to other OMEMO clients?
__Yes__, it was (briefly) tested with:
Richard Bayerle's avatar
Richard Bayerle committed
125
126
127
* [Conversations](https://conversations.im/) (Android)
* [The gajim OMEMO plugin](https://dev.gajim.org/gajim/gajim-plugins/wikis/OmemoGajimPlugin) (Desktop OSs)
* [ChatSecure](https://chatsecure.org/) (iOS)
Richard Bayerle's avatar
Richard Bayerle committed
128

Richard Bayerle's avatar
Richard Bayerle committed
129
See https://omemo.top/ for additional clients.
Richard Bayerle's avatar
Richard Bayerle committed
130

Richard Bayerle's avatar
Richard Bayerle committed
131
132
### Does it work with Finch?
It should, but I only tried it briefly.
Richard Bayerle's avatar
Richard Bayerle committed
133

gkdr's avatar
gkdr committed
134
## Caveats
Richard Bayerle's avatar
Richard Bayerle committed
135
136
137
138
139
_OMEMO_ is not 'whatever Conversations can do', but a very specific _XEP_.

For instance, if you don't install the additional plugin mentioned above, this is probably not the right thing to use if you have multiple clients running at the same time, as there is no message carbons support in libpurple as of now.

At the moment, there is no [XEP-0313: Message Archive Management](https://xmpp.org/extensions/xep-0313.html) aka _MAM_ support in _libpurple_, so there are no 'offline messages'.
gkdr's avatar
gkdr committed
140

Richard Bayerle's avatar
Richard Bayerle committed
141
Finally, I can't stress this enough: This plugin is _highly experimental_, so you __should not trust your life on it__.