pax_global_header 0000666 0000000 0000000 00000000064 14177232421 0014515 g ustar 00root root 0000000 0000000 52 comment=85c7b685e5c48a43ad74876edd6d7973fa7883ed
pantalaimon-0.10.4/ 0000775 0000000 0000000 00000000000 14177232421 0014102 5 ustar 00root root 0000000 0000000 pantalaimon-0.10.4/.flake8 0000664 0000000 0000000 00000000111 14177232421 0015246 0 ustar 00root root 0000000 0000000 [flake8]
max-line-length = 80
select = C,E,F,W,B,B950
ignore = E501,W503
pantalaimon-0.10.4/.github/ 0000775 0000000 0000000 00000000000 14177232421 0015442 5 ustar 00root root 0000000 0000000 pantalaimon-0.10.4/.github/workflows/ 0000775 0000000 0000000 00000000000 14177232421 0017477 5 ustar 00root root 0000000 0000000 pantalaimon-0.10.4/.github/workflows/ci.yml 0000664 0000000 0000000 00000002401 14177232421 0020612 0 ustar 00root root 0000000 0000000 name: Build Status
on: [push, pull_request]
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
python-version: ['3.8', '3.9', '3.10']
steps:
- uses: actions/checkout@v2
- uses: actions/setup-python@v2
with:
python-version: ${{ matrix.python-version }}
- name: Install Tox and any other packages
run: |
wget https://gitlab.matrix.org/matrix-org/olm/-/archive/master/olm-master.tar.bz2
tar -xvf olm-master.tar.bz2
pushd olm-master && make && sudo make PREFIX="/usr" install && popd
rm -r olm-master
pip install tox
- name: Run Tox
run: tox -e py
coverage:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Setup Python
uses: actions/setup-python@v2
with:
python-version: "3.10"
- name: Install Tox and any other packages
run: |
wget https://gitlab.matrix.org/matrix-org/olm/-/archive/master/olm-master.tar.bz2
tar -xvf olm-master.tar.bz2
pushd olm-master && make && sudo make PREFIX="/usr" install && popd
rm -r olm-master
pip install tox
- name: Run Tox
run: tox -e coverage
pantalaimon-0.10.4/.gitignore 0000664 0000000 0000000 00000000102 14177232421 0016063 0 ustar 00root root 0000000 0000000 __pycache__
dist
pantalaimon.egg-info/
.tox
.mypy_cache
.coverage
pantalaimon-0.10.4/.isort.cfg 0000664 0000000 0000000 00000000161 14177232421 0015777 0 ustar 00root root 0000000 0000000 [settings]
multi_line_output=3
include_trailing_comma=True
force_grid_wrap=0
use_parentheses=True
line_length=88
pantalaimon-0.10.4/.travis.yml 0000664 0000000 0000000 00000001212 14177232421 0016207 0 ustar 00root root 0000000 0000000 language: python
dist: xenial
sudo: false
addons:
apt:
packages:
- libdbus-1-dev
- libgirepository1.0-dev
before_install:
- wget https://gitlab.matrix.org/matrix-org/olm/-/archive/master/olm-master.tar.bz2
- tar -xvf olm-master.tar.bz2
- pushd olm-master && make && sudo make PREFIX="/usr" install && popd
- rm -r olm-master
matrix:
include:
- python: 3.8
env: TOXENV=py38
- python: 3.9
env: TOXENV=py39
- python: 3.9
env: TOXENV=coverage
install: pip install tox-travis aioresponses
script: tox
after_success:
- bash <(curl -s https://codecov.io/bash)
pantalaimon-0.10.4/CHANGELOG.md 0000664 0000000 0000000 00000007773 14177232421 0015731 0 ustar 00root root 0000000 0000000 # Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## 0.10.4 2022-02-04
### Fixed
- [[#122]] Fix the GLib import for panctl on some distributions
- [[#120]] Don't use strip to filter Bearer from the auth header
- [[#118]] Don't use the raw path if we need to sanitize filters, fixing room
history fetching for Fractal
[#122]: https://github.com/matrix-org/pantalaimon/pull/122
[#120]: https://github.com/matrix-org/pantalaimon/pull/120
[#118]: https://github.com/matrix-org/pantalaimon/pull/118
## 0.10.3 2021-09-02
### Fixed
- [[#105]] Use the raw_path when forwarding requests, avoiding URL
decoding/encoding issues.
[#105]: https://github.com/matrix-org/pantalaimon/pull/105
## 0.10.2 2021-07-14
### Fixed
- [[#103]] Prevent E2EE downgrade on failed syncs
[#103]: https://github.com/matrix-org/pantalaimon/pull/103
## 0.10.1 2021-07-06
### Fixed
- [[#100]] Don't require the rooms dicts in the sync response
- [[#99]] Thumbnails not generating for media uploaded in unencrypted rooms
whole LRU cache when it shouldn't
[#100]: https://github.com/matrix-org/pantalaimon/pull/100
[#99]: https://github.com/matrix-org/pantalaimon/pull/99
## 0.10.0 2021-05-14
### Added
- [[#98]] Add the ability to remove old room keys
- [[#95]] Encrypt thumbnails uploaded by a client
### Fixed
- [[#96]] Split out the media cache loading logic to avoid returning the
whole LRU cache when it shouldn't
[#98]: https://github.com/matrix-org/pantalaimon/pull/98
[#96]: https://github.com/matrix-org/pantalaimon/pull/96
[#95]: https://github.com/matrix-org/pantalaimon/pull/95
## 0.9.3 2021-05-14
### Changed
- [[#73f68c7]] Bump the allowed nio version
[73f68c7]: https://github.com/matrix-org/pantalaimon/commit/73f68c76fb05037bd7fe71688ce39eb1f526a385
## 0.9.2 2021-03-10
### Changed
- [[#89]] Bump the allowed nio version
[#89]: https://github.com/matrix-org/pantalaimon/pull/89
## 0.9.1 2021-01-19
### Changed
- [[3baae08]] Bump the allowed nio version
[3baae08]: https://github.com/matrix-org/pantalaimon/commit/3baae08ac36e258632e224b655e177a765a939f3
## 0.9.0 2021-01-19
### Fixed
- [[59051c5]] Fix the notification initialization allowing the DBUS thread to
start again
### Added
- [[#79]] Support media uploads, thanks to @aspacca
[59051c5]: https://github.com/matrix-org/pantalaimon/commit/59051c530a343a6887ea0f9ccddd6f6964f6d923
[#79]: https://github.com/matrix-org/pantalaimon/pull/79
## 0.8.0 2020-09-30
### Changed
- [[#69]] If no password is provided to /login, the daemon will re-use the original login response.
[#69]: https://github.com/matrix-org/pantalaimon/pull/69
## 0.7.0 2020-09-02
### Fixed
- [[#60]] Sanitize the GET /rooms/{room_id}/messages filters as well.
- [[#62]] Store media info when decrypting instead of using a event callback.
### Changed
- [[d425e2d]] Increase the max POST size.
[#62]: https://github.com/matrix-org/pantalaimon/pull/62
[#60]: https://github.com/matrix-org/pantalaimon/pull/60
[d425e2d]: https://github.com/matrix-org/pantalaimon/commit/d425e2d188aed32c3fe87cac210c0943fd51b085
## 0.6.5 2020-07-02
### Fixed
- [[a1ce950]] Allow to send messages using a POST request since Synapse seems to
allow it.
[a1ce950]: https://github.com/matrix-org/pantalaimon/commit/a1ce95076ecd80c880028691feeced8d28cacad9
## 0.6.4 2020-06-21
### Changed
- Bump the maximal supported nio version.
## 0.6.3 2020-05-28
### Fixed
- Fix our dep requirements to avoid incompatibilities between nio and pantalaimon.
## 0.6.2 2020-05-27
### Fixed
- Don't require exact patch versions for our deps.
## 0.6.1 2020-05-12
### Fixed
- Bump the version to trigger a docker hub build with the latest nio release.
## 0.6.0 2020-05-10
### Added
- Add support for Janus 0.5.0.
- Added media endpoint handling to the /media/v1 path.
### Fixed
- Modify media events so they contain the unencrypted URL fields as well.
pantalaimon-0.10.4/Dockerfile 0000664 0000000 0000000 00000001432 14177232421 0016074 0 ustar 00root root 0000000 0000000 FROM python:3.8-slim-buster AS builder
RUN mkdir -p /app
RUN apt-get update && apt-get install -y git gcc clang cmake g++ pkg-config python3-dev wget
WORKDIR /app
RUN wget https://gitlab.matrix.org/matrix-org/olm/-/archive/master/olm-master.tar.bz2 \
&& tar -xvf olm-master.tar.bz2 \
&& cd olm-master && make && make PREFIX="/usr" install
RUN pip --no-cache-dir install --upgrade pip setuptools wheel
COPY . /app
RUN pip wheel . --wheel-dir /wheels --find-links /wheels
FROM python:3.8-slim-buster AS run
COPY --from=builder /usr/lib/libolm* /usr/lib/
COPY --from=builder /wheels /wheels
WORKDIR /app
RUN pip --no-cache-dir install --find-links /wheels --no-index pantalaimon
VOLUME /data
ENTRYPOINT ["pantalaimon"]
CMD ["-c", "/data/pantalaimon.conf", "--data-path", "/data"]
pantalaimon-0.10.4/LICENSE 0000664 0000000 0000000 00000023676 14177232421 0015125 0 ustar 00root root 0000000 0000000
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
pantalaimon-0.10.4/MANIFEST.in 0000664 0000000 0000000 00000000171 14177232421 0015637 0 ustar 00root root 0000000 0000000 include contrib/pantalaimon.service
include doc/man/pantalaimon.8
include doc/man/pantalaimon.5
include doc/man/panctl.1
pantalaimon-0.10.4/Makefile 0000664 0000000 0000000 00000000605 14177232421 0015543 0 ustar 00root root 0000000 0000000 test:
python3 -m pytest
python3 -m pytest --black pantalaimon
python3 -m pytest --flake8 pantalaimon
coverage:
python3 -m pytest --cov=pantalaimon --cov-report term-missing
typecheck:
mypy --ignore-missing-imports pantalaimon
run-local:
python -m pantalaimon.main --log-level debug --config ./contrib/pantalaimon.conf
isort:
isort -y -p pantalaimon
format:
black pantalaimon/
pantalaimon-0.10.4/README.md 0000664 0000000 0000000 00000010656 14177232421 0015371 0 ustar 00root root 0000000 0000000 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](https://gitlab.matrix.org/matrix-org/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](https://gitlab.matrix.org/matrix-org/olm/blob/master/README.md)
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 controll 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:
```bash
brew install dbus
perl -pi -e's#(EXTERNAL)##' $(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.
```bash
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
```
An example `pantalaimon.conf` for Docker is:
```conf
[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 your own user. 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](docs/man/pantalaimon.8.md).
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:
```dosini
[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](docs/man/pantalaimon.5.md) `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.
pantalaimon-0.10.4/contrib/ 0000775 0000000 0000000 00000000000 14177232421 0015542 5 ustar 00root root 0000000 0000000 pantalaimon-0.10.4/contrib/pantalaimon.conf 0000664 0000000 0000000 00000000432 14177232421 0020713 0 ustar 00root root 0000000 0000000 [Default]
LogLevel = Debug
SSL = True
Notifications = On
DebugEncryption = True
[local-matrix]
Homeserver = http://localhost:8008
ListenAddress = localhost
ListenPort = 8009
Proxy = http://localhost:8080
SSL = False
IgnoreVerification = False
UseKeyring = True
DropOldKeys = False
pantalaimon-0.10.4/contrib/pantalaimon.service 0000664 0000000 0000000 00000000205 14177232421 0021424 0 ustar 00root root 0000000 0000000 [Unit]
Description=Pantalaimon E2E Matrix reverse proxy
[Service]
ExecStart=/usr/bin/pantalaimon
[Install]
WantedBy=default.target
pantalaimon-0.10.4/docs/ 0000775 0000000 0000000 00000000000 14177232421 0015032 5 ustar 00root root 0000000 0000000 pantalaimon-0.10.4/docs/man/ 0000775 0000000 0000000 00000000000 14177232421 0015605 5 ustar 00root root 0000000 0000000 pantalaimon-0.10.4/docs/man/panctl.1 0000664 0000000 0000000 00000006243 14177232421 0017155 0 ustar 00root root 0000000 0000000 .Dd May 23, 2019
.Dt PANCTL 1
.Os
.\" ---------------------------------------------------------------------------
.Sh NAME
.Nm panctl
.Nd Control the Matrix reverse proxy daemon pantalaimon.
.\" ---------------------------------------------------------------------------
.Sh DESCRIPTION
.Nm
is a small utility to control and introspect the state of pantalaimon.
.Pp
.Ss Commands
The commands accepted by
.Nm
are as follows:
.Bl -tag -width 3n
.It Cm list-servers
List the configured homeservers and pan users on each homeserver.
.It Cm list-devices Ar pan-user Ar user-id
List the devices of a user that are known to the
.Ar pan-user .
.It Cm start-verification Ar pan-user Ar user-id
Start an interactive key verification between the given pan-user and user.
.It Cm accept-verification Ar pan-user Ar user-id
Accept an interactive key verification that the given user has started with our
given pan-user.
.It Cm cancel-verification Ar pan-user Ar user-id
Cancel an interactive key verification between the given pan-user and user.
.It Cm confirm-verification Ar pan-user Ar user-id
Confirm that the short authentication string of the interactive key verification
with the given pan-user and user is matching.
.It Cm verify-device Ar pan-user Ar user-id Ar device-id
Manually mark the given device as verified. The device will be marked as verified
only for the given pan-user.
.It Cm unverify-device Ar pan-user Ar user-id Ar device-id
Mark a previously verified device of the given user as unverified.
.It Cm blacklist-device Ar pan-user Ar user-id Ar device-id
Manually mark the given device of the given user as blacklisted.
.It Cm unblacklist-device Ar pan-user Ar user-id Ar device-id
Mark a previously blacklisted device of the given user as unblacklisted.
.It Cm send-anyways Ar pan-user Ar room-id
If a encrypted room contains unverified devices and a connected Matrix client
tries to send an message to such a room
.Nm pantalaimon
will send a notification that the room contains unverified users. Using this
command the user can choose to mark all unverified devices as ignored. Ignored
devices will receive encryption keys but will be left marked as unverified.
The message will be sent away after all devices are marked as ignored.
.It Cm cancel-sending Ar pan-user Ar room-id
In contrast to the
.Cm send-anyways
command this command cancels the sending of a message to an encrypted room with
unverified devices and gives the user the oportunity to verify or blacklist
devices as they see fit.
.It Cm import-keys Ar pan-user Ar file Ar passphrase
Import end-to-end encryption keys from the given file for the given pan-user.
.It Cm export-keys Ar pan-user Ar file Ar passphrase
Export end-to-end encryption keys to the given file for the given pan-user. The
provided passphrase is used to encrypt the file containing the keys.
.El
.\" ---------------------------------------------------------------------------
.Sh EXIT STATUS
.Ex -std
.\" ---------------------------------------------------------------------------
.Sh SEE ALSO
.Xr pantalaimon 8
.Xr pantalaimon 5
.\" ---------------------------------------------------------------------------
.Sh AUTHORS
.Nm
was written by
.An Damir Jelić Aq Mt poljar@termina.org.uk .
pantalaimon-0.10.4/docs/man/panctl.md 0000664 0000000 0000000 00000005645 14177232421 0017422 0 ustar 00root root 0000000 0000000 PANCTL(1) - General Commands Manual
# NAME
**panctl** - Control the Matrix reverse proxy daemon pantalaimon.
# DESCRIPTION
**panctl**
is a small utility to control and introspect the state of pantalaimon.
## Commands
The commands accepted by
**panctl**
are as follows:
**list-servers**
> List the configured homeservers and pan users on each homeserver.
**list-devices** *pan-user* *user-id*
> List the devices of a user that are known to the
> *pan-user*.
**start-verification** *pan-user* *user-id*
> Start an interactive key verification between the given pan-user and user.
**accept-verification** *pan-user* *user-id*
> Accept an interactive key verification that the given user has started with our
> given pan-user.
**cancel-verification** *pan-user* *user-id*
> Cancel an interactive key verification between the given pan-user and user.
**confirm-verification** *pan-user* *user-id*
> Confirm that the short authentication string of the interactive key verification
> with the given pan-user and user is matching.
**verify-device** *pan-user* *user-id* *device-id*
> Manually mark the given device as verified. The device will be marked as verified
> only for the given pan-user.
**unverify-device** *pan-user* *user-id* *device-id*
> Mark a previously verified device of the given user as unverified.
**blacklist-device** *pan-user* *user-id* *device-id*
> Manually mark the given device of the given user as blacklisted.
**unblacklist-device** *pan-user* *user-id* *device-id*
> Mark a previously blacklisted device of the given user as unblacklisted.
**send-anyways** *pan-user* *room-id*
> If a encrypted room contains unverified devices and a connected Matrix client
> tries to send an message to such a room
> **pantalaimon**
> will send a notification that the room contains unverified users. Using this
> command the user can choose to mark all unverified devices as ignored. Ignored
> devices will receive encryption keys but will be left marked as unverified.
> The message will be sent away after all devices are marked as ignored.
**cancel-sending** *pan-user* *room-id*
> In contrast to the
> **send-anyways**
> command this command cancels the sending of a message to an encrypted room with
> unverified devices and gives the user the oportunity to verify or blacklist
> devices as they see fit.
**import-keys** *pan-user* *file* *passphrase*
> Import end-to-end encryption keys from the given file for the given pan-user.
**export-keys** *pan-user* *file* *passphrase*
> Export end-to-end encryption keys to the given file for the given pan-user. The
> provided passphrase is used to encrypt the file containing the keys.
# EXIT STATUS
The **panctl** utility exits 0 on success, and >0 if an error occurs.
# SEE ALSO
pantalaimon(8)
pantalaimon(5)
# AUTHORS
**panctl**
was written by
Damir Jelić <[poljar@termina.org.uk](mailto:poljar@termina.org.uk)>.
Linux 5.1.3-arch2-1-ARCH - May 23, 2019
pantalaimon-0.10.4/docs/man/pantalaimon.5 0000664 0000000 0000000 00000014124 14177232421 0020200 0 ustar 00root root 0000000 0000000 .Dd May 08, 2019
.Dt PANTALAIMON.CONF 5
.Os
.\" ---------------------------------------------------------------------------
.Sh NAME
.Nm pantalaimon.conf
.Nd pantalaimon configuration file
.\" ---------------------------------------------------------------------------
.Sh DESCRIPTION
.Xr pantalaimon 1 reads configuration data in the INI file format.
The configuration file is used to configure
.Nm pantalaimon
homeservers.
.Pp
The sections inside the configuration file represent a pantalaimon proxy
instance with the section name enclosed in square brackets representing an user
chosen instance name.
.Pp
The following keys are required in the proxy instance sections:
.Bl -tag -width 3n
.It Cm Homeserver
The URI of the homeserver that the pantalaimon proxy should forward requests to,
without the matrix API path but including the http(s) schema.
.El
.Pp
The following keys are optional in the proxy instance sections:
.Bl -tag -width 3n
.It Cm ListenAddress
The address where the daemon will listen to client connections for this
homeserver. Defaults to "localhost".
.It Cm ListenPort
The port where the daemon will listen to client connections for this
homeserver. Note that the listen address/port combination needs to be unique
between different homeservers. Defaults to "8009".
.It Cm Proxy
An URI of a HTTP proxy that the daemon should use when making requests to the
homeserver.
.Nm pantalaimon
only supports HTTP proxies. The default is to make a direct connection to the
homeserver.
.It Cm SSL
A boolean that decides if SSL verification should be enabled for outgoing
connections to the homeserver. Defaults to "True".
.It Cm IgnoreVerification
A boolean that decides if device verification should be enabled. If this is True
devices will be marked as ignored automatically and encryption keys will be
shared with them, if this is False the user needs to verify, blacklist or ignore
devices manually before messages can be sent to a room. Defaults to "False".
.It Cm UseKeyring
This option configures if a proxy instance should use the OS keyring to store
its own access tokens. The access tokens are required for the daemon to resume
operation. If this is set to "No", access tokens are stored in the pantalaimon
database in plaintext. Defaults to "Yes".
.It Cm DropOldKeys
This option configures if a proxy instance should only keep the latest version
of a room key from a certain user around. This effectively means that only newly
incoming messages will be decryptable, the proxy will be unable to decrypt the
room history. Defaults to "No".
.It Cm SearchRequests
This option configures if the proxy should make additional HTTP requests to the
server when clients use the search API endpoint. Some data that is required to
fill out a complete search response is only available on the Homeserver (e.g.
start/end tokens for the event context or room state at a particular point in
time).
If this option is set to "On"
.Nm pantalaimon
will make additional HTTP requests to fetch the unavailable data from the
Homeserver, note that this will make the search much slower. If this is set to
"Off"
.Nm pantalaimon
will not make any additional HTTP requests and will leave some data fields in
the search response empty. Defaults to "Off".
.It Cm IndexEncryptedOnly
A configuration option to decide if
.Nm pantalaimon
should fetch the history for
unencrytped rooms as well as for encrypted ones. If True, only the history for
encrypted rooms is fetched and indexed. Search requests for non-encrypted
rooms are forwarded to the Homeserver. Defaults to "True".
.It Cm IndexingBatchSize
The number of messages that should be requested from the Homeserver when we
fetch and index messages from the room history. Defaults to 100.
.It Cm HistoryFetchDelay
The amount of time to wait between room message history requests to the
Homeserver in ms. Defaults to 3000.
.El
.Pp
Aditional to the homeserver section a special section with the name
.Cm Default
can be used to configure the following values for all homeservers:
.Cm ListenAddress ,
.Cm ListenPort ,
.Cm Proxy ,
.Cm SSL
.Cm IgnoreVerification
.Cm UseKeyring
.Pp
The
.Cm Default
section has the following keys that globally change the behaviour of the daemon:
.Bl -tag -width 3n
.It Cm LogLevel
Set the log level of the daemon, can be one of
.Ar error ,
.Ar warning ,
.Ar info ,
.Ar debug .
Defaults to
.Ar warning .
.It Cm Notifications
The daemon sends out notifications for some actions that require users to
interfere (unverified devices are in a room, interactive key verification
events), this option enables or disables OS notifications. Can be one of
.Ar On ,
.Ar Off .
Defaults to
.Ar On .
.El
.\" ---------------------------------------------------------------------------
.Sh FILES
.Nm pantalaimon
supports the XDG Base Directory Specification, the default locations can be
overridden using appropriate environment variables.
.Pp
.Bl -tag -width 34 -compact
.It Pa ~/.config/pantalaimon/pantalaimon.conf
Default location of the configuration file.
.El
.\" ---------------------------------------------------------------------------
.Sh EXAMPLES
The following example shows a configured pantalaimon proxy with the name
.Em Clocktown ,
the homeserver URL is set to
.Em https://localhost:8448 ,
the pantalaimon proxy is listening for client connections on the address
.Em localhost ,
and port
.Em 8009 .
The pantalaimon proxy is making connections to the homeserver through the proxy
.Em http://localhost:8009 ,
finally, SSL verification is disabled.
.Pp
Additionally to the
.Em Clocktown
section the
.Em Default
section is also listed and the default value for SSL verification is set to
True, OS notifications are enabled and the debug level is set to
.Em Debug .
.Bd -literal -offset indent
[Default]
LogLevel = Debug
SSL = True
Notifications = On
[Clocktown]
Homeserver = https://localhost:8448
ListenAddress = localhost
ListenPort = 8009
Proxy = http://localhost:8080
SSL = False
.Ed
.\" ---------------------------------------------------------------------------
.Sh SEE ALSO
.Xr pantalaimon 8
.\" ---------------------------------------------------------------------------
.Sh AUTHORS
.Nm
was written by
.An Damir Jelić Aq Mt poljar@termina.org.uk .
pantalaimon-0.10.4/docs/man/pantalaimon.5.md 0000664 0000000 0000000 00000010451 14177232421 0020576 0 ustar 00root root 0000000 0000000 PANTALAIMON.CONF(5) - File Formats Manual
# NAME
**pantalaimon.conf** - pantalaimon configuration file
# DESCRIPTION
pantalaimon(1) reads configuration data in the INI file format.
The configuration file is used to configure
**pantalaimon**
homeservers.
The sections inside the configuration file represent a pantalaimon proxy
instance with the section name enclosed in square brackets representing an user
chosen instance name.
The following keys are required in the proxy instance sections:
**Homeserver**
> The URI of the homeserver that the pantalaimon proxy should forward requests to,
> without the matrix API path but including the http(s) schema.
The following keys are optional in the proxy instance sections:
**ListenAddress**
> The address where the daemon will listen to client connections for this
> homeserver. Defaults to "localhost".
**ListenPort**
> The port where the daemon will listen to client connections for this
> homeserver. Note that the listen address/port combination needs to be unique
> between different homeservers. Defaults to "8009".
**Proxy**
> An URI of a HTTP proxy that the daemon should use when making requests to the
> homeserver.
> **pantalaimon**
> only supports HTTP proxies. The default is to make a direct connection to the
> homeserver.
**SSL**
> A boolean that decides if SSL verification should be enabled for outgoing
> connections to the homeserver. Defaults to "True".
**IgnoreVerification**
> A boolean that decides if device verification should be enabled. If this is True
> devices will be marked as ignored automatically and encryption keys will be
> shared with them, if this is False the user needs to verify, blacklist or ignore
> devices manually before messages can be sent to a room. Defaults to "False".
**UseKeyring**
> This option configures if a proxy instance should use the OS keyring to store
> its own access tokens. The access tokens are required for the daemon to resume
> operation. If this is set to "No", access tokens are stored in the pantalaimon
> database in plaintext. Defaults to "Yes".
**DropOldKeys**
> This option configures if a proxy instance should only keep the latest version
> of a room key from a certain user around. This effectively means that only newly
> incoming messages will be decryptable, the proxy will be unable to decrypt the
> room history. Defaults to "No".
Aditional to the homeserver section a special section with the name
**Default**
can be used to configure the following values for all homeservers:
**ListenAddress**,
**ListenPort**,
**Proxy**,
**SSL**
**IgnoreVerification**
**UseKeyring**
The
**Default**
section has the following keys that globally change the behaviour of the daemon:
**LogLevel**
> Set the log level of the daemon, can be one of
> *error*,
> *warning*,
> *info*,
> *debug*.
> Defaults to
> *warning*.
**Notifications**
> The daemon sends out notifications for some actions that require users to
> interfere (unverified devices are in a room, interactive key verification
> events), this option enables or disables OS notifications. Can be one of
> *On*,
> *Off*.
> Defaults to
> *On*.
# FILES
**pantalaimon**
supports the XDG Base Directory Specification, the default locations can be
overridden using appropriate environment variables.
*~/.config/pantalaimon/pantalaimon.conf*
> Default location of the configuration file.
# EXAMPLES
The following example shows a configured pantalaimon proxy with the name
*Clocktown*,
the homeserver URL is set to
*https://localhost:8448*,
the pantalaimon proxy is listening for client connections on the address
*localhost*,
and port
*8009*.
The pantalaimon proxy is making connections to the homeserver through the proxy
*http://localhost:8009*,
finally, SSL verification is disabled.
Additionally to the
*Clocktown*
section the
*Default*
section is also listed and the default value for SSL verification is set to
True, OS notifications are enabled and the debug level is set to
*Debug*.
[Default]
LogLevel = Debug
SSL = True
Notifications = On
[Clocktown]
Homeserver = https://localhost:8448
ListenAddress = localhost
ListenPort = 8009
Proxy = http://localhost:8080
SSL = False
# SEE ALSO
pantalaimon(8)
# AUTHORS
**pantalaimon.conf**
was written by
Damir Jelić <[poljar@termina.org.uk](mailto:poljar@termina.org.uk)>.
Linux 5.11.16-arch1-1 - May 8, 2019
pantalaimon-0.10.4/docs/man/pantalaimon.8 0000664 0000000 0000000 00000006357 14177232421 0020214 0 ustar 00root root 0000000 0000000 .Dd Oct 18, 2019
.Dt PANTALAIMON 8
.Os
.\" ---------------------------------------------------------------------------
.Sh NAME
.Nm pantalaimon
.Nd End-to-end encryption aware Matrix reverse proxy daemon.
.\" ---------------------------------------------------------------------------
.Sh SYNOPSIS
.Nm
.Op Fl c Ar config
.Op Fl -log-level Ar level
.Op Fl -data-path Ar path
.Op Fl -version
.Op Fl -help
.\" ---------------------------------------------------------------------------
.Sh DESCRIPTION
.Nm
is a daemon that acts as a reverse proxy between a Matrix homeserver and a
Matrix client. The daemon transparently handles end-to-end encryption tasks on
behalf of the client.
.Pp
.Nm
is supposed to run as your own user and listen to connections on a
non-privileged port. A client needs to log in using the standard Matrix HTTP
calls to register itself to the daemon, such a registered user is called a pan
user and will have it's own sync loop to keep up with the server. Multiple matrix
clients can connect and use the same pan user.
.Pp
If user interaction is required
.Nm
will send out OS notifications which the user can react to.
.Nm
also provides a D-Bus API that is used for encryption related tasks that
require user interference (e.g. device verification).
.Pp
.Nm
requires a homeserver to be configured. Multiple homeservers can be configured,
each configured homeserver needs to listen on a separate port. Each homeserver
can handle end-to-end encryption for multiple users. The configuration file
format is specified in
.Xr pantalaimon 5 ,
the default location of the configuration file can be found in the
.Sx FILES
section.
.\" ---------------------------------------------------------------------------
.Ss Options
The command line flags to change the behaviour of
.Nm
are as follows:
.Bl -tag -width Ds
.It Fl c , Fl -config Ar file
Use the supplied
.Ar file
as the configuration file instead of the default one.
.It Fl -log-level Ar level
Set the log level of the daemon, can be one of
.Ar error ,
.Ar warning ,
.Ar info ,
.Ar debug .
Defaults to
.Ar warning .
.It Fl -data-path Ar path
Set the directory for the pantalaimon database. This config option takes
precedence over the XDG environment variables.
.It Fl -version
Display the version number and exit.
.It Fl -help
Display the help and exit.
.El
.\" ---------------------------------------------------------------------------
.Sh FILES
.Nm
supports the XDG Base Directory Specification, the default locations can be
overridden using appropriate environment variables.
.Pp
.Bl -tag -width DS -compact
.It Pa ~/.config/pantalaimon/pantalaimon.conf
Default location of the configuration file.
The format of the configuration file is described in
.Xr pantalaimon 5 .
.Pp
.It Pa ~/.local/share/pantalaimon/pan.db
Default location of the pantalaimon database.
This file is used to store a sqlite database holding daemon state and encryption
keys.
.El
.\" ---------------------------------------------------------------------------
.Sh EXIT STATUS
.Ex -std
.\" ---------------------------------------------------------------------------
.Sh SEE ALSO
.Xr panctl 1
.Xr pantalaimon 5
.\" ---------------------------------------------------------------------------
.Sh AUTHORS
.Nm
was written by
.An Damir Jelić Aq Mt poljar@termina.org.uk .
pantalaimon-0.10.4/docs/man/pantalaimon.8.md 0000664 0000000 0000000 00000005501 14177232421 0020601 0 ustar 00root root 0000000 0000000 PANTALAIMON(8) - System Manager's Manual
# NAME
**pantalaimon** - End-to-end encryption aware Matrix reverse proxy daemon.
# SYNOPSIS
**pantalaimon**
\[**-c** *config*]
\[**--log-level** *level*]
\[**--data-path** *path*]
\[**--version**]
\[**--help**]
# DESCRIPTION
**pantalaimon**
is a daemon that acts as a reverse proxy between a Matrix homeserver and a
Matrix client. The daemon transparently handles end-to-end encryption tasks on
behalf of the client.
**pantalaimon**
is supposed to run as your own user and listen to connections on a
non-privileged port. A client needs to log in using the standard Matrix HTTP
calls to register itself to the daemon, such a registered user is called a pan
user and will have it's own sync loop to keep up with the server. Multiple matrix
clients can connect and use the same pan user.
If user interaction is required
**pantalaimon**
will send out OS notifications which the user can react to.
**pantalaimon**
also provides a D-Bus API that is used for encryption related tasks that
require user interference (e.g. device verification).
**pantalaimon**
requires a homeserver to be configured. Multiple homeservers can be configured,
each configured homeserver needs to listen on a separate port. Each homeserver
can handle end-to-end encryption for multiple users. The configuration file
format is specified in
pantalaimon(5),
the default location of the configuration file can be found in the
*FILES*
section.
## Options
The command line flags to change the behaviour of
**pantalaimon**
are as follows:
**-c**, **--config** *file*
> Use the supplied
> *file*
> as the configuration file instead of the default one.
**--log-level** *level*
> Set the log level of the daemon, can be one of
> *error*,
> *warning*,
> *info*,
> *debug*.
> Defaults to
> *warning*.
**--data-path** *path*
> Set the directory for the pantalaimon database. This config option takes
> precedence over the XDG environment variables.
**--version**
> Display the version number and exit.
**--help**
> Display the help and exit.
# FILES
**pantalaimon**
supports the XDG Base Directory Specification, the default locations can be
overridden using appropriate environment variables.
*~/.config/pantalaimon/pantalaimon.conf*
> Default location of the configuration file.
> The format of the configuration file is described in
> pantalaimon(5).
*~/.local/share/pantalaimon/pan.db*
> Default location of the pantalaimon database.
> This file is used to store a sqlite database holding daemon state and encryption
> keys.
# EXIT STATUS
The **pantalaimon** utility exits 0 on success, and >0 if an error occurs.
# SEE ALSO
panctl(1)
pantalaimon(5)
# AUTHORS
**pantalaimon**
was written by
Damir Jelić <[poljar@termina.org.uk](mailto:poljar@termina.org.uk)>.
Linux 5.3.5-arch1-1-ARCH - October 18, 2019
pantalaimon-0.10.4/docs/pan.gif 0000664 0000000 0000000 00011510756 14177232421 0016317 0 ustar 00root root 0000000 0000000 GIF89a
r !$ "}#$%#$g$h%Qv%f%g%i%@&.9&G)''('5A())+)08))B**,++,+,./01258446786o78:7;;>?AADBCDDEEGHHJKLK}MRSTUTlr[\]]_cabdaj{cbcdbdeXWeefhhiiϗjvlʦnoppͪr}rstuvtxPxwwxxxxέyyzz{||{}ϯ~xvӶ48_ϘkaĠE[h|?EʴɶUHQ0žDŽYΆ-xu{!w xyzxx
V;j(KiuNG&wS_JU!NETSCAPE2.0d ! , CərG*LpÆJHqŊ/jqǎ ?Irɒ(OLr˖0_ʌIs͚8osO GԱ+YgՒAePOQBI*OOB:Jk֮SWa[VmZRE\o%+nߵ~LX,ݿyE<8qmEٰ^ʘS&K-Yv.M @RVj_ˎMmطg箍nN|qLJ'/r̟KN}uקgvܿO~yǧ/zˏO}AҌٳdN=SO=,O>((ha aa^x
F
jؠ(X 8&ʈ"+~;c
b=d4ch#CH"4dKNid@ި[ A&FKhTsZOxz~
蠂J衆&袊6(A3:S:S|iƓ:jꪪZꫬj
+Z뮚z+*쯥,l
,촵+V[>k2?K7.|+K,'L+lod)S1`ZN:︓q#3șL2*|r/4,g5Ϭ2+9E"2JG7?Dؒ8[l1s{m/}?=]_o~[mת:ٚ-Jg˨NuJZؽvE6B7G-*x+Eou@Eɩڌ!u"dk[ uk/mmm0&!4cvpG`LV%1\`ϕd&=bj ,D| [v81ew<1@+c"H>}K@4El5.Q5d:,[/uh^dͷ