File: README.html

package info (click to toggle)
topal 72-1
links: PTS
area: main
in suites: squeeze
size: 1,004 kB
ctags: 102
sloc: ada: 9,192; ansic: 768; sh: 233; makefile: 148
file content (1623 lines) | stat: -rw-r--r-- 60,418 bytes
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>
Topal: GPG/GnuPG and Alpine/Pine integration
</title>
<style type="text/css">
body {
  font-family: Helvetica, Geneva, Arial,
        SunSans-Regular, sans-serif ;
  background-color: #fafffa }
a:link {
  color: blue }
a:visited {
  color: purple }
.navbar {
  text-align: center;
  font-size: x-small }
img.validator {
	float: right
}
.tail {
        text-align: center ;
        font-size: x-small ;
        float: none ;
        clear: both
}
</style>
</head>
<body>

<hr/>

<h1>Topal: GPG/GnuPG and Alpine/Pine integration</h1>

<p>Copyright (C) 2001--2010  Phillip J. Brooke</p>

<hr/>

<h2>Contents</h2>

<ul>
<li> <a href="#introduction">Introduction</a></li>
<li> <a href="#features">Features</a></li>
<li> <a href="#important-changes">Important changes from previous stable versions</a></li>
<li> <a href="#inst-and-config">Installation and configuration</a>
<ul>
<li> <a href="#comp-and-inst">Compilation and installation</a></li>
<li> <a href="#pine-patches">Pine/Alpine patches</a></li>
<li> <a href="#pine-config">Pine/Alpine configuration</a></li>
<li> <a href="#mailcap-config">Mailcap configuration</a></li>
<li> <a href="#topal-config">Topal configuration</a></li>
</ul></li>
<li> <a href="#topal-usage">Topal usage</a>
<ul>
<li> <a href="#topal-help">Help!</a></li>
<li> <a href="#config">Configuration</a></li>
<li> <a href="#decrypt-verify">Decryption/verification</a></li>
<li> <a href="#sending">Sending</a></li>
<li> <a href="#nonpine">Command-line usage</a>
<ul>
<li> <a href="#nps">Sending (<tt>-nps</tt>)</a></li>
<li> <a href="#pd">Receiving (<tt>-pd</tt>)</a><l/i>
</ul></li>
<li> <a href="#remote">Remote and server mode</a></li>
</ul></li>
<li> <a href="#fix-multipart">Fixing multipart emails</a></li>
<li> <a href="#notes">Notes</a>
<ul>
<li> <a href="#pinehack">The Pine/Alpine hack, and sending other attachments</a></li>
<li> <a href="#keyids">Key IDs and keylists</a></li>
<li> <a href="#sd">Sending defaults</a></li>
<li> <a href="#errors">Errors</a></li>
<li> <a href="#decrypt-attachments">Decrypting attachments</a></li>
<li> <a href="#locale-problems">Locale problems</a></li>
<li> <a href="#couldnt-find-cert">“Couldn't find certificate needed to sign.”</a></li>
<li> <a href="#cleaning-cache">Cleaning up the cache</a></li>
<li> <a href="#remote-notes">Remote and server mode</a></li>
<li> <a href="#agent">Working with GPG Agent</a></li>
<li> <a href="#new-releases">New releases</a></li>
<li> <a href="#release-numbering">Release numbering</a></li>
<li> <a href="#hints">Hints</a></li>
</ul></li>
<li> <a href="#author">Author</a></li>
<li> <a href="#licence">Licence</a></li>
<li> <a href="#todo">To do</a></li>
<li> <a href="#changes">Version history</a>
<ul>
<li> <a href="#last-changes">Most recent changes</a></li>
</ul></li>
</ul>

<hr/>

<h2><a name="introduction">Introduction</a></h2>

<p>Topal is a &#x2018;glue&#x2019; program that links 
<a href="http://www.gnupg.org">GnuPG</a>
and 
<a href="http://www.washington.edu/pine/">Pine</a>/<a href="http://www.washington.edu/alpine/">Alpine</a>.  It offers
facilities to encrypt, decrypt, sign and verify emails.   It
can also be used directly from the command-line.
</p>

<p>
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.
</p>

<p>See the list
of <a href="#features">features</a> below.
</p>

<hr/>

<h2><a name="features">Features</a></h2>

<!-- Don't remove the next line - or its counterpart later on! -->
<!-- FL -->

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

<!-- FL -->

<hr/>

<h2><a name="important-changes">Important changes from previous stable versions</a></h2>

<p>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.</p>

<h3>Important changes in release 70</h3>

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

<h3>Important changes in release 68</h3>

<ul>
<li>
The sending interface has changed.  Selecting (for example) &#x2018;e&#x2019; for
encrypt no longer immediately operates.  Instead, the desired
operation is chosen, and then &#x2018;g&#x2019; for &#x2018;Go!&#x2019; is used.  This allows
defaults to be associated with keys and email addresses in a sensible way.
</li>
<li>
The MIME viewer setting <tt>mime-viewer</tt> 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.)
</li>
</ul>

