DOCSEARCHbyAlgolia
Submit Docs

Pantalaimon

repository·master·Indexed 43 days ago

https://github.com/matrix-org/pantalaimon

An end-to-end encryption aware Matrix reverse proxy daemon that transparently handles encryption and decryption for Matrix clients. It includes the panctl utility for managing devices, interactive key verification, and importing/exporting E2EE keys.

Tokens
7.3K
Snippets
22
Records
44
Agent score
47%

What's inside Pantalaimon

  2. Run Pantalaimon with Docker

    master

    An experimental Docker image is available, primarily for use in bots.

    To build the image:

    docker build -t pantalaimon .
# Or build from a specific branch/tag:
docker build -t pantalaimon github.com/matrix-org/pantalaimon#master

    To run the container, you must provide a pantalaimon.conf file and mount a directory for data persistence:

    docker run -it --rm -v /path/to/pantalaimon/dir:/data -p 8008:8008 pantalaimon
    docker run -it --rm -v /path/to/pantalaimon/dir:/data -p 8008:8008 pantalaimon

  3. Run the pantalaimon daemon

    master

    Pantalaimon is a reverse proxy daemon that handles end-to-end encryption for Matrix clients. It should be run as your own user and listens on a non-privileged port. Clients register themselves with the daemon via standard Matrix HTTP calls, creating a 'pan user' that maintains its own sync loop. Multiple clients can use the same pan user.

    To run the daemon, use the following command structure:

    pantalaimon [-c config] [--log-level level] [--data-path path]
    pantalaimon

  4. Install Pantalaimon

    master

    Pantalaimon requires the Olm C library (version 3.1+) to be installed on your system before proceeding.

    Standard Installation

    You can install Pantalaimon using pip. It is recommended to use a virtual environment.

    To install the core daemon:

    pip install pantalaimon

    To install the daemon with the optional DBus-based UI:

    pip install pantalaimon[ui]

    Alternatively, you can install from the local source:

    python setup.py install
# or
pip install .
    pip install pantalaimon[ui]

  5. Install Pantalaimon on macOS

    master

    Installing on macOS requires manual setup of dbus and building olm from source.

    1. Install and configure dbus via Homebrew:
    brew install dbus
perl -pi -e's#(<auth>EXTERNAL</auth>)#<!--$1-->#' $(brew --prefix dbus)/share/dbus-1/session.conf
brew services start dbus
    1. Build olm and pantalaimon from source:
    # Build Olm
git clone https://gitlab.matrix.org/matrix-org/olm
(cd olm; make)

# Build Pantalaimon
git clone https://github.com/matrix-org/pantalaimon
(cd pantalaimon; CFLAGS=-I../olm/include LDFLAGS=-L../olm/build/ python3 setup.py install)
    1. Run Pantalaimon:
    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
    1. (Optional) For macOS Notification Center support, install notification-daemon-mac-py and its dependencies (PyObjC, daemon, glib, dbus-python). Note: if you have Django's foundation library installed on a case-insensitive filesystem, you must pip uninstall foundation or use a venv with PyObjC.
    DYLD_LIBRARY_PATH=../olm/build/ pantalaimon -c contrib/pantalaimon.conf

  6. Migrate existing E2E sessions to Pantalaimon

    master

    If you are moving an existing encrypted session (e.g., from Element) to Pantalaimon, follow these steps to ensure continuity of encrypted chats:

    1. Prepare: Ensure an OS keyring (like gnome-keyring) is installed so Pantalaimon can reuse access tokens. Clean ~/.local/share/pantalaimon if you have prior failed attempts.
    2. Start Daemon: Run pantalaimon.
    3. Initial Login: Connect your client to the Pantalaimon ListenAddress:ListenPort using your standard homeserver credentials. The login will succeed, but messages will initially fail to decrypt.
    4. Verification:
      • Open panctl.
      • Run start-verification <user ID> <user ID> <Element's device ID>.
      • In your existing client (e.g., Element), accept the "Incoming Verification Request" and match the emojis shown in panctl.
      • In panctl, run confirm-verification <user ID> <user ID> <Element's device ID>.
    5. Key Import:
      • In your existing client, export your E2E room keys (e.g., via Security & Privacy settings).
      • In panctl, run import-keys <user ID> <path of file> <password used for file>.
    6. Finalize: Restart the client that is now connected to Pantalaimon. Encrypted chats should now be visible.

  7. Configure pantalaimon using an INI configuration file

    master

    Pantalaimon uses an INI-format configuration file to manage one or more proxy instances. Each instance is defined by a section header in square brackets (e.g., [MyInstance]).

    There are two types of sections:

    1. Proxy Instance Sections: Used to define specific settings for a particular homeserver connection.
    2. [Default] Section: A special section used to define global settings that apply to all proxy instances unless overridden within the specific instance section.

    By default, the configuration file is expected at ~/.config/pantalaimon/pantalaimon.conf (following the XDG Base Directory Specification).

    [Default]
