__________________________________________________________________

                  Topal: GPG/GnuPG and Alpine/Pine integration

   Copyright (C) 2001--2010 Phillip J. Brooke
     __________________________________________________________________

Contents

     * Introduction
     * Features
     * Important changes from previous stable versions
     * Installation and configuration
          + Compilation and installation
          + Pine/Alpine patches
          + Pine/Alpine configuration
          + Mailcap configuration
          + Topal configuration
     * Topal usage
          + Help!
          + Configuration
          + Decryption/verification
          + Sending
          + Command-line usage
               o Sending (-nps)
               o Receiving (-pd)i>
          + Remote and server mode
     * Fixing multipart emails
     * Notes
          + The Pine/Alpine hack, and sending other attachments
          + Key IDs and keylists
          + Sending defaults
          + Errors
          + Decrypting attachments
          + Locale problems
          + "Couldn't find certificate needed to sign."
          + Cleaning up the cache
          + Remote and server mode
          + Working with GPG Agent
          + New releases
          + Release numbering
          + Hints
     * Author
     * Licence
     * To do
     * Version history
          + Most recent changes
     __________________________________________________________________

Introduction

   Topal is a `glue' program that links GnuPG and Pine/Alpine. It offers
   facilities to encrypt, decrypt, sign and verify emails. It can also be
   used directly from the command-line.

   Multiple PGP blocks included in the text of a message are processed.
   Decryption and verification output can be cached to reduce the number
   of times the passphrase is entered. RFC2015/3156 multipart messages can
   be sent and received with help from some scripts, procmail and a patch
   to Pine/Alpine. It includes basic support for verifying S/MIME
   multipart/signed messages. There is a remote sending mode for reading
   email on a distant computer via SSH with secret keys on the local
   computer. There is a high level of configurability.

   See the list of features below.
     __________________________________________________________________

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).
     * Basic support for verifying S/MIME multipart/signed messages.
     * Offers user the opportunity to check output before sending it.
     * Remote sending and decryption for when reading email on a distant
       computer via ssh with secret keys on the local computer.
     * Rich configuration options.
     * Shortcuts for selecting keys, as well as general key selection
       routines when sending email.
     * Few arbitrary limits.
     __________________________________________________________________

Important changes from previous stable versions

   Recent stable releases have been numbered 55, 56, .... Prior to release
   55, the stable releases were 0.7.2, 0.7.8, 0.7.9 and 0.7.13.6.

  Important changes in release 70

   The use-agent option sets GPG's --use-agent option as needed. Don't set
   it in any other way or it might be confusing....

  Important changes in release 68

     * The sending interface has changed. Selecting (for example) `e' for
       encrypt no longer immediately operates. Instead, the desired
       operation is chosen, and then `g' for `Go!' is used. This allows
       defaults to be associated with keys and email addresses in a
       sensible way.
     * The MIME viewer setting mime-viewer has been replaced by two new
       settings, one for decrypting and one for verifying. You should set
       these to suit your preferences. (The redundant line will be dropped
       the next time you save your configuration inside Topal.)

  Important changes in release 65

   An additional patch has been added. This should make the procmail
   recipe redundant. More testing is required: it may have broken other
   Alpine features.

  Important changes in release 60

     * MIME sending now requires MIME-tool; mime-construct is no longer
       used. See compilation and installation.

  Important changes in release 58

     * The default configuration no longer uses absolute paths.

  Important changes in release 55

     * If you use a non-English locale, please check that Topal still
       works as expected (replaced code that fixed some locale problems).
     * The Alpine patch is based off my old Pine patches, but does a
       little more. You will need to set the Enable Topal hack for
       OpenPGP/MIME messages option in the hidden configuration list. Bug
       reports welcome.
     * The --fix-email wrapper no longer creates a multipart/alternative:
       it creates a multipart/misc wrapper instead. Please check that your
       procmail recipe includes a suitable backup in case this doesn't
       work for you.

  Important changes in version 0.7.10

   The recommended procmail recipe has been changed.

  Important changes in version 0.7.8

   topal-fix-email and topal-fix-folder have been replaced by the main
   topal binary. Change topal-fix-email in your .procmailrc to be topal
   --fix-email. (Or add symlinks: the binary checks what it has been
   called as.)

   You must clear your cache otherwise the changes made for
   inline-separate-output (added in version 0.7.8) will break (this occurs
   regardless of whether the option is on or off). This new feature shows
   the GnuPG/Topal output separately, then hands back the decrypted or
   verified output without any wrappers. This makes it more suitable for
   dealing with attachments (but you need to set it manually via topal
   -config).

   Finally, the send menu has a new option: `Pass through unchanged'. This
   does nothing to the message so, you can always have Topal invoked as a
   filter for sending.
     __________________________________________________________________

Installation and configuration

  Compilation and installation

   To compile Topal, you need
     * a working C compiler,
     * the GNU Ada Compiler (GNAT), and
     * some common libraries, including readline (e.g., the package
       libreadline5-dev on Debian).

   There is a makefile: simply type make. Type make install to actually
   install. The default location is /usr, so you'll need to be root to
   install. Alternatively, use make install INSTALLPATH=/usr/local to
   install into /usr/local. (Or use the more specific variables
   INSTALLPATHBIN, INSTALLPATHMAN, INSTALLPATHDOC and INSTALLPATHPATCHES.)

   (Cygwin users: before using the makefile, please apply the patch
   cygwin.patch. I haven't recently tested this....)

    MIME sending

   MIME sending requires the Topal version of mime-tool (included with the
   Topal sources, and compiled and installed at the same time using the
   Makefile). Also see Pine/Alpine patches below.

    MIME viewing

   MIME viewing can be handled via metamail, run-mailcap, or by saving to
   a file in the ~/.topal directory and viewed with Alpine. If you are
   using the second patch (see Pine/Alpine patches below), then depending
   on your Alpine configuration, Alpine might say something like
   "Attachment SIGNED unrecognized. Try opening anyway?" - you should say
   yes in that case.

  Pine/Alpine patches

   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 are patches for Alpine: versions 1.00, 1.10 and 2.00 (patch 1 and
   patch 2). 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').

  Pine/Alpine configuration

   Assuming that the topal binary is installed in /usr/bin, set up the
   Pine/Alpine sending and display filters as follows:
display-filters=_BEGINNING("-----BEGIN PGP ")_ /usr/bin/topal -display _TMPFILE_ _RESULTFILE_

sending-filters=/usr/bin/topal -send _TMPFILE_ _RESULTFILE_ _RECIPIENTS_,
                /usr/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.

   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/bin/topal -mime '%s' '%t'; needsterminal
multipart/encrypted; /usr/bin/topal -mime '%s' '%t'; needsterminal
application/pgp; /usr/bin/topal -mimeapgp '%s' '%t'; needsterminal

  Procmail configuration

   From Topal 65: this recipe is no longer needed if you are using
   patch-2. (However, I have received one report of intermittent crashes
   with that patch.)

   In your procmailrc, add the recipe:
:0fw
| /usr/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. Comments
   begin with a # in the first column, and run to the end of a line. They
   are totally ignored and are not currently preserved. 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' ("").
     __________________________________________________________________

Topal usage

  Help!

   -help as the first argument dumps a help message.

   The help message is derived from the help.txt file (included at compile
   time).

   See help.txt for information on non-Pine use of Topal.

   Send email to me if you're really stuck.

  Configuration

   -config as the first argument brings up the configuration menu. This
   menu is also available when sending (so that the signing key can be
   changed).

   However, not all features can be configured via the menus. In some
   cases, you'll need to edit .topal/config.

   If you want to change the comment mentioning Topal when sending
   messages (i.e., the bit saying Topal
   (http://freshmeat.net/projects/topal)) then modify the sending-options
   (via the configuration menu or the config file).

   Colours were introduced in release 71. If you want to turn them off,
   set ansi-terminal=off in the config file. You can change the colours by
   setting colour-menu-title, colour-menu-key, colour-menu-choice,
   colour-important, colour-banner and colour-info. The codes are the
   escape codes (see, for example, colour table in the Wikipedia article
   on ANSI escape codes.).

  Decryption/verification

   Depending on configuration, Topal will either ignore the file
   altogether, ask you what you want to do with it, or proceed to process
   the file automatically.

   GPG will ask you for your passphrase when it needs it.

   Caching is in place; the results of decryption and verification are
   (subject to configuration) saved in ~/.topal/cache. The results of
   caching mean that you won't be repeatedly asked for your passphrase, at
   the expense of storing decrypts in the clear.

   Be warned: Topal often invokes less to view something. So you'll need
   to use q to get out of it. metamail or run-mailcap may be called for
   anything after MIME processing.

   A new option (for version 0.7.8) called inline-separate-output concerns
   inlined (i.e., not MIME) messages. If the option is on, then the
   Topal/GnuPG output will be shown to you by less. Then the decrypted or
   verified output will be handed back to Pine/Alpine. This is the way to
   approach attachments. However, you will normally want to keep this
   option off, because if you're reading (for example) BugTraq mailings,
   then it will want you to hit q an awful lot....

  Sending

    Main send menu

   Topal initially displays some chatter about selecting keys, including
   (if possible) a key for the sending user. After that, you will be
   presented with the sending main menu. Some options (e.g., those
   relating to MIME features) will not be offered unless you use the
   -sendmime option.
** Main send menu:
 Sending mode: No GPG
               Inline plain
 Signing key: 9DAF9B5C 2005-10-21 Dr Phil Brooke
 1 key(s) in key list      0 attachment(s)
[lkr] List/edit recip. keys   [@] Add own key       [w] Edit own key
[n] Pass through unchanged    [1] Inline plain      [v] View mail
[e] Encrypt                   [2] app/pgp           [m] Edit mail
[s] Sign-encrypt              [3] multipart/*       [a] List/edit attachments
[c] Clearsign                 [4] multipart encap   [o] Configuration
[g] Go!                       [r] Remote!           [q] Abort!

   `Abort' tells Pine/Alpine you don't want Topal to process the email
   anymore.

   `Pass through unchanged' does nothing to the message. This means that
   you can always have Topal invoked for sending.

   `Add own key' adds an `encrypt to self' key. (It is added by default,
   but if you remove it, this is a quick way to restore it.)

   When you select `Go!' you will be asked to confirm the command-line,
   and after processing, less is invoked to visually check that the
   desired result has been achieved. Again, a confirmation is asked for.

   Topal can offer a choice of three MIME types. Don't use (2 - app/pgp)
   unless you really know what you're doing. (4 - multipart encap) is only
   relevant if you are signing and encrypting: this encapsulates a MIME
   signed message inside an encrypted message. Otherwise, we do both
   operations at once. (If you choose `clearsign' and `multipart/*', then
   all trailing blank lines will be deleted. Note also that Pine/Alpine
   appears to delete trailing whitespace in trailing blank lines.)

   `Configuration' offers the same menu that is available from the -config
   option.

    List current recipient keys

   `List current recipient keys' offers a list of recipients:
** Key list menu:
 1 key(s) in key list
Select key or [dq] to quit and return to main send menu
           or [s] to select a key after searching in the main keyring
           or [ak] to add keys from the main keyring
                    (not recommended, use `s')
Displaying choices 1 to 1 of 1 to 1    (<,) page up   (>.) page down
 1 - 9DAF9B5C 2005-10-21 Dr Phil Brooke

   `Quit and return to main send menu' sends you back to the first menu.

   `Add key from main keyring' prompts you for a search pattern. It will
   do a general search on your GPG keyring and add all matching keys.
   Beware of just pressing enter - it will select all keys on your
   keyring.

   A better alternative is to use the `select after search' option. This
   also does a search on your GPG keyring, but then you must select one
   key to be added to your list of recipients.

    Examine key menu

   Selecting a key will offer a third menu (a similar menu is offered when
   selecting a single key):
** Examining key currently in key list:
Key: 9DAF9B5C 2005-10-21 Dr Phil Brooke
[d] Display details of key with less   [v] Verbosely
[r] Remove key from list               [kql] Return to key list

   `Return to key list' takes you back to the second menu.

   `Display details of key (less)' simply uses GPG to list the key details
   via less. You'll need to use `q' to get out of less.

   `Verbose details of key (less)' pipes verbose output from GPG for this
   key into gpg. You'll need to use `q' to get out of less.

   `Remove key from list' removes the key from this recipient list.

  Command-line usage

    Sending (-nps)

   If you invoke Topal on the command-line with a filename as an argument,
   it will offer the sending functions on that file. It doesn't actually
   send anything: instead it allows you to encrypt, sign, etc. the
   message. You have a choice of overwriting or preserving the original
   file (this bit is case-sensitive). So e, s, c are different from E, S,
   C.
** Main send menu:
 Sending mode: No GPG
 Signing key: 9DAF9B5C 2005-10-21 Dr Phil Brooke
 1 key(s) in key list
[lkr] List/edit recip. keys   [@] Add own key       [w] Edit own key
[n] Pass through unchanged    [D] Detach sig prsv   [v] View mail
[e] Encrypt                   [E] Encrypt prsv      [m] Edit mail
[s] Sign-encrypt              [S] Sign-encrypt prsv [o] Configuration
[c] Clearsign                 [C] Clearsign prsv    [q] Abort!
[g] Go!                       [r] Remote!           (prsv = keep original)

   The main purpose of this mode is for encrypting or signing attachments
   before they are attached to the message in Pine/Alpine. Beware that
   Pine/Alpine does not feed the attachments to a sending filter. Or you
   could use the attachments option when using Pine with MIME emails.

   MIME functions are not available in this mode: it makes no sense.

    Receiving (-pd)

   Invoking Topal with only -pd as an argument causes it to read a message
   from standard input and attempt to decrypt/verify it. This is useful
   for piping MIME messages from other applications.

   (New in release 71.)

  Remote and server mode

   Suppose you are reading your email on a remote host via ssh (as I often
   do). You now want to compose an email and sign it, but your secret key
   is only accessible on the local computer. Topal has rudimentary support
   for this (primarily to support my style of working). This comes in two
   parts: a `server' mode to run on the local computer (with access to the
   secret key) and a remote option in the sending menu.

   The server mode (on the local host) is started by running topal
   -server. This is where GPG requests for signing are made.

   When sending, you can choose `remote'. This prompts for the host to
   connect to using ssh/scp: this host should be running the `server'. The
   files are sent to the local server, processed by the server, then the
   results are copied back. ssh and scp are both used: because they're
   used repeatedly, you might want to use key-based authentication and
   have the key added to a current ssh-agent.

   There is also a remote mode for receiving, with a similar behaviour as
   for sending. Alternatively could use something like unison (or some
   other file synchroniser or a simple scp) to move the email(s)
   concerned, then view them on the local computer.
     __________________________________________________________________

