Topal

Topal is an application that links GnuPG and Pine/Alpine. It offers facilities to encrypt, decrypt, sign and verify emails.

Installation and configuration

Compilation and installation

To compile Topal, you need a working C compiler and the GNU Ada Compiler (GNAT). There is a makefile: simply type `make'. Type `make install' to see what files need copying (it doesn't actually do the copy).

MIME features require an installation of mime-construct and metamail.

Pine/Alpine configuration

Assuming that the topal binary is installed in /usr/local/bin, set up the Pine/Alpine sending and display filters as follows:

display-filters=_BEGINNING("-----BEGIN PGP ")_ /usr/local/bin/topal -display _TMPFILE_ _RESULTFILE_

sending-filters=/usr/local/bin/topal -send _TMPFILE_ _RESULTFILE_ _RECIPIENTS_,
/usr/local/bin/topal -sendmime _TMPFILE_ _RESULTFILE_ _MIMETYPE_ _RECIPIENTS_

You can choose either or both of the sending filters. The -sendmime option allows the user to choose the MIME type of the outbound email. (Legacy fixes are in place that make -decrypt and -verify behave the same as -display.) Note that _RECIPIENTS_ should be last.

For -sendmime to work, you will need to patch Pine/Alpine. There are patches for versions 4.44, 4.50, 4.53, 4.58. 4.60 and 4.64 of Pine. (They're all more-or-less the same patch.) cd into the pine4.xx directory and use the patch command.

There is one patch for Alpine: version 1.00. Please note that the Alpine patches also modify Alpine's configuration. There is a hidden preference `enable Topal hack' (enable-topal-hack) that you need to switch on.

It doesn't seem to have broken anything else.... It seems to work for sending via an SMTP server - it might break for sending via /usr/lib/sendmail (if it does, please send me a debug trace by invoking pine with `-d 9').

You can also add --read-from _INCLUDEALLHDRS_ before send and -sendmime. This makes Topal attempt to guess a suitable key for signing and self-encryption. If multiple possible keys match, then you'll be offered a menu of the keys.

Mailcap configuration

To decode MIME RFC2015/3156 multipart/signed and /encrypted messages requires the assistance of metamail. Add in either the user mailcap configuration (.mailcap) or the system configuration (/etc/mailcap) the lines
multipart/signed; /usr/local/bin/topal -mime '%s' '%t'; needsterminal
multipart/encrypted; /usr/local/bin/topal -mime '%s' '%t'; needsterminal
application/pgp; /usr/local/bin/topal -mimeapgp '%s' '%t'; needsterminal

Procmail configuration

In your procmailrc, add the recipe:

:0fw
| /usr/local/bin/topal --fix-email

This examines all inbound emails. Those with top-level multipart/signed or multipart/encrypted MIME types are modified to add a multipart/misc wrapper so that Pine/Alpine can hand it off to Topal. All other emails are left unchanged.

I strongly advise that you also use one of the backup recipes from the procmail manual. See also the notes in fixing multipart emails.

Topal configuration

Create a directory called `${HOME}/.topal'. This is currently hard-coded into Topal. Create the basic configuration file by running topal with the -dump or -default options. This file should be named `config'.

All .topal files are silently ignored if they cannot be found. Parsing errors cause an exception.

If you want to include strings with spaces, you'll need to quote them with double-quotes ("). Double-quotes themselves can be included by `stuffing' ("").

Features:

• In-place decryption/verification, dealing with multiple blocks embedded in text.
• Caching of output to reduce need for passphrase (at expense of storing decrypts and verification output).
• Receiving of MIME RFC2015/3156 multipart/signed and multipart/encrypted messages. Top-level multipart items need some modification: see the README section `fixing multipart emails'. These features are available to any program that uses .mailcap files.
• Sending of MIME RFC2015/3156 multipart/signed and multipart/encrypted messages. (Needs a patch to Pine/Alpine.)
• Sending and receiving of the old application/pgp content-type (sending requires the same patch as the previous item).
• Offers user the opportunity to check output before sending it.
• Rich configuration options.
• Shortcuts for selecting keys, as well as general key selection routines when sending email.
• Few arbitrary limits.

What is new in this release:

• Documentation updates and minor improvements to attachment and multipart detection.

What is new in version 73:

• Fix crash when sending attachments with spaces in filenames.
• Add new switch, wait-if-missing-keys, which requires the user to acknowledge if keys are missing when defaulting to encryption.
• Slightly reorganise configuration menu to keep it within 24 lines.
• Update documentation re: crashes related to the second patch and mailcap files.
• Topal makes greater efforts to check that external commands exist before running them.
• Exception messages are repeated via Ada's exception handling (if Topal panics).
• Added decrypt-prereq option. See this note.
• Experimental S/MIME sending support added.
• More use of GnuPG's --status-fd option so that we can determine exit status properly.
• Replaced ancient expanding_array package with Ada.Containers.Vectors.
• Adding sendmail-path filter mode. This is needed for the S/MIME encrypted and S/MIME sign+encrypted modes. (Otherwise only Topal can read them; neither Outlook nor Thunderbird will cope with an S/MIME part inside multipart/mixed.) This mode also needs pinentry-qt for gpgsm: pinentry-curses doesn't like this environment.
• In the sendmail-path filter mode, we no longer need the content-type guessing. We can simply re-use the content-type from the original header.
• Added replace-ids option which can replace Message-ID (and also Content-ID) in sendmail-path filter mode.
• The sendmail-path mode can also add a token to help spot our cc'd emails. Use something like st=user@domain,token to set a password. This is hashed with some headers for each email and added to an X-Topal-Send-Token header. Topal then has a -cst token mode which adds a X-Topal-Check-Send-Token header with either yes or no for that header.
• Investigation suggests that group addresses are handled other than I expect. E.g., Group name:; in the to: field and the actual list of addresses in lcc field will result in the addresses appearing in the bcc field in sendmail-path filter mode.
• Rewrite main documentation in LaTeX: the main manual is now topal.pdf. The change log is still in HTML.
• Start adding interoperability notes to manual.
• Diagnosing issue with clearsigned (both OpenPGP and S/MIME) emails that have passed through an MS Exchange server being corrupted.
• Added opaque signing option for S/MIME.
• Added attachment-trap boolean option. In -asend mode, this causes Topal to complain if the message body contains the string "attach" but doesn't have any attachments.

What is new in version 72:

• Fix menus for non-Pine sending. (a€˜Goa€ wasn't working!)
• Trap attempts to encrypt when no keys are in the key list.
• Minor change to distrib text and Makefile.
• Distrib target in Makefile now uses GPG agent.

What is new in version 67:

• Added another configuration option `omit-inline-disposition-header'. If a disposition header of value inline would be added, it's simply omitted altogether.

What is new in version 64:

• A Topal patch for Alpine 2.00 was added. (Alpine's S/MIME needs to be turned off for Topal's S/MIME verification to work.)
• Temporary files are now properly deleted.
• A bug when guessing the type of an attachment was fixed.
• A patch was added to Topal sources for Cygwin (the recent interrupt code doesn't build).

What is new in version 63:

• Warning messages about missing secret keys were improved.
• Initial support for remote decryption of messages was added.
• Signal handling for the remote server was improved.