LogLevel = info

[MyHomeserver]
Homeserver = https://matrix.example.com
ListenPort = 8009

  8. Configure Pantalaimon

    master

    Pantalaimon requires a configuration file to specify homeservers. The default location is ~/.config/pantalaimon/pantalaimon.conf.

    Minimal Configuration

    [local-matrix]
Homeserver = https://localhost:443
ListenAddress = localhost
ListenPort = 8009

    Docker Example Configuration

    [Default]
LogLevel = Debug
SSL = True

[local-matrix]
Homeserver = https://matrix.org
ListenAddress = 0.0.0.0
ListenPort = 8008
SSL = False
UseKeyring = False
IgnoreVerification = True
    [local-matrix]
Homeserver = https://localhost:443
ListenAddress = localhost
ListenPort = 8009

  9. Configure the pantalaimon.conf file

    master

    pantalaimon uses an INI-format configuration file to manage one or more proxy instances. Each instance is defined by a section header in square brackets (e.g., [MyProxy]).

    Instance Sections

    Each instance section must include the Homeserver key. Other keys are optional and control how the proxy interacts with that specific homeserver.

    Required Keys:

    • Homeserver: The URI of the homeserver (including http(s) schema, but excluding the Matrix API path).

    Optional Keys:

    • ListenAddress: The address to listen for client connections. Defaults to localhost.
    • ListenPort: The port to listen for client connections. Defaults to 8009. Note: Each instance must have a unique address/port combination.
    • Proxy: The URI of an HTTP proxy to use for outgoing requests to the homeserver. Defaults to direct connection.
    • SSL: Boolean (True/False) to enable/disable SSL verification for outgoing connections. Defaults to True.
    • IgnoreVerification: Boolean (True/False) to automatically ignore new devices and share encryption keys. If False, users must manually verify devices. Defaults to False.
    • UseKeyring: Boolean (True/False) to use the OS keyring for storing access tokens. If No, tokens are stored in plaintext in the database. Defaults to Yes.
    • DropOldKeys: Boolean (True/False) to only keep the latest version of a room key. If True, only new messages are decryptable; history cannot be decrypted. Defaults to No.

    The [Default] Section

    You can define a [Default] section to apply settings to all proxy instances or to configure global daemon behavior.

    Instance-level defaults (applied to all instances):

    • ListenAddress, ListenPort, Proxy, SSL, IgnoreVerification, UseKeyring.

    Global daemon behavior:

    • LogLevel: Sets the logging verbosity. Options: error, warning, info, debug. Defaults to warning.
    • Notifications: Enables or disables OS notifications for actions requiring user intervention (e.g., unverified devices). Options: On, Off. Defaults to On.
    [Default]
LogLevel = Debug
SSL = True
Notifications = On

[Clocktown]
Homeserver = https://localhost:8448
ListenAddress = localhost
ListenPort = 8009
Proxy = http://localhost:8080
SSL = False

  10. How the Pantalaimon proxy architecture works

    master

    Pantalaimon operates as an HTTP reverse proxy using aiohttp. It intercepts Matrix Client API requests and routes them to the appropriate ProxyDaemon instance based on the user or configuration.

    Key Components:

    • ProxyDaemon: Manages the connection to a specific Matrix homeserver and handles the encryption/decryption logic.
    • HTTP Routes: The proxy implements standard Matrix API endpoints (e.g., /login, /sync, /createRoom, /messages, /media/upload) and includes a catch-all route /{proxyPath:.*} to handle any other paths via proxy.router.
    • Message Router: An internal asynchronous task that receives messages from the UI or other components and forwards them to the correct ProxyDaemon using find_proxy_by_user.
    • Data Storage: Uses KeyDroppingSqliteStore if the configuration specifies drop_old_keys, ensuring efficient management of cryptographic keys.

  11. How pantalaimon works as a reverse proxy

    master

    Pantalaimon acts as an end-to-end encryption (E2EE) aware reverse proxy between a Matrix homeserver and a Matrix client.

    Key concepts:

    • Pan User: When a client logs in using standard Matrix HTTP calls, it registers itself to the daemon as a 'pan user'. The daemon maintains a dedicated sync loop for this user.
    • Multi-client support: Multiple Matrix clients can connect to the same pan user.
    • Encryption handling: The daemon transparently handles E2EE tasks on behalf of the client.
    • User Interaction: If encryption tasks require user intervention (e.g., device verification), the daemon uses a D-Bus API and sends OS notifications that the user can react to.
    • Homeservers: You can configure multiple homeservers, but each must listen on a separate port.