<h3>Important changes in release 65</h3>

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

<h3>Important changes in release 60</h3>

<ul>
<li>MIME sending now requires MIME-tool; mime-construct is no longer
used.  See <a href="#comp-and-inst">compilation and installation</a>.</li>
</ul>

<h3>Important changes in release 58</h3>

<ul>
<li>The default configuration no longer uses absolute paths.</li>
</ul>

<h3>Important changes in release 55</h3>

<ul>
<li>If you use a non-English locale, please check that Topal still
works as expected (replaced code that fixed some locale
problems).</li>
<li>The Alpine patch is based off my old Pine patches, but does a
little more.  You will need to set the <tt>Enable Topal hack for
OpenPGP/MIME messages</tt> option in the hidden configuration list. Bug
reports welcome.</li>
<li>The <tt>--fix-email</tt> 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.</li>
</ul>

<h3>Important changes in version 0.7.10</h3>

<p>The recommended procmail recipe has been changed.</p>

<h3>Important changes in version 0.7.8</h3>

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

<p>You <em>must</em> 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 <tt>topal
-config</tt>).</p>

<p>
Finally, the send menu has a new option: &#x2018;Pass through unchanged&#x2019;.
This does nothing to the message so, you can
always have Topal invoked as a filter for sending.
</p>

<hr/>

<h2><a name="inst-and-config">Installation and configuration</a></h2>

<h3><a name="comp-and-inst">Compilation and installation</a></h3>

<p>
To compile Topal, you need
</p>
<ul>
<li> a working C compiler, </li>
<li> the GNU Ada
Compiler (GNAT), and </li>
<li> some common libraries, including readline (e.g., the package
  libreadline5-dev on Debian).</li>
</ul>
<p>There is a makefile: simply type <tt>make</tt>.
Type <tt>make install</tt> to actually install.  The default location
is /usr, so you'll need to be root to install.  Alternatively, use
<tt>make install INSTALLPATH=/usr/local</tt> to install into
/usr/local.  (Or use the more specific variables INSTALLPATHBIN,
INSTALLPATHMAN, INSTALLPATHDOC and INSTALLPATHPATCHES.)
</p>

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

<h4>MIME sending</h4>

<p>
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 <a href="#pine-patches">Pine/Alpine patches</a> below.
</p>

<h4>MIME viewing</h4>

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

<h3><a name="pine-patches">Pine/Alpine patches</a></h3>

<p>
For <tt>-sendmime</tt> to work, you will need to patch
  Pine/Alpine.</p>

