From 2c6adfe335ed370da32b757fb02eecb3e5ef4012 Mon Sep 17 00:00:00 2001 From: Onnayaku Date: Tue, 1 Nov 2022 21:35:48 +0100 Subject: [PATCH] Minor formatting corrections and whitespace character fixes in adv-filt.md testing.md INSTALL.md and README.md --- INSTALL.md | 19 ++++++++++++++++++- README.md | 6 ++++-- doc/adv-filt.md | 16 ++++++++-------- doc/testing.md | 22 +++++++++++----------- 4 files changed, 41 insertions(+), 22 deletions(-) diff --git a/INSTALL.md b/INSTALL.md index cc62f20..6a65ec1 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,11 +1,14 @@ # Installation instructions + ## Content + - General information - Install GPG-Mailgate - Install GPG-Mailgate-Web - Install Register-handler ## General information + GPG-Mailgate is divided in 3 main parts: GPG-Mailgate itself, GPG-Mailgate-Web and Register-handler. Some parts of the GPG-Mailgate project depend on other parts of the project. You will find information about these dependencies at the beginning of every installation part. These instructions show you how to set up GPG-Mailgate in an easy way. If you are a more advanced user, feel free to experiment with the settings. For these instructions a home directory for the user `nobody` is set. Sadly this is an odd workaround but no better solution was found. @@ -13,7 +16,9 @@ These instructions show you how to set up GPG-Mailgate in an easy way. If you ar These instructions are based on an installation on an Ubuntu 14.04 LTS virtual machine. For other Linux distributions and other versions these instructions might need to be adapted to your distribution (e.g. installation of packages and used directories). ## Install GPG-Mailgate + ### Requirements + - Python 3.x is already installed - Postfix is already installed and configured. It is recommended that you have already tested your configuration so we can exclude this as a main cause of problems - GnuPG is already installed and configured @@ -101,23 +106,29 @@ Please also test your installation before using it. GPG-Mailgate is also able to handle S/MIME certificates for encrypting mails. However, it is best to use it in combination with Register-Handler described later to add new certificates. If you try to add them manually it might fail. The certificates are stored in `/var/gpgmailgate/smime` in PKCS7 format and are named like `User@example.com` (the user part is case sensitive, the domain part should be in lower case). -####Additional settings +#### Additional settings + Most mail servers do not handle mail addresses case sensitive. If you know that all your recipient mail servers do not care about case sensitivity then you can set `mail_case_insensitive` in the settings to `yes` so looking up PGP keys or S/MIME certificates does also happen case insensitive. If your recipients have problems to decrypt mails encrypted by GPG-Mailgate they might use a piece of software that does not support PGP/MIME encrypted mails. You can tell GPG-Mailgate to use the legacy PGP/INLINE format by adding the recipient to the `pgp_style` map in the following format: `User@example.com=inline` ### Mail decryption + GPG-Mailgate does not only feature encryption of mails but also decryption of PGP encrypted mails. + #### Important notice + **Read carefully before setting up and using this functionality!** With this functionality you could use GPG-Mailgate to decrypt incoming PGP encrypted mails (it is also capable of decrypting outgoing mails if the necessary key is present). To use this, you need to store your private keys on the server. This means that anyone who is able to obtain admin rights on the server is able to get the private keys stored on the server and is able to decrypt any mail encrypted with the corresponding public key. **If the server gets compromised in any kind and the attacker may have gained access to the server's file system, the keys have to be regarded as compromised as well!** If this happens you have to revoke your keys, notify everyone who has your public key (key servers as well) not to use this key any longer. You also need to create a new key pair for encrypted communication. #### Limitations + There are two main types of PGP encryption: PGP/MIME and PGP/INLINE. PGP/MIME is standardized while PGP/INLINE isn't completely clear standardized (even though some people claim so). Decrypting PGP/MIME encrypted mails works in most cases while decrypting PGP/INLINE encrypted mails may fail more often. The reason is that most clients are implementing PGP/INLINE in their own way. GPG-Mailgate is able to decrypt mails which are encrypted PGP/INLINE by GPG-Mailgate on the sender's side. Furthermore it should be able to decrypt PGP/INLINE encrypted mails encrypted by Enigmail. For PGP/INLINE the mail's structure may not be preserved due to how PGP/INLINE is implemented on most clients. If you receive a PGP/INLINE encrypted mail that could not be decrypted by GPG-Mailgate you may ask the sender to use PGP/MIME instead. Furthermore file types might get lost when using PGP/INLINE. Due to this limitations decrypting PGP/INLINE encrypted mails is disabled by default. If you want to take the risk you can set `no_inline_dec` to `no` in the `[default]` section. You have been warned. #### Setting up decryption + You need the recipient's private key for whom you want to decrypt mails. Only unprotected keys are supported. Keys protected by a passphrase could not be used. To add the private key, use the following command: `sudo -u nobody /usr/bin/gpg --homedir=/var/gpgmailgate/.gnupg --import /some/private.key` From now on PGP encrypted mails will be decrypted for the recipients for whom the keys are imported. @@ -126,13 +137,16 @@ You also can remove a private key by using the following command. Replace `user@ `sudo -u nobody /usr/bin/gpg --homedir=/var/gpgmailgate/.gnupg --delete-secret-keys user@example.com` ## Install GPG-Mailgate-Web + ### Requirements + - A webserver is installed and reachable - The webserver is able to handle PHP scripts - MySQL is installed - Python 3.x is already installed ### Installation + All files you need can be found in the [gpg-mailgate-web](gpg-mailgate-web/) directory. 1. Install the Python-mysqldb and Python-markdown modules: @@ -177,10 +191,13 @@ chmod u+x /usr/local/bin/gpgmw-cron.py 11. Test your installation. ### GPG-Mailgate-Web as keyserver + GPG-Mailgate-Web can also be used as a keyserver. For more information have a look at GPG-Mailgate-Web's [readme](gpg-mailgate-web/README). ## Install Register-handler + ### Requirements + - Already set up and working GPG-Mailgate-Web. It should be reachable from the machine that will run register-handler - Postfix is already installed and configured. It is recommended that you have already tested your configuration so we can exclude this as a main cause of problems. Your Postfix configuration should also support aliases diff --git a/README.md b/README.md index 43ef043..4935216 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@ # GPG Lacre Project GPG Lacre is a fork and continuation of original work of gpg-mailgate project: -[gpg-mailgate](https://github.com/TheGreatGooo/gpg-mailgate). It is still +[gpg-mailgate](https://github.com/TheGreatGooo/gpg-mailgate). It is still actively developed and should be considered as beta -- with all APIs and -internals being subject to change. Please only use this software if you know +internals being subject to change. Please only use this software if you know GnuPG well. @@ -30,11 +30,13 @@ Made possible thanks to:
![](https://nlnet.nl/logo/banner.png) --- + For installation instructions, please refer to the included **INSTALL** file. --- # Features + - Correctly displays attachments and general email content; currently will only display first part of multipart messages - Public keys are stored in a dedicated gpg-home-directory - Encrypts both matching incoming and outgoing mail (this means gpg-mailgate can be used to encrypt outgoing mail for software that doesn't support PGP or S/MIME) diff --git a/doc/adv-filt.md b/doc/adv-filt.md index c7c76fb..2332ec5 100644 --- a/doc/adv-filt.md +++ b/doc/adv-filt.md @@ -3,9 +3,9 @@ ## Postfix Filters There are two types of Postfix mail filters: Simple Filters and Advanced -Filters. Simple Filters are executed for each incoming email as a new -process, which may turn out to be expensive in terms of resources. Advanced -Filters work as a mail-processing proxies. +Filters. Simple Filters are executed for each incoming email as a new +process, which may turn out to be expensive in terms of resources. Advanced +Filters work as a mail-processing proxies. For detailed documentation, see [FILTER README](https://www.postfix.org/FILTER_README.html). @@ -18,17 +18,17 @@ Just use the following command to install dependencies: ## Configuration Lacre Advanced Filter, also known as daemon, is configured in the `[daemon]` -section of configuration file. Two obligatory parameters to be defined there +section of configuration file. Two obligatory parameters to be defined there are: - * `host` -- IP address or a host name; + * `host` -- IP address or a host name; * `port` -- TCP port Lacre should listen on. The other very important section is `[relay]`, which by default uses Simple -Filter destination. It has to be adjusted for Advanced Filter to work, +Filter destination. It has to be adjusted for Advanced Filter to work, setting port to `10026`. -Command to spawn a Lacre daemon process is: +Command to spawn a Lacre daemon process is: GPG_MAILGATE_CONFIG=/etc/gpg-mailgate.conf PYTHONPATH=... python -m lacre.daemon @@ -36,6 +36,6 @@ Two environment variables used here are: * `GPG_MAILGATE_CONFIG` (not mandatory) -- path to Lacre configuration, unless it's kept in default location (`/etc/gpg-maillgate.conf`). - * `PYTHONPATH` (not mandatory) -- location of Lacre modules. You can place + * `PYTHONPATH` (not mandatory) -- location of Lacre modules. You can place them below your Python's `site-packages` to be reachable by any other Python software. diff --git a/doc/testing.md b/doc/testing.md index affae9e..545fb00 100644 --- a/doc/testing.md +++ b/doc/testing.md @@ -1,7 +1,7 @@ # Testing First tests have been set up to cover GPG Mailgate with at least basic test -that would be easy to run. The tests are called "end-to-end", meaning that we +that would be easy to run. The tests are called "end-to-end", meaning that we feed some input to GPG Mailgate and inspect the output. ## Running tests @@ -10,39 +10,39 @@ To run tests, use command `make test`. There are 4 types of tests: - * `make e2etest` -- they cover a complete Lacre flow, from feeding it with + * `make e2etest` -- they cover a complete Lacre flow, from feeding it with an email to accepting its encrypted form; * `make daemontest` -- similar to the original `e2etest` goal, but tests the behaviour of the Lacre Daemon, i.e. key part of the Advanced Content Filter. * `make unittest` -- just small tests of small units of code; - * `make crontest` -- execute cron job with a SQLite database. + * `make crontest` -- execute cron job with a SQLite database. E2E tests (`make e2etest`) should produce some helpful logs, so inspect contents of `test/logs` directory if something goes wrong. If your system's Python binary isn't found in your `$PATH` or you want to use -a specific binary, use make's macro overriding: `make test +a specific binary, use make's macro overriding: `make test PYTHON=/path/to/python`. ## Key building blocks - *Test Script* (`test/e2e_test.py`) and *Daemon Test Script* - (`test/daemon_test.py`) that orchestrate the other components. They perform - test cases described in the *Test Configuration*. They spawn *Test Mail + (`test/daemon_test.py`) that orchestrate the other components. They perform + test cases described in the *Test Configuration*. They spawn *Test Mail Relay* and *GPG Mailgate* in appropriate order. -- *Test Mail Relay* (`test/relay.py`), a simplistic mail daemon that only - supports the happy path. It accepts a mail message and prints it to +- *Test Mail Relay* (`test/relay.py`), a simplistic mail daemon that only + supports the happy path. It accepts a mail message and prints it to stdandard output. - *Test Configuration* (`test/e2e.ini`) specifies test cases: their input, - expected results and helpful documentation. It also specifies the port that + expected results and helpful documentation. It also specifies the port that the *Test Mail Relay* should listen on. ## Limitations Currently tests only check if the message has been encrypted, without -verifying that the correct key has been used. That's because we don't know -(yet) how to have a reproducible encrypted message. Option +verifying that the correct key has been used. That's because we don't know +(yet) how to have a reproducible encrypted message. Option `--faked-system-time` wasn't enough to produce identical output. ## Troubleshooting