313a5d528c
Suppose that Alice logs in using Element. Before this change, when Bob would send a DM to Alice through Pantalaimon, Alice would not be able to decrypt Bob's initial message. Instead, she would see "Unable to decrypt: The sender's device has not sent us the keys for this message." and Pantalaimon's olmsessions table would have no associated records. Any future messages would be visible however. On the other hand, when Alice (using Element) is the one to send the first DM to Bob, he can decrypt the initial message. For Pantalaimon to execute /keys/claim, get_missing_sessions must return the invitee's device (and log "Missing session for device"). If Pantalaimon calls this method too soon, then self.device_store will not have the device. To populate self.device_store before Pantalaimon calls get_missing_sessions, it must execute /keys/query (and invoke _handle_key_query) earlier, during the /createRoom request. Pantalaimon does execute the /keys/query request during a sync after the server finishes creating the DM (and logs "Adding new device to the device store for user"), but only after checking unsuccessfully for the device in self.device_store. After this change, Pantalaimon executes /keys/claim, there is one record in olmsessions, and Alice can decrypt Bob's initial message. |
||
|---|---|---|
| .github/workflows | ||
| contrib | ||
| docs | ||
| pantalaimon | ||
| tests | ||
| .flake8 | ||
| .gitignore | ||
| .isort.cfg | ||
| .travis.yml | ||
| CHANGELOG.md | ||
| Dockerfile | ||
| LICENSE | ||
| Makefile | ||
| MANIFEST.in | ||
| README.md | ||
| setup.py | ||
| test-requirements.txt | ||
| tox.ini | ||
pantalaimon
Pantalaimon is an end-to-end encryption aware Matrix reverse proxy daemon. Pantalaimon acts as a good man in the middle that handles the encryption for you.
Messages are transparently encrypted and decrypted for clients inside of pantalaimon.
Installation
The Olm C library is required to be installed before installing pantalaimon.
If your distribution provides packages for libolm it is best to use those, note that a recent version of libolm is required (3.1+). If your distribution doesn't provide a package building from source is required. Please refer to the Olm readme to see how to build the C library from source.
Installing pantalaimon works like usually with python packages:
python setup.py install
Pantalaimon can also be found on pypi:
pip install pantalaimon
Pantalaimon contains a dbus based UI that can be used to control the daemon. The dbus based UI is completely optional and needs to be installed with the daemon:
pip install pantalaimon[ui]
Do note that man pages can't be installed with pip.
macOS installation
For instance, on macOS, this means:
brew install dbus
perl -pi -e's#(<auth>EXTERNAL</auth>)#<!--$1-->#' $(brew --prefix dbus)/share/dbus-1/session.conf
brew services start dbus
# it may be necessary to restart now to get the whole OS to pick up the
# existence of the dbus daemon
git clone https://gitlab.matrix.org/matrix-org/olm
(cd olm; make)
git clone https://github.com/matrix-org/pantalaimon
(cd pantalaimon; CFLAGS=-I../olm/include LDFLAGS=-L../olm/build/ python3 setup.py install)
export DBUS_SESSION_BUS_ADDRESS=unix:path=$(launchctl getenv DBUS_LAUNCHD_SESSION_BUS_SOCKET)
cd pantalaimon
DYLD_LIBRARY_PATH=../olm/build/ pantalaimon -c contrib/pantalaimon.conf
# for notification center:
git clone https://github.com/fakechris/notification-daemon-mac-py
# if you have django's `foundation` library installed and your filesystem
# is case insensitive (the default) then you will need to `pip uninstall foundation`
# or install PyObjC in a venv...
pip install PyObjC daemon glib dbus-python
cd notification-daemon-mac-py
./notify.py
Docker
An experimental Docker image can be built for Pantalaimon, primarily for use in bots.
docker build -t pantalaimon .
# Create a pantalaimon.conf before running. The directory mentioned in the
# volume below is for where Pantalaimon should dump some data.
docker run -it --rm -v /path/to/pantalaimon/dir:/data -p 8008:8008 pantalaimon
The Docker image in the above example can alternatively be built straight from any branch or tag without the need to clone the repo, just by using this syntax:
docker build -t pantalaimon github.com/matrix-org/pantalaimon#master
An example pantalaimon.conf for Docker is:
[Default]
LogLevel = Debug
SSL = True
[local-matrix]
Homeserver = https://matrix.org
ListenAddress = 0.0.0.0
ListenPort = 8008
SSL = False
UseKeyring = False
IgnoreVerification = True
Usage
While pantalaimon is a daemon, it is meant to be run as the same user as the app it is proxying for. It won't verify devices for you automatically, unless configured to do so, and requires user interaction to verify, ignore or blacklist devices. A more complete description of Pantalaimon can be found in the man page.
Pantalaimon requires a configuration file to run. The configuration file specifies one or more homeservers for pantalaimon to connect to.
A minimal pantalaimon configuration looks like this:
[local-matrix]
Homeserver = https://localhost:8448
ListenAddress = localhost
ListenPort = 8009
The configuration file should be placed in ~/.config/pantalaimon/pantalaimon.conf.
The full documentation for the pantalaimons configuration can be found in
the man page pantalaimon(5).
Now that pantalaimon is configured it can be run:
pantalaimon --log-level debug
After running the daemon, configure your client to connect to the daemon instead of your homeserver. The daemon listens by default on localhost and port 8009.
Note that logging in to the daemon is required to start a sync loop for a user. After that clients can connect using any valid access token for the user that logged in. Multiple users per homeserver are supported.
For convenience a systemd service file is provided.
To control the daemon an interactive utility is provided in the form of
panctl.
panctl can be used to verify, blacklist or ignore devices, import or export
session keys, or to introspect devices of users that we share encrypted rooms
with.