<p>There are patches
for versions 
<a href="pine-4.44.patch">4.44</a>,
<a href="pine-4.50.patch">4.50</a>,
<a href="pine-4.53.patch">4.53</a>,
<a href="pine-4.58.patch">4.58</a>.
<a href="pine-4.60.patch">4.60</a>
and
<a href="pine-4.64.patch">4.64</a>
of Pine.  (They're all more-or-less the same patch.)
<tt>cd</tt> into the pine4.<i>xx</i> directory and use the 
<tt>patch</tt>  command.
</p>

<p>
There are patches for Alpine: versions 
<a href="alpine-1.00.patch">1.00</a>,
<a href="alpine-1.10.patch">1.10</a>
and
2.00 (<a href="alpine-2.00.patch-1">patch 1</a> 
and <a href="alpine-2.00.patch-2">patch 2</a>).
Please note that the Alpine patches also modify Alpine's
configuration.  There is a hidden preference &#x2018;enable Topal hack&#x2019;
(enable-topal-hack) that you need to switch on.
</p>

<p>
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 &#x2018;<tt>-d 9</tt>&#x2019;).
</p>

<h3><a name="pine-config">Pine/Alpine configuration</a></h3>

<p>
Assuming that the topal binary is installed in /usr/bin, set up
the Pine/Alpine sending and display filters as follows:
</p>
<pre>
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_
</pre>
<p>
You can choose either or both of the sending filters.  The <tt>-sendmime</tt>
option allows the user to choose the MIME type of the outbound
email. (Legacy fixes are in place that make <tt>-decrypt</tt> and <tt>-verify</tt>
behave the same as <tt>-display</tt>.)  Note that
<tt>_RECIPIENTS_</tt> should be last.
</p>



<p>
You can also add <tt>--read-from _INCLUDEALLHDRS_</tt> before
<tt>-send</tt> and <tt>-sendmime</tt>.  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.
</p>

<h3><a name="mailcap-config">Mailcap configuration</a></h3>

<p>
To decode MIME RFC2015/3156 multipart/signed and /encrypted messages
requires the assistance of metamail.  Add in either the user mailcap
configuration (<tt>.mailcap</tt>) or the system configuration
(<tt>/etc/mailcap</tt>) the lines
</p>
<pre>
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
</pre>

<h3><a name="procmail-config">Procmail configuration</a></h3>

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

<p>
In your procmailrc, add the recipe:
</p>
<pre>
:0fw
| /usr/bin/topal --fix-email
</pre>
<p>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.</p>
<p>
I <em>strongly</em> advise that you also use one of the backup
recipes from the procmail manual.  See also the notes in 
<a href="#fix-multipart">fixing multipart emails</a>.
</p>

<h3><a name="topal-config">Topal configuration</a></h3>

<p>
Create a directory called &#x2018;<tt>${HOME}/.topal</tt>&#x2019;.  This is
currently hard-coded into Topal.  Create the basic configuration file
by running topal with the <tt>-dump</tt> or <tt>-default</tt> options.
This file should be named &#x2018;<tt>config</tt>&#x2019;.
</p>

<p>
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.
</p>

<p>
If you want to include strings with spaces, you'll need to quote them
with double-quotes (<tt>"</tt>).  Double-quotes themselves can be
included by &#x2018;stuffing&#x2019; (<tt>""</tt>).
</p>

<hr/>

<h2><a name="topal-usage">Topal usage</a></h2>

<h3><a name="topal-help">Help!</a></h3>

<p>
<tt>-help</tt> as the first argument dumps a help message.
</p>

<p>
The help message is derived from the <tt>help.txt</tt> file (included at
compile time).
</p>

<p>
See <tt>help.txt</tt> for information on <a href="#nonpine">non-Pine use of Topal</a>.
</p>

<p>
Send <a href="#author">email to me</a> if you're really stuck.
</p>

<h3><a name="config">Configuration</a></h3>

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

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

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

<p>
Colours were introduced in release 71.  If you want to turn them off,
set <tt>ansi-terminal=off</tt> in the  <tt>config</tt> file.  You can
change the colours by setting 
<tt>colour-menu-title</tt>,
<tt>colour-menu-key</tt>,
<tt>colour-menu-choice</tt>,
<tt>colour-important</tt>,
<tt>colour-banner</tt> and
<tt>colour-info</tt>.  The codes are the escape codes (see, for
example, colour table in the <a href="http://en.wikipedia.org/wiki/ANSI_escape_code">Wikipedia article on ANSI escape codes.</a>).
</p>

<h3><a name="decrypt-verify">Decryption/verification</a></h3>

<p>
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.
</p>

<p>
GPG will ask you for your passphrase when it needs it.
</p>

<p>
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.
</p>

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

<p>
A new option (for version 0.7.8) called <tt>inline-separate-output</tt>
concerns inlined (i.e., not MIME) messages.  If the option is on, then
the Topal/GnuPG output will be shown to you by <tt>less</tt>.  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 <tt>q</tt> an awful lot....
</p>

<h3><a name="sending">Sending</a></h3>

<h4>Main send menu</h4>

<p>
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 <tt>-sendmime</tt> option.
</p>

<pre>
** Main send menu:
 Sending mode: No GPG                            
               Inline plain          
 Signing key: 9DAF9B5C 2005-10-21 Dr Phil Brooke <pjb@scm.tees.ac.uk>
 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!
</pre>

<p>
&#x2018;Abort&#x2019; tells Pine/Alpine you don't want Topal to process the email anymore.
</p>

<p>
&#x2018;Pass through unchanged&#x2019; does nothing to the message.  This means that
you can always have Topal invoked for sending.
</p>

<p>
&#x2018;Add own key&#x2019; adds an &#x2018;encrypt to self&#x2019; key.  (It is added by default,
but if you remove it, this is a quick way to restore it.)
</p>

<p>
When you select &#x2018;Go!&#x2019; you will be asked to confirm the command-line,
and after processing, <tt>less</tt> is invoked to visually check that
the desired result has been achieved.  Again, a confirmation is asked
for.
</p>

<p>
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 &#x2018;clearsign&#x2019; and
&#x2018;multipart/*&#x2019;, then all trailing blank lines will be deleted.  Note
also that Pine/Alpine appears to delete trailing whitespace in
trailing blank lines.)
</p>