Fixing multipart emails

   Two scripts used to be included with topal (long ago): topal-fix-email
   and topal-fix-folder. They have been replaced by the --fix-email and
   --fix-folder command-line options to the main binary.

   topal --fix-email modifies any email that is (at the top level) a
   multipart/signed or multipart/encrypted message. It creates a
   multipart/misc message instead: this revised message is simply a
   wrapper version of the original message so that Pine/Alpine can pass
   the signed or encrypted part to Topal.

   Usage:

   topal --fix-folder <folder> ...
          This fixes the old email folders you may have.

   topal --fix-email
          Takes no arguments; it accepts a single email on stdin. Ideally,
          it should be invoked by procmail (see the configuration section
          above).

   topal --fix-email has a simpler mode (--simple) where it pretends that
   there are two MIME content types: `application/x-topal-encrypted' and
   `application/x-topal-signed'. You might prefer using this.

   Why do we need this? If we just set the .mailcap file for, say,
   multipart/signed, then Alpine (at least version 1.00) is unable to
   handle a top-level multipart/signed email: an error message starting
   `Can't find body for requested message' is seen. But multipart/signed
   inside a multipart/mixed (or multipart/alternative, etc.) can be
   successfully handed-off to Topal.

   Replying to such messages is a pain: you'll have to save off the actual
   message and read it in. Suggestions on fixing this are welcome....

   See Workaround.Fix_Email in the sources for more details.
     __________________________________________________________________

Notes

  The Pine/Alpine patches, and sending other attachments

   What does the (first) patch to Pine/Alpine do? It removes some of the
   safety checking when changing the content-type (_MIMETYPE_) in a
   filter. Normally, if the returned content-type is not text/*, then the
   entire content-type is dropped.

   The patch instead adds a flag, `topal_hack', and sets this if the
   returned content-type is not text. From time-to-time, we pretend that
   the body is normal text. We take a little care to check if this message
   is already a multipart message, so hopefully, the normal sending of
   attachments still works.

   The second patch file (new from Topal release 65 for Alpine 2.00)
   slightly modifies some of the mail reading code to allow .mailcap
   settings to act directly on top-level multipart messages.

  Key IDs and keylists

   Topal internally lists keys by their fingerprint. It uses GPG to look
   up key fingerprints by using whatever GPG can cope with.

   Duplicate keys are silently suppressed. Removing a key only removes one
   instance, if somehow you've coerced Topal to list duplicates (which is
   quite easy, since adding a key with its short key ID, and the same key
   with its fingerprint will add two identical keys).

   The way that Topal chooses the keys is as follows:
     * For each recipient email address (supplied by Pine)
         1. For each matching line in keylist, use the key ID to get a
            fingerprint, and add the key to the list.
         2. In there are no matching lines in keylist, try to get a
            fingerprint via just that email address (but exclude `xk'
            configuration entries).

   The keylist is a way to say, `for this particular email address, use
   this particular key'. In your config file, include lines such as
ake=50973B91,philb@soc.plym.ac.uk
ake=50973B91,pjb@lothlann.freeserve.co.uk

   These mean `use key 50973B91 for the given email addresses'. Similarly,
xk=50973B91

   means `don't use key 50973B91'. There are also similar sake and sxk
   options for the secret key selection (via --read-from) (although the
   testing of the secret key listings is less thorough so far).

  Sending defaults

   The sd expressions can assign a default to a key ID or email address.
   The special expression @ANY@ matches any email address (or key). The
   last matching sd expression applies.
     * n: no GPG
     * e: encrypt
     * s: sign and encrypt
     * c: clearsign
     * I: inline plain
     * A: app pgp
     * M: multipart
     * E: multipart encapsulated

   Example: the following means that the default settings for the given
   address are encrypted and inline plain.
   sd=pjb@lothlann.freeserve.co.uk,eI

   Topal will warn you if you are sending to multiple recipients, and sd
   has selected encryption, and not all of the recipients have keys.

   (New in release 68.)

  Errors

   Bad things happening should result in Topal setting its exit status to
   `failed', so Pine should detect this and not send your email.

   Bug reports are welcome: send them by email to me (contact details
   below).

  Decrypting attachments

   If an attachment is a plaintext PGP ASCII-armoured message, then Topal
   will be invoked by Pine. You probably want to say `no' when asked here
   (beware of the configuration options here). Otherwise, you'll get a
   decrypted file with the original attachment filename, plus the various
   Topal headers.

  Locale problems

   GPG does not do any encoding of input data. This means that the
   encoding is dependent on Pine/Alpine and Topal. If a message is sent
   with one encoding and received by a user running in a different locale,
   then we might end up with a good message not verifying (i.e., bad
   signature).

   I currently have no way to automatically fix this. However, the
   --ask-charset option will ask during inline decryption/verification if
   you want to change the encoding. If you know that the message was
   written by a UTF-8 user (and you're in a different locale), this might
   help. (This only happens if a bad signature is returned.)

   I know it's a kludge. I'd be interested to hear success and failure
   reports.

  "Couldn't find certificate needed to sign."

   A regular query (for both Topal and other OpenPGP filters) concerns the
   message "Couldn't find certificate needed to sign." This message is
   part of Alpine's S/MIME support: it is nothing to do with Topal. One
   option is to turn off the internal S/ MIME support via the (hidden)
   config option ("S/MIME -- Turn off S/ MIME").

  Cleaning up the cache

   You might want to run something like
find ${HOME}/.topal/cache -mtime +7 | xargs rm

   to remove all the cache files that are a bit old (in this example, 7
   days old or older).

  Remote and server mode

   When remote is invoked in a sending menu:
     * The host has to be chosen for ssh/scp.
     * Because topal might be outside the normal path, you'll be asked for
       that too.
     * The sender scp's the relevant files into .topal/server.
     * The sender calls ssh (server) -remotesend ... or ssh (server)
       -remotesendmime ....
     * The invocation of -remotesend or -remotesendmime triggers the
       server to run a new instance of Topal on the local computer.
     * When that instance is finished, the relevant files are copied back,
       along with the return value.

   For receiving: if decrypt-not-cached/decrypt-cached are set to 2 (ask),
   then as well as offering to decrypt (yes or no), it will also offer
   remote decryption. The caching settings are irrelevant at this point.

  Working with GPG Agent

   The use-agent configuration option has three values: (1) never use an
   agent, (2) only use it for decryption, (3) always use it. Don't put
   GPG's --[no-]use-agent options in any other configuration options.

  New releases

   To be notified of new releases of Topal, send an email to me.

  Release numbering

   The old release numbering was making less sense to me. New releases are
   simple integers. In the event that an earlier release is modified, I'll
   then add extra components to the release number.

  Hints

     * Consider using GPG's --trusted-key option in Topal's gpg-options
       configuration setting. This is useful if you keep your secret keys
       offline.
     * Use the --read-from option, especially if you use multiple roles.
     __________________________________________________________________

Author

   Phil Brooke wrote this, partially out of boredom, but mostly because he
   wanted a GPG/Pine add-on to do exactly what he wants. There are many
   similar programs.

   If you like this program, please tell me. If you'd like it better with
   changes, please tell me what changes you want. If particular items on
   the `To do' list are important to you, let me know. In particular, if
   you find bugs, feel free to tell me the details by email.

   This package is released under the GPL: see the file COPYING.

   I can be emailed on pjb@lothlann.freeserve.co.uk

   My key ID is 0x50973B91; the key is available from web pages and public
   key servers.

   If you want to send snailmail to me, email me for my (physical)
   address.
     __________________________________________________________________

Licence

   This program is free software: you can redistribute it and/or modify it
   under the terms of the GNU General Public License version 3 as
   published by the Free Software Foundation.

   This program is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
   General Public License for more details.

   You should have received a copy of the GNU General Public License along
   with this program. If not, see http://www.gnu.org/licenses/.
     __________________________________________________________________

To do...

     * Planned releases:
          + Add S/MIME support via gpgsm.
          + Improve attachments code (and add some documentation).
     * Better error handling, particularly when missing dependencies such
       as mime-construct or metamail.
     * Add signal handlers.
     * Catch GPG keyboard interrupt.
     * Should we check that the infile matches the cache file even if the
       MD5 hash matches? (We'd need to store the infile in the cache as
       well.)
     * Check through code: all external calls should check return values.
     * Refactor code.
     * Add interrupt option at very beginning of execution? (which would
       bring up the configuration menu?)
     * Associate extra options with particular keys?
     * Configuration routine for managing keys/config/keylist?
     * Implement rest of configuration menu.
     * Make a much nicer interface all round....
     * Separate out all the constant strings -- so that we can have
       internationalization.
     * Context-sensitive help throughout (modify mkhelp to create multiple
       procedures, or do it by number?); add COPYING option?
     * More receiving/decrypt options: include both plaintext and
       ciphertext.
     * Add periodic cache cleanup when Topal is invoked?
     * Add logging for workaround mode (report time of email processing
       (include PID); indicate if the file was changed or not)?
     __________________________________________________________________

Version history

   Look in release for the current release number.

   06/2001, 0.1
          First alpha release.

   06/2001, 0.2
          Minor changes.

   06/2001, 0.3
          Major changes to how keys are identified and looked up.

   06/2001, 0.4
          Adding more customization features.

   11/2001, 0.4.4
          Cleaned up some error messages; added -nps mode.

   11/2001, 0.4.5
          Added `gpg-options' config item with default `--no-options'.
          (Forgot to add this note as well....)

   11/2001, 0.5.0
          Dumped -verify and -decrypt modes in favour of the
          multiple-block `-display' mode. Added -help. Added caching.
          Added more switches relating to caching. Better output
          formatting.

   11/2001, 0.5.1
          Improved menus. Tidied up some of the interface. Added -s, which
          does the same as -nps.

   12/2001, 0.5.2
          Tidied disclaimer. Added synonyms for -help (-h, -?, --help,
          --h) Cleaned up menus; keypresses aren't echoed any longer.

   12/2001, 0.5.3
          Altered packaging to include version in directory name. Changed
          names of some -clear options to be a bit more sensible. Changing
          config settings method (big change). Making -s the default
          operation. Some rearrangement of code, constants. Some
          configuration editing possible via Topal. Send has access to
          configuration menu.

   12/2001, 0.5.4
          Bug fix; one-off error in the sending menus.

   12/2001, 0.5.5
          Removed redundant examples directory. Changed over to HTML
          documentation. Tweaked the RELEASE stuff. Use space instead of
          enter when waiting to continue: this looks forward to offering a
          help option at every prompt. The receive/blocks stuff now uses
          an expanding array. The GPG return value is checked when
          receiving: if it's bad, then some bits of the output are
          omitted; the cache file is not written. The date bit of Topal
          output moved onto the previous line (echo -n blah blah).

   12/2001, 0.5.6
          Adding installation instructions. Using tee and PIPESTATUS to
          get stderr on screen during receiving while also saving that
          output and recording gpg's exit status. Changed RELEASE filename
          to release. Tidied up the Makefile. Invalid passphrase messages
          are grep'd out of the output. Added `fast continue' options. Key
          lists in the configuration section now use expanding arrays.
          Changed key details selection message. Secret key selection now
          offers a menu of secret keys on the secret keyring. Initial
          recipient search excludes keys in XK list. Added key
          search/selection menu choice - much nicer to use than the add
          menu. More configuration stuff added (still more to do, although
          the config file can always be used). Partial documentation
          update.

   2/2002, 0.5.7
          Adding limited RFC2015/MIME decoding of multipart email.

   2/2002, 0.5.8
          Adding mime-construct to configuration in expectation of more
          RFC2015 features. Put test for the config file existing before
          actually attempting to read it (oops). Added -O2 -Wall and the
          TOPALDEBUG variable for compiling. Put up WWW page via own
          Freeserve site. Announcing via Freshmeat. Automating output WWW
          site generation (all the grunge in the Makefile).

   3/2002, 0.6.0
          Distribution uses a gzip'd binary now.... Added a pre-built
          binary that is statically linked against the GNAT stuff so that
          people don't need to acquire GNAT first (this, I believe,
          complies with the GNAT licence).
          Added the scripts topal-fix-email and topal-fix-folder. This
          makes it a lot easier to work with other people's
          multipart/signed or /encrypted email. Procmail recipe added to
          this README.
          Added display of application/pgp messages. Including the text of
          one of these in a reply might be difficult, but then, it was
          difficult without topal's mangling. At least they can be
          verified and read now.
          -sendmime option added. Hack needed (in topal-pine-patch [now
          pine-4.44.patch]) to allow non-text/blah content-types in Pine.
          RFC2015 send and received done (including micalg detection when
          sending clearsigned messages: list used from RFC3156.). Ditto
          for application/pgp, but I'm not sure of some of the parameters,
          since I've only ever seen signed emails of this form.
          Removed some of the waits for execution, since it seems
          reliable. Added error checking on return value of GPG in sends.

   3/2002, 0.6.1
          The Content-Type for MIME sending is displayed on the screen
          using `cat' rather than `less', which was getting to be
          annoying.
          Two changes that are related to how I manage the source code:
          Slight tweak to makefile for keeping track of RCS files; and
          using rcs -n<symbolic-name> to tag the released files.

   3/2002, 0.6.2
          MIME clear-signed messages: trailing blank lines are now deleted
          before signing (this would cause BAD signature when verifying on
          some other MTAs). Added remarks to documentation about the patch
          to Pine and attachments.

   4/2002, 0.6.3
          RFC1847 multipart encapsulation added. (See section 6.1 of
          RFC3156.) Cleaned up related receiving/caching behaviour.
          Another MIME clear-signed messages bugfix. This one sorts out
          line-end conventions correctly.
          New patch for Pine: this stops a SEGFAULT when using RFC2015
          stuff and other attachments at the same time.
          Updated documentation; added man pages for the two scripts.

   4/2002, 0.6.4
          New patch for Pine. Adds a workaround for the problem where some
          versions of MS Exchange would silently lose inbound MIME
          clearsigned email. It turns out that a slight formatting change
          stops the problem.

   5/2002, 6/2002; 0.6.5, 0.6.6, 0.6.7, 0.6.8
          Adding more debugging, mostly to the menus code. Used for
          tracking down a nasty problem causing exceptions. Many thanks to
          Felix Madlener for pointing this out and testing the revised
          code.

   7/2002, 0.6.9
          Renamed the Pine patch for when new versions come out. (It's
          still the same patch as for Topal 0.6.4.) Added trap for
          non-existent file when using `-s'. Cache directory as well as
          .topal directory is also chmod'd to 700. Added README.txt to
          package file (even though it's generated from the .html) so that
          those who just want to `less' it (instead of firing up a HTML
          reader) can do so.

   8/2002, 0.7.0
          Changed email address in man page. Lots more exception handling
          for extra info when something goes wrong. Moderate code
          reorganisation: mostly splitting blocks of code out for future
          work. Fixed `bug' (feature?) where send fails if a public key is
          unusable (although this may risk sending plaintext through; we
          assume that if an output file was generated, then the GPG errors
          weren't fatal). Now we check instead if the output file exists.
          Checking all source files for any similar bugs in menus (cf. the
          5/2002 entry). Modified MIME RFC2015 receiving function so that
          it isn't so reliant on shell calls of sed (which can fall over
          with nasty characters in an incoming emails boundary). Moreover,
          it can now cope with MIME parts that don't end with a newline.
          Tweaking MIME/verify cache handling: we shouldn't actually get
          an output file from GPG (since we're only verifying one part
          with the other); we put a vague warning if this happens, and
          trap when reading the cache. Added content-type to plaintext for
          MIME/encrypted. Documentation update.

   8/2002, 0.7.1
          Fixed minor bug with inverted return code (`-s' trap). Doc
          update.

   9/2002, 0.7.2
          Fixed minor bug in key list handling code (dealing with key
          selection).

   9/2002; 0.7.3, 0.7.4 (BETA)
          Disposed of the dependency on a shell by introducing Ada
          bindings for fork/exec/dup/pipe/glob, etc.. Several external
          binaries are no longer needed (cat, echo). Most return codes are
          now properly checked (although still need to do a better audit).
          Followed Eduardo Chappa's advice and changed Pine patch version
          letter. Miscellaneous cleanups and fixes. Many thanks to Peter
          Losher for giving me the incentive to sort out the external
          calls.

   9/2002; 0.7.5 (BETA)
          Tidying up structure of external calls, and how the various
          messages are built up and torn down. Changed the lynx switches
          at the suggestion of Felix Madlener (many thanks!). When
          receiving MIME encrypted attachments, the output is not included
          in the Topal output, but only in the metamail invocation.

   10/2002; 0.7.6 (BETA)
          Explicitly noted which versions are not intended for general use
          (beta versions). Rearranged command line parsing for more
          flexibility in future.

   10/2002; 0.7.7 (BETA)
          Re-implementing topal-fix-email and topal-fix-folder as part of
          the main topal binary. This removes the (script) dependency on
          munpack, but adds formail and diff to the main binary. Fixed
          some missing bits for particular binaries in configuration
          handling. Adding `important changes from last stable version'
          documentation. Tweaked the body extraction procedure. Tweaked
          some output messages. Major changes to menus: they now use
          enumerated types rather than integers.... Tweaking cl_menu some
          more. Added `pass-thu' option to send menu (so you can always
          use the Topal filter. This might also fix the minor problem with
          text/html occasionally being sent when it shouldn't be....)
          Fixed bug where MIME decrypt failure would still cause metamail
          to be invoked, but that's a waste of time.

   10/2002; 0.7.8
          Clearing out case statements with `when others'. Tidying up
          sending.adb. Fixed problem in MIME output where a leading blank
          line was added. Finally implemented `topal --fix-folders'
          functionality added. No longer need the two old scripts (I
          hope)! Another documentation tidy-up. Added
          `inline-separate-output' option: this effectively turns off the
          GnuPG/Topal wrappers in output. However, the side-effect is that
          the cache must be cleared when upgrading to this version.

   11/2002; 0.7.9
          Added some infrastructure for encrypting/signing attachments
          (but this is nowhere near working yet). Documentation and
          manpage update (again). Seems stable, will release.

   2/2003; 0.7.10, 0.7.11
          Tweaking distribution pages (mkdistrib). Including patches
          against Pine versions 4.50 and 4.53. (They're all more-or-less
          the same patch. It's pretty easy to apply them against 4.51 and
          4.52 if you feel so inclined.) Further doc clean up (particular
          the stuff about important changes from previous stable
          versions). Implemented Felix M.'s suggestion for handling
          non-existant command-line options: things that aren't valid
          options, but are prefixed with a `-' get a more helpful error
          message. --fix-email workaround also writes out the original
          input in the exception handler. Changed recommended procmail
          recipe so that Topal's exit code is checked.

   2/2003; 0.7.12
          Adding `workaround-error-log' file to .topal. This accepts
          output from topal --fix-email when it fails to exit cleanly. Not
          quite clear if this bit works yet (was tracking down other
          problem). It appears that when running without a real terminal,
          the call to set_echo fails. Odd. Nasty workaround implemented.

   2/2002; 0.7.13
          Added missing includes to ada-echo-c.c. Perhaps related to issue
          in the previous entry.

   4/2003; 0.7.13b
          Bug fix release only - backported from (not-yet-released 0.8.0).
          Fixed bug when changing own signing key using the -config option
          - thanks to Stewart James for the bug report.

   10/2003; 0.7.13.2
          Bug fix release only - backported from (not-yet-released 0.8.0).
          Changed bug fix versioning scheme. Makefile now links properly
          against static GNAT runtime. Fixed problem which manifests as:
          `relocation error: /lib/libreadline.so.4: undefined symbol: BC'
          (needed instruction to link against ncurses) - thanks to Marty
          Hoff for the bug report. Added patch against Pine version 4.58.

   10/2003; 0.7.13.3
          Now use -gnatwa and -gnato for all Ada compilation. It was
          omitted from the main binary build command before. Fixed all the
          resulting warnings.

   1/2004; 0.7.13.4
          Patched externals calls for errno to prevent (in some cases)
          warnings from ld.so, and in other cases, failures to build.

   6/2004; 0.7.13.5
          Added patch against Pine version 4.60. Updated some notices.

   1/4/2005; 0.7.13.6
          Calls to the GPG binary now have LANG set to C before exec so
          that we don't have to worry about different language output in
          GPG. Thanks for Joern Brederec for the bug report and suggestion
          of how to fix it.

   2005-2007
          Four internal development releases junked.

   8/1/2008; release 55
          --fix-email now replaces the original message with a
          multipart/misc wrapper, rather than expanding it into a
          multipart/alternative message.
          Replaced some key selection code. Hopefully, this reduces the
          number of locale-dependent and GPG version-specific problems.
          Additionally, revoked, disabled and invalid keys are no longer
          offered; checks are made to ensure that the key is valid for
          encryption/signing when applicable.
          New patch for Alpine 1.00. Includes configuration setting.
          The `pass through unchanged' send option no longer modifies the
          content-type to text/plain.
          Should now build and run on Cygwin.
          Licence is now GPL-3.
          Attempt to prevent potential memory leak (if running for a long
          time) by making the implementation of expanding_array a
          controlled type.
          Cleaned up Ada source to reduce warnings.
          Other minor changes, e.g., better checks on keylists,
          documentation clean-up.
          Changed release numbering.
          HTML cleaned up and CSS added.

   8/1/2008; release 56
          --read-from option added to select different signing keys
          depending on the From line. Also added sake and sxk
          configurations.
          Fixed bug in Keys.Remove.Key (didn't match if the full
          fingerprint wasn't given).
          Command-line parser now accepts 1 or more hyphens for any
          option.
          Improved keylist documentation.
          Corrected release date for release 55... oops.

   8/1/2008; release 57
          Initial attempt at supporting attachments within Topal.
          Changed MIME boundary detection code (the previous algorithm
          couldn't cope with multipart included in a signed email). Please
          tell me if this breaks your emails....
          Bug fix to _INCLUDEALLHDRS_ - it needs to turn the CRLF back
          into LF or it might chop off some of your message....

   22/6/2008; release 58
          UI improvements (count keys in keylist, clearer indication of
          position in menus).
          Added patch for Alpine 1.10. Renamed all patch files.
          Default paths for binaries are no longer absolute.
          Configuration files now allow comments, but they're not
          preserved by Topal.
          Added more exception handling messages.
          Sending and receiving both save off original input as tempfiles
          to help debugging.
          Added --ask-charset command line option. This is really only for
          testing a new workaround for locale-related bad signatures.
          Please see locale problems in the notes and send feedback.
          Started removing dependency on mime-construct; new source files
          mime.ad[sb].
          Build date added to binary.

   3/7/2008; release 59
          Added sequence numbers to temporary files to reduce possible
          name conflicts.
          The makefile's install target now installs to INSTALLPATH. This
          can be overridden, e.g., make install INSTALLPATH=/usr/local.
          The four more specific paths, INSTALLPATHBIN, INSTALLPATHMAN,
          INSTALLPATHDOC and INSTALLPATHPATCHES can also be overridden.
          Fixes request from Nils Schlupp re: ebuild.
          The --ask-charset command-line option is now only used if a bad
          signature is returned; a second attempt is then made if a
          different character set is suggested by the user.

   13/7/2008; release 60
          Update installation instructions for make install.
          We now use a modified version of Jeffrey S. Dutky's mime-tool
          instead of mime-construct for creating MIME messages. We include
          our modified version in the Topal tarball (since both are GPL,
          and our modifications are needed if creating MIME messages).
          MIME viewing can now use metamail, use run-mailcap or save the
          attachment to the folder ~/.topal/viewmime (which you can then
          open in Alpine). run-mailcap and saving support are new.
          Sending menu allows user to view and edit the email. A quicker
          method for changing/setting the signing (own) key is available.

   14/7/2008; release 61
          An initial, rather crude, but (for my purposes at least)
          effective remote mode for sending.
          Some history is now saved.

   17/7/2008; release 62
          Added basic support for S/MIME verification of messages.
          Quoted-printable encoder (in MIME-tool) improved (single dots
          and leading "From ") as per RFC2049.
          Decode quoted-printable and base64 before calling run-mailcap.
          Ignore errors in strip in Makefile (trips up Cygwin, which
          expects the executable to be foo.exe).
          Update feature list for remote sending.
          Internal changes to configuration storage.

   31/8/2008; release 63
          Update change list for release 62 (omitted some items...).
          Give a sensible warning message instead of dying with an
          exception when (1) signing operations are called without own key
          set; (2) attempting to choose own key without any secret keys
          available.
          Added some hints in the documentation.
          Initial attempt at supporting remote decryption.
          Handle SIGINT ourselves so that temporary files are cleaned up.
          Also clean up more often when exceptions occur.

   24/10/2008; release 64
          Update feature list for release 63's remote decryption support.
          Add patch to Topal sources for Cygwin. (The recent interrupt
          code doesn't build.)
          Bug fix: temporary files weren't being deleted, because
          Rm_Tempfiles_PID hadn't been changed to match Temp_File_Name.
          Added patch for Alpine 2.00. Alpine's S/MIME needs to be turned
          off for Topal's S/MIME verification to work.
          Bug fix in Externals.Simple.Guess_Content_Type.

   1/5/2009; release 65
          MIME sending now uses the current locale as the content-type
          header charset.
          MIME receiving (verification) tries to use the character set
          given in its first attempt.
          Signing calls to GPG use --textmode flag (shouldn't be needed if
          the dos2unix calls work, but experiments suggest some problems
          if we don't do this).
          Fix remote server so that emails with multiple recipients are
          handled properly.
          Added new patch to Alpine that might make it easier to read
          multipart signed/encrypted messages. This makes the procmail
          recipe redundant, but needs more testing.
          Attempt to manage different character sets when verifying
          S/MIME.
          MIME messages now include a prolog explaining that they're
          OpenPGP messages. Also added appropriate Content-Disposition
          headers to help client programs.
          Update docs re: Alpine patches.
          Code cleanup (e.g., vars that could be declared constant, and
          some unused procedure formals).

   6/6/2009; release 66
          Removed spurious spaces from Topal `-----' text that were
          messing up format=flowed text. Note that this doesn't fix cache
          files that already have this problem.
          Changed the default sending and receiving GPG options (use the
          -default option to see them). This does not override whatever is
          in your current .topal/config file.
          Added a configuration option `omit-inline-disposition-name':
          apparently some mail services mistreat inline MIME parts if they
          have a filename. If this option is set, then no filename
          parameter is added to inline content-disposition headers. The
          option can be changed via the configuration menu.

   6/6/2009; release 67
          Added another configuration option
          `omit-inline-disposition-header'. If a disposition header of
          value inline would be added, it's simply omitted altogether.

   27/6/2009; release 68
          Minor bug fix with configuration handling of
          omit-inline-disposition-header.
          Added new configuration option save-on-send.
          A range of major and minor changes to the sending interface.
          Added the sd configuration option that allows keys or emails to
          be associated with particularly sending options.
          When secret keys aren't available, still try to add a suitable
          key for self for encryption.
          MIME viewer setting has been replaced by two: one for decrypt
          and one for verify.
          Bad lines in the configuration file now result in a warning, not
          an exception.
          Internal modifications to configuration handling.

   21/7/2009; release 69
          No longer calling an external app for line-end conversions.
          Added a note re: Alpine's S/MIME message about certificates.
          Show the list of recipients just before sending (from the
          to/cc/bcc lists; not lcc, as Alpine doesn't pass those to in the
          _RECIPIENTS_ token). The idea is to allow the user to spot the
          "oh no, I didn't intend to email that person" problem.

   22/9/2009; release 70
          Added use-agent configuration option. This has three values: (1)
          never use an agent, (2) only use it for decryption, (3) always
          use it. Don't put GPG's --[no-]use-agent options in any other
          configuration options or it might be confusing.
          Adding attachments when using a non-MIME mode forces a change to
          a suitable mode (where possible).
          Presentation changes for recipient list check.
          Fixed a minor typo in a user message.

   25/2/2010; release 71
          Added more MICALGs from RFC4880.
          Handle missing Content-Type headers in multipart messages.
          Reorganise menus: hopefully, they're easier to read now. Add
          some colourisation (this can be disabled by setting
          ansi-terminal to off). Assorted tidying.
          Warn if sending defaults to encryption, but some keys are
          missing.
          Add -pd - pipe-display mode. Takes stdin and treats it as a MIME
          email for display/verification.
          Release code is now taken from the README.html file rather than
          a separate release file.
          Slight clean-up of this README.

   25/2/2010; release 72
          Fix menus for non-Pine sending. (`Go' 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.
     __________________________________________________________________