Article by editor Leo [email protected]
Pantalaimon is a End-to-End Encryption (E2EE) aware proxy daemon that connects to a Matrix server and handles sending and receiving messages. It also handles verifying sessions, verifying or blacklisting devices, and exporting/importing session keys.
Its main use-case is to provide clients that have not yet fully implemented some of the most important Matrix’s features, namely verifying devices and End-to-End encryption, a good man-in-the-middle that does it transparently for you.
Today we will set up a local
pantalaimon daemon and log in with
Fractal, the GNOME client for Matrix. We will also learn how to use the
panctl program from Pantalaimon to verify the session we started with Fractal.
The first step is installing Pantalaimon. It can be installed via
pip as it
is a python program, but we will instead use our distro repositories, in this
case Alpine Linux.
# apk add pantalaimon pantalaimon-ui
We also need to install Fractal, instead of using the distro repositories lets use the flatpak-ed version from FlatHub:
$ flatpak install fractal Looking for matches… Found similar ref(s) for ‘fractal’ in remote ‘flathub’ (user). Use this remote? [Y/n]: Found ref ‘app/org.gnome.Fractal/x86_64/stable’ in remote ‘flathub’ (user). Use this ref? [Y/n]: Required runtime for org.gnome.Fractal/x86_64/stable (runtime/org.gnome.Platform/x86_64/3.36) found in remote flathub Do you want to install it? [Y/n]: org.gnome.Fractal permissions: ipc network pulseaudio wayland x11 dri dbus access   org.freedesktop.Notifications, org.freedesktop.secrets ID Branch Op Remote Download 1. [✓] org.gnome.Fractal.Locale stable i flathub 4.8 kB / 233.8 kB 2. [✓] org.gnome.Platform.Locale 3.36 i flathub 17.7 kB / 323.1 MB 3. [✓] org.gnome.Platform 3.36 i flathub 172.7 MB / 326.0 MB 4. [✓] org.gnome.Fractal stable i flathub 3.5 MB / 3.6 MB Installation complete.
Now that we have Pantalaimon installed we need to create the configuration file,
the location is
[local-matrix] Homeserver = https://matrix.org ListenAddress = localhost ListenPort = 8010
Homeserver key holds what is the server you’re connecting to.
ListenAddress key decides the URL where the daemon will listen for
connections, in this case we are doing a local server so use localhost.
ListenPort decides what port of the URL that pantalaimon is going to
Now we run the daemon and start our client, just invoke the
and start the flatpak via
flatpak run org.gnome.Fractal.
When Fractal asks us for our provider instead of using the
Homeserver, which is
normally expected, we instead put the
pantalaimon as shown below:
We now need to verify the Pantalaimon session, in this case we need an already verified device running that can perform verification, one can safely use the Element Web on the Desktop or the Mobile application.
We will use the
panctl binary, which interacts with the running
daemon and allows us to verify our session.
Getting info from panctl
But first lets take a look at what information
panctl can give to us. It is
very important as we need the the correct ID of the device.
$ panctl panctl> list-servers
pantalaimon servers: - Name: local-matrix - Pan users: - @maxice8:matrix.org BFXSMBOBLH
We have one server running, the
Name key holds the value that is present in
our configuration, and the
Pan users collection holds all the users that are
logged in, in this case we are logged in via fractal and our id is
panctl> list-devices @maxice8:matrix.org @maxice8:matrix.org
Devices for user @maxice8:matrix.org: - Display name: FluffyChat android - Device id: UXOXMSYWMH - Device key: [STRENG GEHEIM] - Trust state: Verified - Display name: Element Desktop (Linux) - Device id: QPOOTXJLUS - Device key: [STRENG GEHEIM] - Trust state: Verified
Those are my devices, you can see I use FlufflyChat on my Android phone and have Element Desktop on my desktop, we will use the latter to perform the confirmation.
Important here is to take note of the ID of the device we want to start the
verification with, in this case the ID is
Starting verification from panctl
First we call the start-verification program
panctl> start-verification @maxice8:matrix.org @maxice8:matrix.org QPOOTXJLUS Successfully started the key verification request
Then we look at our Element client:
continue, and then switch back to
panctl we need to check if the
Short authentication string for pan user @maxice8:matrix.org from @maxice8:matrix.org via QPOOTXJLUS: 🚀 🔑 🍎 🚂 🎸 ⚓ 🔧 Rocket Key Apple Train Guitar Anchor Wrench
If they match we can click
They match in Element and on panctl we need to
panctl> confirm-verification @maxice8:matrix.org @maxice8:matrix.org QPOOTXJLUS Device QPOOTXJLUS of user @maxice8:matrix.org succesfully verified for pan user @maxice8:matrix.org.
And in your Element client ?
Now, that doesn’t mean we are done, we can also import/export the End-to-End encryption keys to be used in other contexts.
panctl> export-keys @maxice8:matrix.org ~/tmp/ourkeys pass Succesfully exported keys for @maxice8:matrix.org to /home/enty/tmp/ourkeys panctl> import-keys @maxice8:matrix.org ~/tmp/ourkeys pass Succesfully imported keys for @maxice8:matrix.org from /home/enty/tmp/ourkeys