<p>
&#x2018;Configuration&#x2019; offers the same menu that is available from the
<tt>-config</tt> option.
</p>

<h4>List current recipient keys</h4>

<p>
&#x2018;List current recipient keys&#x2019; offers a list of recipients:
</p>
<pre>
** 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 <pjb@scm.tees.ac.uk>                 
</pre>
<p>
&#x2018;Quit and return to main send menu&#x2019; sends you back to the first menu. 
</p>

<p>
&#x2018;Add key from main keyring&#x2019; prompts you for a search pattern.  It will
do a general search on your GPG keyring <em>and add</em> all matching keys.  Beware of just pressing
enter - it will select <em>all</em> keys on your keyring.
</p>

<p>
A better alternative is to use the &#x2018;select after search&#x2019; 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.
</p>

<h4>Examine key menu</h4>

<p>
Selecting a key will offer a third menu (a similar menu is offered
when selecting a single key):
</p>
<pre>
** Examining key currently in key list:
Key: 9DAF9B5C 2005-10-21 Dr Phil Brooke <pjb@scm.tees.ac.uk>                 
[d] Display details of key with less   [v] Verbosely
[r] Remove key from list               [kql] Return to key list  
</pre>
<p>
&#x2018;Return to key list&#x2019; takes you back to the second menu.  
</p>

<p>
&#x2018;Display details of key (less)&#x2019; simply uses GPG to list the
key details via <tt>less</tt>.  You'll need to use &#x2018;q&#x2019; to get out of <tt>less</tt>.
</p>

<p>
&#x2018;Verbose details of key (less)&#x2019; pipes verbose output from GPG for this
key into gpg.  You'll need to use &#x2018;q&#x2019; to get out of <tt>less</tt>.
</p>

<p>
&#x2018;Remove key from list&#x2019; removes the key from this recipient list.
</p>

<h3><a name="nonpine">Command-line usage</a></h3>

<h4><a name="nps">Sending (<tt>-nps</tt>)</a></h4>

<p>
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.  <em>You have a choice of overwriting or
preserving the original file (this bit is case-sensitive).</em>  So <tt>e</tt>,
<tt>s</tt>, <tt>c</tt> are different from <tt>E</tt>, <tt>S</tt>, <tt>C</tt>.
</p>
<pre>
** Main send menu:
 Sending mode: No GPG                            
 Signing key: 9DAF9B5C 2005-10-21 Dr Phil Brooke <pjb@scm.tees.ac.uk>
 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)
</pre>

<p>
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.
</p>

<p>
MIME functions are not available in this mode: it makes no sense.
</p>

<h4><a name="pd">Receiving (<tt>-pd</tt>)</a></h4>

<p>Invoking Topal with only <tt>-pd</tt> 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. </p>

<p>(New in release 71.)</p>

<h3><a name="remote">Remote and server mode</a></h3>

<p>
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 &#x2018;server&#x2019; mode to run on the local
computer (with access to the secret key) and a remote option in the
sending menu.
</p>

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

<p>
When sending, you can choose &#x2018;remote&#x2019;.  This prompts for the host to
connect to using ssh/scp: this host should be running the &#x2018;server&#x2019;.
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.
</p>

<p>
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.
</p>

<hr/>

<h2><a name="fix-multipart">Fixing multipart emails</a></h2>

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

<p>
<tt>topal --fix-email</tt> 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.  
</p>

<p>
Usage: 
</p>
<dl>
<dt><tt>topal --fix-folder</tt> &lt;folder&gt; ...</dt> <dd>This fixes the old
email folders you may have.</dd>
<dt><tt>topal --fix-email</tt></dt> <dd>Takes no arguments; it accepts a single
email on stdin.  Ideally, it should be invoked by procmail (see the
<a href="#procmail-config">configuration section</a> above).</dd>
</dl>

<p>
<tt>topal --fix-email</tt> has a simpler mode (<tt>--simple</tt>) where it
pretends that there are two MIME content types:
&#x2018;application/x-topal-encrypted&#x2019; and &#x2018;application/x-topal-signed&#x2019;.  You
might prefer using this.
</p>

<p>Why do we need this?  If we just set the <tt>.mailcap</tt> 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 &#x2018;Can't find body for requested message&#x2019; is seen.  But
multipart/signed inside a multipart/mixed (or multipart/alternative,
etc.) can be successfully handed-off to Topal.</p>

<p>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....</p> 

<p>See <tt>Workaround.Fix_Email</tt> in the sources for more details.</p>

<hr/>

<h2><a name="notes">Notes</a></h2>

