README.md 7.13 KB
Newer Older
Richard Bayerle's avatar
Richard Bayerle committed
1
# lurch 0.6.5
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 [OMEMO](https://conversations.im/omemo/).
gkdr's avatar
gkdr committed
3
4
5

(Plus I thought the word sounds funny, especially when pronounced by a speaker of English.)

Richard Bayerle's avatar
Richard Bayerle committed
6
## News
Richard Bayerle's avatar
Richard Bayerle committed
7
8
9
10
11
12
0.6.5 is out and you should get it as it contains important security updates.

If you use any text-formatting, through XHTML-IM a whole plaintext copy of your text was sent along with the ciphertext, which is obviously bad.
The `<html>` tags and any additional `<body>` tags are now stripped from the message.

Also, the tag is now appended to the key, i.e. is part of the data which is encrypted with the double ratchet session.
Richard Bayerle's avatar
Richard Bayerle committed
13

gkdr's avatar
gkdr committed
14
## Installation
15
16
17
### From a package (easy)
#### Linux
##### Arch Linux
18
19
20
21
22
23
24
25
26

``` bash
sudo pacman -S base-devel git pidgin libpurple mxml sqlite libxml2 libgcrypt
git clone https://aur.archlinux.org/libpurple-lurch-git.git
cd libpurple-lurch-git
makepkg
sudo pacman -U *.xz
```

27
28
29
30
31
32
33
34
### Compiling (harder)
#### Linux (and MacOS?)
1. First, install the (submodules') dependencies
* `libpurple-dev`
* `libmxml-dev`
* `libxml2-dev`
* `libsqlite3-dev`
* `libgcrypt20-dev`
35

36
37
38
39
40
41
42
These might have different names in different GNU/Linux distributions (such as Fedora or Arch, for instance).

You'll also need `cmake` to compile and you'll most likely want to install `git` to download (and in the future, update) the code easily.

For some hints on how to get the required libraries on macOS, see issue #8.

##### Debian, Ubuntu
43
44
45
Unfortunately, _Debian Stable_ comes with an older version of _mxml_ (2.6).
See issues #30 and #35 on some hints how to get a newer version from the _Testing_ repositories (2.7 is required).

46
47
48
49
50
On Debian testing and Ubuntu 16.04, you can install the dependencies with this command:

``` bash
sudo apt install cmake git libpurple-dev, libmxml-dev, libxml2-dev, libsqlite3-dev, libgcrypt20-dev
```
51

52
53
###### ArchLinux, Parabola
On Arch and Parabola, you can install the dependencies with this command:
54
55
56
57

``` bash
sudo pacman -S base-devel git pidgin libpurple mxml sqlite libxml2 libgcrypt
```
58
59
60
61
62
63
64
##### Fedora
On Fedora, you can install the dependencies with this command:


``` bash
sudo dnf install cmake git libpurple-devel mxml-devel libxml2-devel libsqlite3x-devel libgcrypt-devel
```
65

66
2. Then, get the source code, including all submodules and their submodules:
67
68
69
70

``` bash
git clone https://github.com/gkdr/lurch/
cd lurch
Richard Bayerle's avatar
Richard Bayerle committed
71
git submodule update --init --recursive
72
73
```

74
If you just pull a newer version (`git pull`), remember to also update the submodules as they might have changed!
75

76
3. Finally, build and install with:
77
78
79
80
81
82
83
84
85

``` bash
make
make install-home
```

Which copies the compiled plugin into your local libpurple plugin directory.

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

Richard Bayerle's avatar
Richard Bayerle committed
87
88
### Windows
Thanks to EionRobb, Windows users can use the dlls he compiled and provides here: https://eion.robbmob.com/lurch/
89

90
1. Download the plugin .dll itself and put it in the `Program Files\Pidgin\plugins` directory. If you want to talk to other OMEMO clients, use _lurch-compat.dll_.
91
2. Download _libgcrypt-20.dll_ and _libgpg-error-0.dll_ and put them in the `Program Files\Pidgin` directory.
92
93

These instructions can also be found at the provided link.
Richard Bayerle's avatar
Richard Bayerle committed
94
95
96
97
98
99
100

### More
The current version of libpurple does not come with [Message Carbons](https://xmpp.org/extensions/xep-0280.html) support, i.e. if you have multiple devices, your Pidgin might not receive that message, and if you write messages on other devices, you do not see them either.

Lucky for you, I wrote another plugin to fix this! You can find it here: https://github.com/gkdr/carbons
Be aware that both are really experimental and might not work well, especially not together.

gkdr's avatar
gkdr committed
101
## Usage
gkdr's avatar
gkdr committed
102
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
103

gkdr's avatar
gkdr committed
104
For conversations with one other user, it is automatically activated if the other user is using OMEMO too. 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
105

gkdr's avatar
gkdr committed
106
In groupchats, encryption has to be turned on first by typing `/lurch enable`. This is a client-side setting, so every participant has to do this in order for it to work. Warning messages are displayed if it does not work for every user in the conference, hopefully helping to fix the issue.
gkdr's avatar
gkdr committed
107

gkdr's avatar
gkdr committed
108
109
The same restrictions as with other OMEMO applications apply though - each user has to have every other user in his buddy list, otherwise the information needed to build a session is not accessible. Thus, it is recommended to set it to members-only.
Additionally, the room has to be set to non-anonymous so that the full JID of every user is accessible - otherwise, the necessary information cannot be fetched.
gkdr's avatar
gkdr committed
110

111
112
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
113
More information on the available commands can be found by typing `/lurch help` in any conversation window.
gkdr's avatar
gkdr committed
114

115
116
117
118
119
120
121
122
123
124
125
126
127
128
## It doesn't work!
If something does not work as expected, don't hesitate to open an issue.
You can also reach me on the Pidgin IRC channel (#pidgin on freenode) as `_riba`, or send me an email.

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
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
## Answers
### Can it talk to other OMEMO clients?
__Yes__, it was (briefly) tested with:
* [Conversations](https://conversations.im/)
* [The gajim OMEMO plugin](https://dev.gajim.org/gajim/gajim-plugins/wikis/OmemoGajimPlugin)
* [Mancho's libpurple plugin](https://git.imp.fu-berlin.de/mancho/libpurple-omemo-plugin)

### Do encrypted group chats work?
Yes.

### Does it work in Finch?
Mostly, but I only tried it briefly.

It only uses libpurple functions, so if they are implemented in the client correctly, they should work.
That being said, indicating encrypted chats by setting the topic does not seem to work in Finch (maybe just because window titles are very short). The encryption itself does work though, which you can confirm by looking at the sent/received messages in the debug log.

gkdr's avatar
gkdr committed
145
## Caveats
Richard Bayerle's avatar
Richard Bayerle committed
146
147
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.
MAM for "catchup" and offline messages is also not supported by libpurple.
gkdr's avatar
gkdr committed
148

Richard Bayerle's avatar
Richard Bayerle committed
149
Again: This plugin is _highly experimental_, so you should not trust your life on it.