{"id":13576106,"url":"https://github.com/gkdr/lurch","last_synced_at":"2025-05-15T20:06:00.057Z","repository":{"id":16632397,"uuid":"80359261","full_name":"gkdr/lurch","owner":"gkdr","description":"XEP-0384: OMEMO Encryption for libpurple.","archived":false,"fork":false,"pushed_at":"2024-10-28T00:36:20.000Z","size":259,"stargazers_count":289,"open_issues_count":55,"forks_count":33,"subscribers_count":23,"default_branch":"dev","last_synced_at":"2025-04-08T02:41:22.579Z","etag":null,"topics":["axolotl","encryption","finch","jabber","libpurple","messaging","omemo","pidgin","xmpp"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gkdr.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-01-29T17:12:21.000Z","updated_at":"2025-02-15T11:25:54.000Z","dependencies_parsed_at":"2024-01-14T03:50:35.533Z","dependency_job_id":"3e96a1a1-3eba-4e5f-9c9b-d4b766b0afbe","html_url":"https://github.com/gkdr/lurch","commit_stats":{"total_commits":175,"total_committers":21,"mean_commits":8.333333333333334,"dds":0.1885714285714286,"last_synced_commit":"f4a886c177136f9b161dc6eac58935295c39b680"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gkdr%2Flurch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gkdr%2Flurch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gkdr%2Flurch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gkdr%2Flurch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gkdr","download_url":"https://codeload.github.com/gkdr/lurch/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254414499,"owners_count":22067272,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["axolotl","encryption","finch","jabber","libpurple","messaging","omemo","pidgin","xmpp"],"created_at":"2024-08-01T15:01:07.027Z","updated_at":"2025-05-15T20:05:55.029Z","avatar_url":"https://github.com/gkdr.png","language":"C","funding_links":[],"categories":["C"],"sub_categories":[],"readme":"# lurch 0.7.0\n/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 [XEP-0384: OMEMO Encryption](https://xmpp.org/extensions/xep-0384.html). For a higher-level overview, see [the official OMEMO homepage](https://conversations.im/omemo/).\n\n(Plus I thought the word sounds funny.)\n\n## News\nThis section is now the [changelog](https://github.com/gkdr/lurch/blob/master/CHANGELOG.md).\n\n## Table of Contents\n1. [Installation](#installation)\n   1. [Linux](#linux)\n   1. [Windows](#windows)\n   1. [MacOS](#macos)\n   1. [Additional plugins](#additional-plugins)\n1. [Usage](#usage)\n   1. [General](#general)\n   1. [Group Chats](#group-chats)\n1. [Uninstallation](#uninstallation)\n1. [Troubleshooting](#troubleshooting)\n1. [FAQ](#faq)\n1. [Caveats](#caveats)\n\n## Installation\n### Linux\n##### 1. Install the (submodules') dependencies\nBelow 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_.\n\n__Debian, Ubuntu__\n``` bash\nsudo apt install git cmake libpurple-dev libmxml-dev libxml2-dev libsqlite3-dev libgcrypt20-dev build-essential\n```\n__ArchLinux, Parabola__\n``` bash\nsudo pacman -S base-devel git cmake pidgin libpurple mxml libxml2 sqlite libgcrypt\n```\n__Fedora__\n``` bash\nsudo dnf install git cmake libpurple-devel mxml-devel libxml2-devel libsqlite3x-devel libgcrypt-devel\n```\n\n##### 2A. EITHER: Build and install from source\n``` bash\ngit clone https://github.com/gkdr/lurch/\ncd lurch\ngit submodule update --init --recursive\nmake install-home\n```\nIf you just pull a newer version (`git pull`), remember to also update the submodules as they might have changed!\n\nThe last command compiles the whole thing and copies the plugin into your local _libpurple_ plugin directory.\n\nThe next time you start Pidgin, or another libpurple client, you should be able to activate it in the \"Plugins\" window.\n\n##### 2B. OR: Install from a community repo\n* Arch - AUR: https://aur.archlinux.org/packages/libpurple-lurch-git/\n* Fedora - COPR:  https://copr.fedorainfracloud.org/coprs/treba/pidgin-lurch/\n\n\n### Windows\nThanks to [EionRobb](https://github.com/EionRobb), Windows users can use the dlls he compiled and provides here: https://eion.robbmob.com/lurch/\n\n1. Download the plugin (_lurch.dll_) and put it in the `Program Files (x86)\\Pidgin\\plugins` directory.\n2. Download _libgcrypt-20.dll_ and _libgpg-error-0.dll_ and put them in the `Program Files (x86)\\Pidgin` directory.\n\nThese instructions can also be found at the provided link.\n\n### MacOS\nHomebrew should have all dependencies:\n\n```\nbrew install cmake pidgin glib libxml2 libmxml sqlite libgcrypt\n```\nThis 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!\n\nAlternatively, if you use Adium, you should definitely check out [shtrom](https://github.com/shtrom)'s [Lurch4Adium](https://github.com/shtrom/Lurch4Adium)!\n\n### Additional plugins\nThe 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.\n\n#### carbons\nIf 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.\n\nYou can find my plugin for it here: https://github.com/gkdr/carbons\n\n#### pidgin-xmpp-receipts\nIn 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):\n\n https://app.assembla.com/spaces/pidgin-xmpp-receipts/git/source\n\n## Usage\n### General\nThe 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.\n\nAfter 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.\n\nThis 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.\n\n### Group Chats\nGroup 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:\n* 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`.\n* Every participant has to be in every other participant's contact list! This is why this really only makes sense for member-only MUCs.\n\nOnce 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.\n\nIt 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`.\n\n## Uninstallation\nIn order to uninstall this plugin, you should call the `/lurch uninstall` command.\nIt will remove this client from the _OMEMO_ device list, notifying other _OMEMO_ clients that they do not need to encrypt messages for it any longer.\n\nAfterwards, you can just deactivate the plugin in the _Tools \u003e Plugins_ window.\n\nIn order to completely remove all data related to this plugin, e.g. for a fresh installation, you will need to delete the following files from your _.purple_ directory:\n* `your@xmpp.account_omemo_db.sqlite` to delete the device list cache \n* `your@xmpp.account_axc_db.sqlite` to delete your keypair and all sessions with other devices\n* and finally, `lurch.[so|dll]` found in the _plugins_ directory\n\n\n## Troubleshooting\nIf something does not work as expected, don't hesitate to open an issue.\nYou can also reach me on the Pidgin IRC channel (#pidgin on freenode) as `riba`, or send me an email.\n\nIt 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 \u003e Debug Window_ in Pidgin.\nThere, you will see a scary error from the XML parser every time you receive a message, which you can safely ignore. It is due to the nonstandard namespace used by _OMEMO_ and looks something like this: `jabber: XML parser error for JabberStream 0x5631ed678670: Domain 3, code 100, level 1: xmlns: URI eu.siacs.conversations.axolotl is not absolute`.\n\nIn addition to just reading logs, you can get a bit more active, as again I will probably ask for this anyway.\nPidgin comes with an XMPP console, but you have to activate the plugin first (_Tools \u003e Plugins_).\nAfterwards you can find it at _Tools \u003e XMPP Console_ and send queries to the server.\n\nIf you are having trouble sending or receiving messages, you should look up if you can find the device in the _device list_. You can do so by pasting the following into the XMPP console, replacing the `to` attribute with the device's owner's JID:\n```XML\n\u003ciq type='get'\n    to='b@localhost'\n    id='whatever123'\u003e\n  \u003cpubsub xmlns='http://jabber.org/protocol/pubsub'\u003e\n    \u003citems node='eu.siacs.conversations.axolotl.devicelist'/\u003e\n  \u003c/pubsub\u003e\n\u003c/iq\u003e\n```\n\nSometimes, a device might be on the list, but it did not publish a _bundle_, which is necessary to establish a session. In this case, you can query this bundle by pasting the following, replacing the `to` attribute as well as the `DEVICE_ID` suffix of the `bundles` node:\n\n```XML \n\u003ciq type='get' \n    to='b@localhost'\n    id='whatever456'\u003e\n  \u003cpubsub xmlns='http://jabber.org/protocol/pubsub'\u003e\n    \u003citems node='eu.siacs.conversations.axolotl.bundles:DEVICE_ID' max_items='1'/\u003e\n  \u003c/pubsub\u003e\n\u003c/iq\u003e\n```\n\nFinally, in case it is more serious and Pidgin crashes, I will have to ask you for a backtrace.\nYou can obtain it in the following way:\n* Open Pidgin in gdb: `gdb pidgin`\n* Run it: `run`\n* Do whatever you were doing to make it crash\n* When it does crash, type `bt` (or `backtrace`)\n* Copy the whole thing\n\n## FAQ\n### Can it talk to other OMEMO clients?\n__Yes__, it was (briefly) tested with:\n* [Conversations](https://conversations.im/) (Android)\n* [The gajim OMEMO plugin](https://dev.gajim.org/gajim/gajim-plugins/wikis/OmemoGajimPlugin) (Desktop OSs)\n* [ChatSecure](https://chatsecure.org/) (iOS)\n\nSee https://omemo.top/ for additional clients.\n\n### Does it work with Finch?\nIt should, but I only tried it briefly.\n\n## Caveats\n_OMEMO_ is not 'whatever Conversations can do', but a very specific _XEP_.\n\nFor 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.\n\nAt 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'.\n\nFinally, I can't stress this enough: This plugin is _highly experimental_, so you __should not trust your life on it__.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgkdr%2Flurch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgkdr%2Flurch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgkdr%2Flurch/lists"}