<h3><a name="pinehack">The Pine/Alpine patches, and sending other attachments</a></h3>

<p>
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.
</p>

<p>
The patch instead adds a flag, &#x2018;topal_hack&#x2019;, 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.
</p>

<p>
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.
</p>

<h3><a name="keyids">Key IDs and keylists</a></h3>

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

<p>
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).
</p>

<p>
The way that Topal chooses the keys is as follows:
</p>
<ul>
<li>  For each recipient email address (supplied by Pine)
<ol>
<li>    For each matching line in keylist, use the key ID to get a fingerprint, and add the key to the list.</li>
<li>    In there are no matching lines in keylist, try to get a
fingerprint via just that email address (but exclude &#x2018;xk&#x2019;
configuration entries).</li>
</ol></li>
</ul>

<p>
The keylist is a way to say, &#x2018;for this particular email address, use
this particular key&#x2019;.  In your <tt>config</tt> file, include lines
such as
</p>
<pre>
ake=50973B91,philb@soc.plym.ac.uk
ake=50973B91,pjb@lothlann.freeserve.co.uk
</pre>
<p>These mean &#x2018;use key 50973B91 for the given email addresses&#x2019;.
Similarly,</p>
<pre>
xk=50973B91
</pre>
<p>means &#x2018;don't use key 50973B91&#x2019;.  There are also similar
<tt>sake</tt> and <tt>sxk</tt> options for the secret key selection
(via <tt>--read-from</tt>) (although the testing of the secret key
listings is less thorough so far).</p>


<h3><a name="sd">Sending defaults</a></h3>

<p>
The <tt>sd</tt> expressions can assign a default to a key ID or email address.
The special expression <tt>@ANY@</tt> matches any email address (or
key).
The last matching <tt>sd</tt> expression applies.
</p>
<ul>
<li><tt>n</tt>: no GPG</li>
<li><tt>e</tt>: encrypt</li>
<li><tt>s</tt>: sign and encrypt</li>
<li><tt>c</tt>: clearsign</li>
<li><tt>I</tt>: inline plain</li>
<li><tt>A</tt>: app pgp</li>
<li><tt>M</tt>: multipart</li>
<li><tt>E</tt>: multipart encapsulated</li>
</ul>
<p>Example: the following means that the default settings for the
given address are encrypted and inline plain.</p>
<tt>sd=pjb@lothlann.freeserve.co.uk,eI</tt>

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

<p>(New in release 68.)</p>

<h3><a name="errors">Errors</a></h3>

<p>
Bad things happening should result in Topal setting its exit status to
&#x2018;failed&#x2019;, so Pine should detect this and not send your email.
</p>

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

<h3><a name="decrypt-attachments">Decrypting attachments</a></h3>

<p>
If an attachment is a plaintext PGP ASCII-armoured message, then Topal
will be invoked by Pine.  You probably want to say &#x2018;no&#x2019; 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.
</p>

<h3><a name="locale-problems">Locale problems</a></h3>

<p>
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).  
</p>

<p>
I currently have no way to automatically fix this.  However, the
<tt>--ask-charset</tt> 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.)
</p>

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

<h3><a name="couldnt-find-cert">“Couldn't find certificate needed to sign.”</a></h3>

<p>
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").
</p>


<h3><a name="cleaning-cache">Cleaning up the cache</a></h3>

<p>
You might want to run something like
</p>
<pre>
find ${HOME}/.topal/cache -mtime +7 | xargs rm
</pre>
<p>
to remove all the cache files that are a bit old (in this example, 7
days old or older).
</p>

<h3><a name="remote-notes">Remote and server mode</a></h3>

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

<p>
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.
</p>

<h3><a name="agent">Working with GPG Agent</a></h3>

<p>
The <tt>use-agent</tt> 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 <tt>--[no-]use-agent</tt> options in any other
configuration options.
</p>


<h3><a name="new-releases">New releases</a></h3>

<p>To be notified of new releases of Topal, send an email to me.</p>

<h3><a name="release-numbering">Release numbering</a></h3>

<p>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.</p>

<h3><a name="hints">Hints</a></h3>

<ul>
<li>Consider using GPG's <tt>--trusted-key</tt> option in Topal's
gpg-options configuration setting.  This is useful if you keep your secret keys offline.</li>
<li>Use the <a href="#pine-config"><tt>--read-from</tt></a> option, especially if you use multiple roles.</li>
</ul>

<hr/>

<h2><a name="author">Author</a></h2>

<p>
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. 
</p>

<p>
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 <a href="#todo">&#x2018;To do&#x2019; list</a> are important to you, let me know.  In
particular, if you find bugs, feel free to tell me the details by
email.
</p>

