pEp-mail-tool

This command-line tool allows existing email applications to use p≡p (see https://pep.foundation/ ) with few or no changes.

pEp-mail-tool is sort of a p≡p adapter for Unix, communicating as it does using standard input, standard output, the command line, Unix shells, sockets.

pEp-mail-tool is a single Python script implementing:

• standard mail servers for an ordinary MUAs to connect to:
  • a local SMTP server (via aiosmtpd, in-process), accepting unencrypted messages to be delivered;
  • a local IMAP server (via dovecot, in the recommended configuration automatically handled by pEp-mail-tool as a subprocess), again serving unencrypted messages.
• a (local) RPC server, handling requests from the RPC client;
• an RPC client which works by performing requests to the local RPC server;
• communication with incoming and outgoing “mail servers”, performing encryption and decryption automatically and invisibly. In this extended sense a mailserver may be:
  • a remote SMTP server (outgoing only)
  • a remote POP server (incoming only)
  • a remote IMAP server
  • a local mbox file
  • a local Maildir directory
• back up of incoming and/or outgoing messages, typically to local mbox or Maildir boxes, in encrypted and/or unencrypted format.

The local SMTP and IMAP servers are meant for an MUA to directly connect to, with a trivial MUA-side configuration. Since they serve unencrypted message a standard email client will just work, even without knowing anything about pEp.

When run from the command line pEp-mail-tool operates as an RPC client, performing operations such as showing trustwords, presenting the rating of an outgoing message, or key reset. It is also designed to be used in scripts, since it can handle outgoing messages (unencrypted, to encrypt and send out) or incoming messages (possibly encrypted, to decrypt and receive) provided by the user via the process standard input.

pEp-mail-tool as an RPC client is particularly easy to use and is designed to be convenient both from the command line and as as a subprocess helper called from interactive MUAs. The RPC client/server organisation, with the server providing a thread pool with p≡p sessions initialised in advance, allows the typical response time to be quite fast.

This repository contains the pEp-mail-tool utility and addons for MUAs using it; at the time or writing the following MUAs are supported:

• Gnus (https://gnus.org ), running on top of GNU Emacs (https://www.gnu.org/software/emacs ). Addon by Luca Saiu.

Configuration examples

See the directory configuration-examples/ for sample configuration files useful for the typical pEp-mail-tool setup.

Simple configuration example

Most people will want to only use one IMAP store and one SMTP submitter, with one mail account. There is a configuration example covering this simple scenarion:

• configuration-examples/dot-pEp-mail-tool--easy--imap-smtp.py.example

The end of the example also explains how to configure the MUA to connect to pEp-mail-tool.

General configuration example

Another example file is provided, explaining every possible configuration item. It is longer and more complex than the simple example above, but should cover every use case.

See

• the example configuration file in configuration-examples/dot-pEp-mail-tool.py.example;

A user understanding this file should have no problem setting up her MUA.

Manual Dovecot configuration

Some people might want to run their own IMAP server, in order to tune performance or to integrate in some complex setup. In such cases the example configuration under configuration-examples/dovecot/ might be of use.

Usage

First start the pEp-mail-tool server. Currently the server remains in the foreground, and prints log messages to stdout:

./pEp-mail-tool --server --conf configuration-examples/dot-pEp-mail-tool.py

The server will periodically contact incoming mail servers to download messages, and will remain waiting to serve local requests.

From a different terminal (or from some other process, such as a mail user agent) one can invoke the client for local requests:

./pEp-mail-tool --outgoing-rating-stdin < MY-MAIL-SAVED-ON-A-FILE

The client will work by performing inter-process communication with the local server. In case of success the return code of the process will be zero, and a line of text will be produced such as

yellow (reliable 6)

In case of error the return code will be nonzero, and some error message intended for humans will be printed.

See

./pEp-mail-tool --help

for all the options.

Building

Building the p≡p stack from its source, while not difficult, is a long process because of the multiple repositories involved. The build/ subdirectory contains a script making it easier to build the entire p≡p stack up tp pEp-mail-tool from its sources. The script has been tested on several GNU/Linux distributions.

Resources

This is a list of further resources about pEp-mail-tool and pEp.

2023-06-27: Luca Saiu's pEp-mail-tool presentation: p≡p-mail-tool: Using p≡p for email with ordinary MUAs --- A status report with some personal opinions.

Luca Saiu gave a presentation about pEp-mail-tool at the end of June 2023 to his p≡p Foundation colleagues; the slides and video recording are now published with permission.

Notice that this presentation has not been updated to cover the recent pEp-mail-tool developments, and the software has already become considerably more general and powerful since the time of the presentation. This presentation should still be suitable as an introduction.

Abstract: I have written a new tool for using p≡p for email, particularly with traditional MUAs different from Thunderbird, on Unix systems; it is not complete but already at a point where a random reasonably technical person could use it production. I normally use Gnus as my MUAs – Gnus being one of the mail applications running on top of GNU Emacs. I wrote a small extension to Gnus for taking advantage of pEp-mail-tool, making the interface quite easy and friendly. Other mail programs can be adapted; but even without any adaptation the tool is useful.

• Slides: https://ageinghacker.net/talks/pEp-mail-tool-slides--saiu--2023-06-27.pdf

• Video recording: https://ageinghacker.net/talks/pEp-mail-tool--saiu--2023-06-27.webm