Startup and verification workflow is not well documented

[ppar]

This is a bind long-winded, but I decided to roll these thoughts into a single ticket since they mostly address the same point from different angles.

I'm happy to provide some documentation PRs if/when I get pantalaimon working for myself and understand these missing bits.

Also related: #155

TL/DR

As a Matrix end user (not familiar with Matrix internals, but able to run a UNIX daemon in general), the steps to take after installing Pantalaimon and creating my config file are not very clear.

How do I get to a point where pantalaimon is en/decrypting my messages, and my encrypted message history is visible in my client?

Missing step-by-step instructions

The "Usage" chapter in the README and/or the man pages should answer questions like:

• When first starting and connecting to the daemon, do I need to take steps in panctl - if so, what and in which order?
• Are there alternatives panctl (see DBUS/UI comments below)?
• Do I need to take steps in my existing Matrix clients - if so, what and in which order?

The animated gif at the top or the README alludes to some kind of workflow, but obviously an animation like this is impossible to follow.

DBUS / UI?

This paragraph in README.md is confusing:

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]

• Does this simply mean that installing pantalaimon[ui] makes pantalaimon expose a DBUS service that panctl can connect to? Then it's not a UI, it's an API.
• Why is it optional? AFAIK verifying your login is necessary in order to use any encryption features - what is the alternative way to handle the verification?

What does the "If user interaction is required pantalaimon will send out OS notifications which the user can react to." part in the pantalaimon(8) man page mean in practice?

• Desktop notifications that will appear in KDE/GNOME/etc?
• Or just the DBUS communication with panctl?

panctl man page

The man page for panctl only covers syntax, not semantics or purpose:

• What does each of these commands do? This should be put into adequate context for an end user.
• What do each of the arguments mean?
  • What is a pan-user? How do I know what my pan-user is? (The pantalaimon(8) man page briefly defines the term, but not where to find the value)
  • Same for user_id
  • device_id seems obvious, but which device's ID in a given situation?

[adham-omran]

I just got done with an attempt to setup alphapapa/ement.el.

I had to get the inital verivications using panctl with trial-and-error but the process was like this

1. Open Element and request to verify the pantalaimon session
2. Run panctl
3. Run start-verification @user:domain.tld @user:domain.tld device_id where the device_id is found in the privacy settings in the Element settings
4. Match the emojis
5. Run confirm-verification @user:domain.tld @user:domain.tld device_id

And I still have the issue where Emacs has Unable to decrypt: The sender's device has not sent us the keys for this message everywhere although I connected as document in the ement.el documentation.

Also sending requires you to run send-anyways @user:domain.tld !STUFF:matrix.org and I only managed to do this by hitting tab.

[rgri]

@adham-omran Did you ever get this working? Trying to setup right now and start-verification is doing nothing.

[alphapapa]

And I still have the issue where Emacs has Unable to decrypt: The sender's device has not sent us the keys for this message everywhere although I connected as document in the ement.el documentation.

I don't use Pantalaimon myself, but from what I've gathered, verification is only one of the required steps. You also need to send/receive the appropriate keys.

And we really, really need these procedures to be documented, correctly, in one place, for all users. I've watched so many users stumble through the process, but it seems that none of them will take a few moments to write down what they did to save the next person the trouble.

[Arnavion]

I just set it up. Here are the steps for Linux, as of 2024-02-18, using pantalaimon-0.10.5 installed from pip:

1. Ensure you have an OS keyring installed. In my case I installed gnome-keyring. You may also want a GUI like seahorse to inspect the keyring. (pantalaimon will work without a keyring but your client will have to log in with the password every time pantalaimon is restarted, instead of being able to reuse the access token from the previous successful login.)

2. Create ~/.config/pantalaimon/pantalaimon.conf as the README says, except that the Homeserver = URL should use port 443, not port 8448 as the README says. (Pantalaimon is a client, not a federating server, so 443 is the correct port.)

3. In case you have prior attempts, clean the slate by deleting the ~/.local/share/pantalaimon directory.

4. Start pantalaimon.

5. Connect a client to the ListenAddress:ListenPort you specified in pantalaimon.conf, eg to 127.0.0.1:8009, using the same username and password you would've used to login to your homeserver directly.

6. The login should succeed, but at this point all encrypted messages will fail to decrypt. This is fine.

7. Start another client that you were already using for your encrypted chats previously. In my case this was app.element.io, so the rest of the steps here assume that.

8. Run panctl. At the prompt, run start-verification <user ID> <user ID> <Element's device ID>. <user ID> here is the full user ID like @arnavion:arnavion.dev. If you only have the one Element session, panctl will show you the device ID as an autocomplete hint so you don't have to look it up. If you do need to look it up, go to Element -> profile icon -> All Settings -> Sessions, expand the "Current session" item, and the "Session ID" is the device ID.

9. In Element you will see a popup "Incoming Verification Request". Click "Continue". It will change to a popup containing some emojis, and panctl will print the same emojis. Click the "They match" button. It will now change to a popup like "Waiting for other client to confirm..."

10. In panctl, run confirm-verification <user ID> <user ID> <Element's device ID>, ie the same command as before but with confirm-verification instead of start-verification.

11. At this point, if you look at all your sessions in Element (profile icon -> All Settings -> Sessions), you should see "pantalaimon" in the "Other sessions" list as a "Verified" session.

12. Export the E2E room keys that Element was using via profile icon -> Security & Privacy -> Export E2E room keys. Pick any password and then save the file to some path.

13. Back in panctl, run import-keys <user ID> <path of file> <password you used to encrypt the file>. After a few seconds, in the output of pantalaimon, you should see a log like INFO: pantalaimon: Successfully imported keys for <user ID> from <path of file>

14. Close and restart the client you had used in step 5, ie the one you want to connect to pantalaimon. Now, finally, you should be able to see the encrypted chats be decrypted.

15. Delete the E2E room keys backup file from step 12. You don't need it any more.

16. If in step 11 you had other unverified sessions from pantalaimon from your prior attempts, you can sign out of them too.

---

You will probably have to repeat steps 12-15 any time you start a new encrypted chat in Element.

[alphapapa]

@Arnavion Thanks, that's a very concise step-by-step guide!

[chookity-pokk]

This is fixed thanks to @Arnavion's comment which has now been added to the README.