<p>
This package is released under the GPL: see the file <a href="COPYING">COPYING</a>.
</p>

<p>
I can be emailed on 
<a href="mailto:pjb@lothlann.freeserve.co.uk"><tt>pjb@lothlann.freeserve.co.uk</tt></a>
</p>

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

<p>
If you want to send snailmail to me, email me for my (physical) address.
</p>

<hr/>

<h2><a name="licence">Licence</a></h2>

<p>
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.
</p>
<p>
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.
</p>
<p>
You should have received a copy of the GNU General Public License
along with this program.  If not, see <a href="http://www.gnu.org/licenses/">http://www.gnu.org/licenses/</a>.
</p>

<hr/>

<h2><a name="todo">To do...</a></h2>

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

<hr/>

<h2><a name="changes">Version history</a></h2>

<p>Look in <a href="release">release</a> for the current release number.</p>

<dl>
<dt>06/2001, 0.1</dt> <dd>First alpha release.</dd>

<dt>06/2001, 0.2</dt> <dd>Minor changes.</dd>

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

<dt>06/2001, 0.4</dt> <dd>Adding more customization features.</dd>

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

<dt>11/2001, 0.4.5</dt> <dd>Added &#x2018;gpg-options&#x2019; config item with
default &#x2018;--no-options&#x2019;.  (Forgot to add this note as well....)</dd>

<dt>11/2001, 0.5.0</dt> <dd>Dumped -verify and -decrypt modes in
favour of the multiple-block &#x2018;-display&#x2019; mode.  Added -help.  Added
caching.  Added more switches relating to caching.  Better output
formatting.</dd>

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

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

<dt>12/2001, 0.5.3</dt> <dd>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.  </dd>

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

<dt>12/2001, 0.5.5</dt> <dd>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).</dd>

<dt>12/2001, 0.5.6</dt> <dd>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 &#x2018;fast continue&#x2019; 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.</dd>

<dt>2/2002, 0.5.7</dt> <dd>Adding limited RFC2015/MIME decoding of
multipart email.</dd>

<dt>2/2002, 0.5.8</dt> <dd>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).</dd>

<dt>3/2002, 0.6.0</dt> <dd>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).  <br/> 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.<br/>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.<br/>-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.<br/>Removed some of the waits for execution,
since it seems reliable.  Added error checking on return value of GPG
in sends.</dd>

<dt>3/2002, 0.6.1</dt> <dd>The Content-Type for MIME sending is
displayed on the screen using &#x2018;cat&#x2019; rather than &#x2018;less&#x2019;, which was
getting to be annoying.<br/>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&lt;symbolic-name&gt; to tag the
released files.</dd>

<dt>3/2002, 0.6.2</dt> <dd>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.</dd>

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

<dt>4/2002, 0.6.4</dt> <dd>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.</dd>

<dt>5/2002, 6/2002; 0.6.5, 0.6.6, 0.6.7, 0.6.8</dt> <dd>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.</dd>

<dt>7/2002, 0.6.9</dt><dd>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 &#x2018;-s&#x2019;.  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 &#x2018;less&#x2019; it (instead of firing up a HTML reader) can do so.</dd>

<dt>8/2002, 0.7.0</dt><dd>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 &#x2018;bug&#x2019; (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.</dd>

<dt>8/2002, 0.7.1</dt><dd>Fixed minor bug with inverted return code
(&#x2018;-s&#x2019; trap).  Doc update.</dd>

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

<dt>9/2002; 0.7.3, 0.7.4 (BETA)</dt><dd>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.</dd>

<dt>9/2002; 0.7.5 (BETA)</dt><dd>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.</dd>

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

<dt>10/2002; 0.7.7 (BETA)</dt><dd>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 &#x2018;important changes from last stable
version&#x2019; 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 &#x2018;pass-thu&#x2019; 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.</dd>

<dt>10/2002; 0.7.8</dt><dd>Clearing out case statements with &#x2018;when
others&#x2019;.  Tidying up sending.adb.  Fixed problem in MIME output where
a leading blank line was added.  Finally implemented &#x2018;topal
--fix-folders&#x2019; functionality added.  No longer need the two old
scripts (I hope)!  Another documentation tidy-up.  Added
&#x2018;inline-separate-output&#x2019; 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.
</dd>

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

<dt>2/2003; 0.7.10, 0.7.11</dt><dd>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 &#x2018;-&#x2019; 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.
</dd>

<dt>2/2003; 0.7.12</dt><dd>Adding &#x2018;workaround-error-log&#x2019; 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.
</dd>

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

<dt>4/2003; 0.7.13b</dt><dd>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.  </dd>

<dt>10/2003; 0.7.13.2</dt><dd>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: &#x2018;relocation error: /lib/libreadline.so.4:
undefined symbol: BC&#x2019; (needed instruction to link against ncurses) -
thanks to Marty Hoff for the bug report. Added patch against Pine
version 4.58.</dd>

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

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

<dt>6/2004; 0.7.13.5</dt><dd>Added patch against Pine version
4.60.  Updated some notices.</dd>

<dt>1/4/2005; 0.7.13.6</dt><dd>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.</dd>

<dt>2005-2007</dt><dd>Four internal development releases junked.</dd>

<dt>8/1/2008; release 55</dt><dd>
<tt>--fix-email</tt> now replaces the original message with a
multipart/misc wrapper, rather than expanding it into a
multipart/alternative message.
<br/>
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.
<br/>
New patch for Alpine 1.00.  Includes configuration setting.
<br/>
The &#x2018;pass through unchanged&#x2019; send option no longer modifies the
content-type to text/plain.
<br/>
Should now build and run on Cygwin.
<br/>
Licence is now GPL-3.
<br/>
Attempt to prevent potential memory leak (if running for a long time)
by making the implementation of <tt>expanding_array</tt> a controlled type.
<br/>
Cleaned up Ada source to reduce warnings.
<br/>
Other minor changes, e.g., better checks on keylists, documentation clean-up.
<br/>
Changed <a href="#release-numbering">release numbering</a>.
<br/>
HTML cleaned up and CSS added.</dd>

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

<dt>8/1/2008; release 57</dt><dd>
Initial attempt at supporting attachments within Topal.
<br/>
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....
<br/>
Bug fix to _INCLUDEALLHDRS_ - it needs to turn the CRLF back into LF
or it might chop off some of your message....
</dd>
<dt>22/6/2008; release 58</dt><dd>
UI improvements (count keys in keylist, clearer indication of position
in menus).
<br/>
Added patch for Alpine 1.10.  Renamed all patch files.
<br/>
Default paths for binaries are no longer absolute.  
<br/>
Configuration files now allow comments, but they're not preserved by Topal.
<br/>
Added more exception handling messages.
<br/>
Sending and receiving both save off original input as tempfiles to
help debugging.
<br/>
Added --ask-charset command line option.  This is really only for
testing a new workaround for locale-related bad signatures.  Please
see <a href="#locale-problems">locale problems</a> in the notes and
send feedback.
<br/>
Started removing dependency on mime-construct; new source files mime.ad[sb].
<br/>
Build date added to binary.
</dd>
<dt>3/7/2008; release 59</dt><dd>
Added sequence numbers to temporary files to reduce possible name
conflicts.
<br/>
The makefile's install target now installs to INSTALLPATH.  This can
be overridden, e.g., <tt>make install INSTALLPATH=/usr/local</tt>.
The four more specific paths, INSTALLPATHBIN, INSTALLPATHMAN,
INSTALLPATHDOC and INSTALLPATHPATCHES can also be overridden.  Fixes
request from Nils Schlupp re: ebuild.
<br/>
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.
</dd>
<dt>13/7/2008; release 60</a></dt><dd>
Update installation instructions for make install.
<br/>
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).
<br/>
MIME viewing can now use metamail, use run-mailcap or save the attachment to the
folder <tt>~/.topal/viewmime</tt> (which you can then open in
Alpine).  run-mailcap and saving support are new.
<br/>
Sending menu allows user to view and edit the email.  A quicker
method for changing/setting the signing (own) key is available.
</dd>
<dt>14/7/2008; release 61</dt><dd>
An initial, rather crude, but (for my purposes at least) effective
remote mode for sending.
<br/>
Some history is now saved.
</dd>
<dt>17/7/2008; release 62</dt><dd>
Added basic support for S/MIME verification of messages.
<br/>
Quoted-printable encoder (in MIME-tool) improved (single dots and
leading "From ") as per RFC2049.
<br/>
Decode quoted-printable and base64 before calling run-mailcap.
<br/>
Ignore errors in strip in Makefile (trips up Cygwin, which expects the
executable to be foo.exe).
<br/>
Update feature list for remote sending.
<br/>
Internal changes to configuration storage.
</dd>
<dt>31/8/2008; release 63</dt><dd>
Update change list for release 62 (omitted some items...).
<br/>
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.
<br/>
Added some hints in the documentation.
<br/>
Initial attempt at supporting remote decryption.
<br/>
Handle SIGINT ourselves so that temporary files are cleaned up.  Also
clean up more often when exceptions occur.
</dd>
<dt>24/10/2008; release 64</dt><dd>
Update feature list for release 63's remote decryption support.
<br/>
Add patch to Topal sources for Cygwin. (The recent interrupt code
doesn't build.)
<br/>
Bug fix: temporary files weren't being deleted, because
Rm_Tempfiles_PID hadn't been changed to match Temp_File_Name.
<br/>
Added patch for Alpine 2.00.   Alpine's S/MIME needs to be turned off
for Topal's S/MIME verification to work.
<br/>
Bug fix in Externals.Simple.Guess_Content_Type.
</dd>
<dt>1/5/2009; release 65</dt><dd>
MIME sending now uses the current locale as the content-type header charset.
<br/>
MIME receiving (verification) tries to use the character set given in
its first attempt.
<br/>
Signing calls to GPG use <tt>--textmode flag</tt> (shouldn't be needed
if the dos2unix calls work, but experiments suggest some problems if
we don't do this).
<br/>
Fix remote server so that emails with multiple recipients are handled
properly.
<br/>
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.
<br/>
Attempt to manage different character sets when verifying S/MIME.
<br/>
MIME messages now include a prolog explaining that they're OpenPGP
messages.  Also added appropriate Content-Disposition headers to help
client programs.
<br/>
Update docs re: Alpine patches.
<br/>
Code cleanup (e.g., vars that could be declared constant, and some
unused procedure formals).
</dd>
<dt>6/6/2009; release 66</dt><dd>
Removed spurious spaces from Topal &#x2018;-----&#x2019; text that were messing up
format=flowed text.  Note that this doesn't fix cache files that
already have this problem.
<br/>
Changed the default sending and receiving GPG options (use
the <tt>-default</tt> option to see them).  This does not override
whatever is in your current <tt>.topal/config</tt> file.
<br/>
Added a configuration option &#x2018;omit-inline-disposition-name&#x2019;:
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.
</dd>
<dt>6/6/2009; release 67</dt><dd>
Added another configuration option &#x2018;omit-inline-disposition-header&#x2019;.
If a disposition header of value inline would be added, it's simply
omitted altogether.
</dd>

<!-- Don't remove the next line - or its counterpart later on! -->
<!-- MRC -->

<dt>27/6/2009; release 68</dt><dd>
Minor bug fix with configuration handling of
omit-inline-disposition-header.
<br/>
Added new configuration option save-on-send.
<br/>
A range of major and minor changes to the sending interface.
<br/>
Added the sd configuration option that allows keys or emails to be
associated with particularly sending options.
<br/>
When secret keys aren't available, still try to add a suitable key for
self for encryption.
<br/>
MIME viewer setting has been replaced by two: one for decrypt and one
for verify.
<br/>
Bad lines in the configuration file now result in a warning, not an exception.
<br/>
Internal modifications to configuration handling.
</dd>
<dt>21/7/2009; release 69</dt><dd>
No longer calling an external app for line-end conversions.
<br/>
Added a note re: Alpine's S/MIME message about certificates.
<br/>
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.
</dd>
<dt>22/9/2009; release 70</a></dt><dd>
Added <tt>use-agent</tt> 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 <tt>--[no-]use-agent</tt> options in any other
configuration options or it might be confusing.
<br/>
Adding attachments when using a non-MIME mode forces a change to a
suitable mode (where possible).
<br/>
Presentation changes for recipient list check.
<br/>
Fixed a minor typo in a user message.
</dd>
<dt>25/2/2010; release 71</a></dt><dd>
Added more MICALGs from RFC4880.
<br/>
Handle missing Content-Type headers in multipart messages.
<br/>
Reorganise menus: hopefully, they're easier to read now.
Add some colourisation (this can be disabled by
setting <tt>ansi-terminal</tt> to <tt>off</tt>).
Assorted tidying.
<br/>
Warn if sending defaults to encryption, but some keys are missing.
<br/>
Add -pd - pipe-display mode.  Takes stdin and treats it as a MIME
email for display/verification.
<br/>
Release code is now taken from the <tt>README.html</tt> file rather
than a separate <tt>release</tt> file.
<br/>
Slight clean-up of this README.
</dd>
<dt><a name="last-changes"/>25/2/2010; release 72</a></dt><dd>
Fix menus for non-Pine sending.  (‘Go’ wasn't working!)
<br/>
Trap attempts to encrypt when no keys are in the key list.
<br/>
Minor change to distrib text and Makefile.
<br/>
Distrib target in Makefile now uses GPG agent.
</dd>
<!-- MRC -->
</dl>

<hr/>

</body>
</html>