~ubuntu-branches/ubuntu/precise/topal/precise

% Topal: GPG/GnuPG and Alpine/Pine integration
% Copyright (C) 2001--2012  Phillip J. Brooke
% 
% 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/>.

\documentclass[a4paper,twoside,12pt,openright]{report}

\usepackage[utf8]{inputenc}
\usepackage{palatino,fancyhdr,amssymb,textcomp,txfonts,paralist}
\newcommand{\eg}{\textit{e.g.}}
\newcommand{\etc}{\textit{etc.}}
\newcommand{\ie}{\textit{i.e.}}
\newcommand{\vv}{\textit{vice versa}}
\usepackage[hyphens]{url}
\usepackage{hyphenat}
\usepackage{graphicx}
\renewcommand\familydefault{\sfdefault}
\usepackage{listings}
\lstset{language=,columns=fullflexible,escapechar=\%,keepspaces=true}
\lstset{basicstyle=\small\ttfamily}
\lstdefinestyle{type}{backgroundcolor=\color{green},showspaces=true}
\lstdefinestyle{response}{backgroundcolor=\color{yellow}}

\input{versionid.tex}

% Don't like Courier.
\usepackage[T1]{fontenc}
\usepackage{textcomp}
\usepackage{beramono}

\newcommand{\vefill}{\vspace*{\fill}}

\newcounter{saveenumi}
\newcommand{\saveenumi}{\setcounter{saveenumi}{\theenumi}}
\newcommand{\restoreenumi}{\setcounter{enumi}{\thesaveenumi}}

\newenvironment{enumerateleg}{\begin{enumerate}[(a)]}{\end{enumerate}}

\newlength{\Oldparindent}
\setlength{\Oldparindent}{\parindent}

% Maxwidth, from http://www.tex.ac.uk/cgi-bin/texfaq2html?label=grmaxwidth
\makeatletter
\def\maxwidth{%
  \ifdim\Gin@nat@width>0.9\linewidth
    0.9\linewidth
  \else
    \Gin@nat@width
  \fi
}
\makeatother

% Screenshot figures.  The filename and the caption.
\newcommand{\SSF}[2]{
\begin{figure}[htp!]
\centering
\fbox{\parbox{0.9\linewidth}{  \centering
  \includegraphics[width=\maxwidth]{screens/#1}
  \caption{#2}\label{fig:#1}}}

\end{figure}
(figure~\ref{fig:#1})}

\usepackage[bookmarksopen=true,bookmarksopenlevel=1,
  bookmarksnumbered=true,
  colorlinks=true, urlcolor=blue,
  breaklinks=true,
  pdftitle={Topal manual},
  pdfauthor={Phil Brooke},
  pdfsubject={Topal},
  pdfkeywords={Topal, Pine, Alpine, OpenPGP, SMIME, GnuPG}
]{hyperref}

% Footing.
\fancyfoot{}
\fancyfoot[RO,LE]{\thepage}


\begin{document}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Title page/front cover
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\pagestyle{empty}

\begin{titlepage}

  \pdfbookmark[1]{Title page}{pdf:titlePage}
  \setlength{\parindent}{0pt}
  \raggedright

  {\Huge\bf\scshape Topal\\\bigskip\large GPG/GnuPG and Alpine/Pine integration}\\[10ex]


  {\Large Phil Brooke
  }

  \vfill

     Release~\TopalRelease\\ 
     \TopalBuildDate

  \setlength{\parindent}{\Oldparindent}

\end{titlepage}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Inside front cover.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


\vefill
  \setlength{\parindent}{0pt}

  {


Topal: GPG/GnuPG and Alpine/Pine integration

Copyright \copyright~ 2001--2012  Phillip J. Brooke

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 \url{http://www.gnu.org/licenses/}.
}

  \setlength{\parindent}{\Oldparindent}


\cleardoublepage

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Front matter, ToC, LoF, ...
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\pagestyle{fancy}
\renewcommand{\headrulewidth}{0pt}
\fancyhead{}

\pagenumbering{roman}
\setcounter{page}{1}

\pdfbookmark[1]{Table of contents}{pdf:TOC}
\tableofcontents

\cleardoublepage


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Main matter.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\pagenumbering{arabic}
\setcounter{page}{1}



\chapter{Introduction \& features}

Topal is a ‘glue’ program that links 
\href{http://www.gnupg.org}{GnuPG}
and 
\href{http://www.washington.edu/pine/}{Pine}/%
\href{http://www.washington.edu/alpine/}{Alpine}/%
\href{http://sourceforge.net/projects/re-alpine/}{``Re-Alpine'' (from
 Sourceforge)}.
It offers
facilities to encrypt, decrypt, sign and verify emails, including
inline OpenPGP, MIME/OpenPGP and S/MIME.   It
can also be used directly from the command-line.

\section{Features}

\begin{itemize}
\item Multiple inline PGP blocks can be processed in display filters.
\item Decryption and verification output can be cached to reduce the
  number of times a passphrase is entered\footnote{Note that you should also
  consider the use of \texttt{gpg-agent}.}.  This also helps when
  secret keys aren't always available, at the expense of storing
  decrypted output.  
\item MIME/OpenPGP (RFC2015/RFC3156) multipart messages can be sent
  and received.  Depending on configuration, this might involve
  procmail or patching Alpine.
\item The deprecated application/pgp content-type can be sent and received.
\item S/MIME messages can be sent and received if \verb|gpgsm| is
  available.  (\verb|openssl| is also used in some circumstances, but
  \verb|gpgsm| is still required.)
\item Topal can be used as Alpine's \verb|sendmail-path| command.
\item Topal has a remote sending mode (a server and a means of
  accessing the server) for reading email on a distant computer via
  SSH with secret keys on the local computer.
\item A range of mechanisms for selecting keys for both self and recipients.
\item There is a high level of configurability (although the
  configuration interface does not expose all of it; you'll have to
  edit \verb|.topal/config|).
\end{itemize}

\section{Terminology}

We use Pine and Alpine interchangably in this manual.  The earliest
version of Pine that Topal supported was 4.44.  When referring to
Thunderbird and Enigmail together, we sometimes just say Thunderbird.

Similarly, we often use GnuPG, GPG and sometimes OpenPGP and PGP interchangably.

\section{Version numbering}

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

\chapter{Important changes from previous stable versions}

\section{Important changes in release 70}

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

\section{Important changes in release 68}

\begin{itemize}\item 
  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.  
\item The MIME viewer setting \verb|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.) 
\end{itemize}

\section{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.


\section{Important changes in release 60}

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


\section{Important changes in release 58}

The default configuration no longer uses absolute paths.

\section{Important changes in release 55}

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

\section{Important changes in version 0.7.10}

The recommended procmail recipe has been changed.

\section{Important changes in version 0.7.8}

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

You \emph{must} clear your cache otherwise the changes made for\linebreak
\verb|inline-separate-output| \marginpar{New 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 
\verb|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.

\chapter{Installation and configuration}

\section{Options}

Topal supports a range of modes; some have particular requirements:
the following table summarises them.

\newcommand{\colh}[1]{\rotatebox{89}{\parbox{5cm}{\raggedright #1}}}
\noindent\begin{tabular}{lccccccc}
\hline
&
\colh{Apply patch \texttt{-1} to Alpine}
&
\colh{Apply patch \texttt{-2} to Alpine}
&
\colh{Configure Alpine's \texttt{sending-filters}}
&
\colh{Configure Alpine's \texttt{display-filters}}
&
\colh{Configure Alpine's \texttt{sendmail-path}}
&
\colh{Configure \texttt{.mailcap}}
&
\colh{Configure \texttt{.procmail} or run \texttt{topal --fix-email}}
\\
\hline
Encrypt/sign inline OpenPGP   &&&$\vee$&&$\vee$&&\\
Decrypt/verify inline OpenPGP &&&&\checkmark&&&\\
Encrypt/sign MIME/OpenPGP     &$\vee$&&&&$\vee$&&\\
Decrypt/verify MIME/OpenPGP   &&$\wedge$&&&&$\wedge$&\textopenbullet\\
Encrypt/sign S/MIME           &\textopenbullet&&&&$\star$&&\\
Decrypt/verify S/MIME         &&$\wedge$&&&&$\wedge$&\textopenbullet\\
\hline
\end{tabular}\bigskip

\noindent Key:
\begin{tabular}[t]{cl}
  \hline
  \checkmark&The only option.\\
  $\wedge$&Use both of these together.\\
  $\vee$&Use either of these.\\
  $\star$&This is a preferred option, but you can use an alternative (\textopenbullet).\\
  \textopenbullet&This is a possible option, but there is a better
  option ($\star$ or $\wedge$).\\
  \hline
\end{tabular}\bigskip

Inline OpenPGP is processed via Alpine's sending and display filters.
So you need to configure this within Alpine.

MIME messages are more complicated.  MIME/OpenPGP messages can be sent
if patch 1 is applied to Alpine.  However, although the corresponding
S/MIME messages appear to be correctly formed, use of patch 1 requires
that the message is embedded within a multipart/mixed message --- and
other mail clients (such as Mozilla Thunderbird and MS Outlook) will
not handle them properly.  So for S/MIME sending, you are strongly
recommended to use Topal as a \verb|sendmail-path| for Alpine.

Receipt of MIME messages (both OpenPGP and S/MIME) is best handled via
Alpine with patch 2.  This will cause Alpine to crash if your
\verb|.mailcap| is not properly configured to handled the cryptography
multipart/* types.  An alternative is to invoke Topal's
\verb|--fix-email| mode via \verb|.procmail| which rewrites the
top-level cryptographic message into a multipart/mixed message
that can be more easily processed by Alpine.

\section{Compilation and installation}

To compile Topal, you need
\begin{compactitem}\item 
   a working C compiler, 
\item
 the GNU Ada Compiler (GNAT),
  and 
\item some common libraries, including \verb|readline| (e.g., the
  package \linebreak\verb|libreadline6-dev| on Debian).
\end{compactitem}
There is a makefile: simply type \verb|make|.

Type \verb|make install| to actually install.  The default location
is \verb|/usr|, so you'll need to be root to install.  Alternatively, use
\linebreak\verb|make install INSTALLPATH=/usr/local| to install into
\verb|/usr/local|.  (Or use the more specific variables \verb|INSTALLPATHBIN|,
\verb|INSTALLPATHMAN|, \verb|INSTALLPATHDOC| and \verb|INSTALLPATHPATCHES|.)



\subsection{Cygwin}

Before using the makefile, please apply the patch
\verb|cygwin.patch|.  I haven't recently tested this\ldots.

\subsection{MIME-tool}

MIME sending requires the Topal version of Jeffrey S.~Dutky's
\verb|mime-tool|.  This is included with the Topal sources, and is
compiled and installed at the same time using the Makefile.


\subsection{MIME viewing}


MIME viewing can be handled via
\begin{compactenum}\item 
  metamail, \item run-mailcap, or \item by saving to a file (mbox format) in the \verb|~/.topal|
  directory and viewing with Alpine.
\end{compactenum}
If
you are using patch~2
(see ``Alpine patches'' below), then
depending on your Alpine configuration, Alpine might say something
like
\begin{quote}
  \verb|Attachment SIGNED unrecognized. Try opening anyway?|
\end{quote}
--- you
should say \verb|yes| in that case.


\subsection{GNU sed}

GNU sed is required.  I only discovered this when using Topal on Mac
OS X\ldots.

\section{Alpine patches}

There are two patches, for a range of versions of Pine and Alpine.
Patch 1 deals with sending MIME messages (\verb|-sendmime|); patch 2 with receiving them.

\begin{centering}
  \begin{tabular}{lcc}
    \hline
    &Patch 1&Patch 2\\
    \hline
    Pine 4.44&\checkmark&\\
    Pine 4.50&\checkmark&\\
    Pine 4.53&\checkmark&\\
    Pine 4.58&\checkmark&\\
    Pine 4.60&\checkmark&\\
    Pine 4.64&\checkmark&\\
    Alpine 1.00&\checkmark&\\
    Alpine 2.00&\checkmark&\checkmark\\
    Alpine 2.02&\checkmark&\checkmark\\
    \hline
  \end{tabular}

\end{centering}
\bigskip

To apply these patches, 
\verb|cd| into the Pine or Alpine source  directory and use the 
\verb|patch|  command, \eg, \verb|patch -p1 < -2.02.patch-1|.

Please note that the Alpine patches also modify Alpine's
configuration.  There is a hidden preference ‘enable Topal hack’
(\verb|enable-topal-hack|) that you need to enable.


% 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 ‘\verb|-d 9|’).


\section{Alpine filter configuration}


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

\begin{lstlisting}
display-filters=_BEGINNING("-----BEGIN PGP ")_ /usr/bin/topal
                  -display _TMPFILE_ _RESULTFILE_

sending-filters=/usr/bin/topal --read-from _INCLUDEALLHDRS_ 
                  -send _TMPFILE_ _RESULTFILE_ _RECIPIENTS_, 
                /usr/bin/topal --read-from _INCLUDEALLHDRS_ 
                  -sendmime _TMPFILE_ _RESULTFILE_ _MIMETYPE_ 
                  _RECIPIENTS_
\end{lstlisting}

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





The \verb|--read-from _INCLUDEALLHDRS_|\label{pg:readFrom} text 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.  Use
of this option is strongly recommended (but can be omitted).

\section{Alpine sendmail-path configuration}

As an alternative (or addition!) to setting filters (above), you can set 
\begin{lstlisting}
sendmail-path="/usr/bin/topal -asend"
\end{lstlisting}
Also see section~\ref{sec:smp-config} for more details on configuring
this mode.

This option allows Topal to handle attachments added within Alpine,
whereas sending using patch 1 requires that attachments are added via
Topal's interface (otherwise the attachments aren't covered by
encryption or signing).

\section{Mailcap configuration}


To decode MIME RFC2015/3156 multipart/signed and /encrypted messages
requires help via the ``mailcap'' system.  Add in either the user mailcap
configuration (\verb|.mailcap|) or the system configuration
(\verb|/etc/mailcap|) the lines

\begin{lstlisting}
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
\end{lstlisting}

Note that Alpine has been known to crash if you compile it with the
second patch, but do not set up your mailcap file to handle these
multipart types.


\section{Procmail configuration}\label{sec:procmail-configuration}

From Topal version 65, this recipe is no longer needed if you are
using patch~2. 

If you prefer to modify inbound multipart messages rather than use
patch~2, you should add this recipe to your \verb|.procmailrc|:
\begin{lstlisting}
:0fw 
| /usr/bin/topal --fix-email
\end{lstlisting}
This causes Topal to examine all inbound emails.  Those with top-level
multipart/signed or multipart/encrypted MIME types are modified to add
a multipart/misc wrapper so that 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.


\section{Topal configuration}


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



All \verb|.topal| files are silently ignored if they cannot be found.
Comments begin with a \verb|#| 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 (\verb|"|).  Double-quotes themselves can be
included by ‘stuffing’ (\verb|""|).



\chapter{Usage}


\section{Help!}


\verb|-help| as the first argument dumps a help message.


The help message is derived from the \verb|help.txt| file in the
source distribution.


See \verb|help.txt| for information on non-Pine use of Topal (section~\ref{sec:nonpine}).



Send \href{mailto:pjb@lothlann.freeserve.co.uk}{email to me} if you're really stuck.


\section{Configuration}


\verb|-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 \verb|.topal/config|.  Later sections in
this manual give specific instructions for particular features.



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



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

\section{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 \verb|~/.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 \verb|less| to view something.  So you'll
need to use \verb|q| to get out of it.  \verb|metamail|
or \verb|run-mailcap| may be called for anything
after MIME processing.



A new option \marginpar{New in  version~0.7.8.} called \verb|inline-separate-output|
concerns inlined (\ie, not MIME) messages.  If the option is on, then
the Topal/GnuPG output will be shown to you by \verb|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 \verb|q| an awful lot\ldots.


\section{Sending}

\subsection{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~\SSF{mainSendMenu.png}{Main
  sending menu}.  Some options (\eg, those
relating to MIME features) will not be offered unless you use
the \verb|-sendmime| option.


‘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, \verb|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 (but Thunderbird
doesn't seem to process the signature on these).  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
\verb|-config| option.


\subsection{List current recipient keys}


‘List current recipient keys’ offers a list of
recipients~\SSF{keyListMenu.png}{Key list menu}.


‘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 \emph{and add} all matching keys.  Beware of just pressing
enter --- it will select \emph{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.


\subsection{Examine key menu}


Selecting a key will offer a third menu (a similar menu is offered
when selecting a single key)~\SSF{examineKeyMenu.png}{Single key menu}.


‘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 \verb|less|.  You'll need to use \verb|q| to get out of \verb|less|.



‘Verbose details of key (less)’ pipes verbose output from GPG for this
key into gpg.  Again, you'll need to use \verb|q| to get out of \verb|less|.



‘Remove key from list’ removes the key from this recipient list.


\section{Command-line usage}\label{sec:nonpine}

\subsection{Sending (\texttt{-nps})}


If you invoke Topal on the command-line with a filename as an
argument, it will offer the sending functions on that
file~\SSF{npsSendMenu.png}{Non-pine sending menu}.  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).}  So \verb|e|,
\verb|s| and \verb|c| are different from \verb|E|, \verb|S| and
\verb|C| respectively.


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.


\subsection{Receiving (\texttt{-pd})}

\marginpar{New in release~71.}
Invoking Topal with only \verb|-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. 

\section{Remote and server mode}


Suppose you are reading your email on a remote host via \verb|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 
\verb|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 \verb|ssh|/\verb|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.  \verb|ssh| and \verb|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 \verb|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.


A generally better alternative is to process your email locally by
using IMAPS and SMTPS to remotely access the mail server.


\section{Fixing multipart emails}


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



\verb|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
wrapped version of the original message so that Pine/Alpine can pass the
signed or encrypted part to Topal.  



Usage: 
\begin{itemize}\item 
  \verb|topal --fix-folder <folder> ...|
  fixes the named  email folders.
  \item
  \verb|topal --fix-email| takes no arguments; it accepts
  a single email on stdin.  Ideally, it should be invoked by procmail
  (see section~\ref{sec:procmail-configuration}).
\end{itemize}

\verb|topal --fix-email| has a simpler mode (\verb|--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.  These effectively rename the multipart email
instead of wrapping it.


Why do we need this?  If we just set the \verb|.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
\begin{quote}
  \verb|Can't find body for requested message|
\end{quote}
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\ldots. 

See \verb|Workaround.Fix_Email| in the sources for more details.


\chapter{Notes}

This chapter includes a number of notes, explanations and further details.

\section{The Pine/Alpine patches, and sending other attachments}


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



The patch instead adds a flag, ‘\verb|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.  However, these attachments are
\emph{not} encrypted or signed by Topal.  You will need to separately
process them before attaching them in Alpine (\eg, using the
command-line mode described in section~\ref{sec:nonpine}) or add them
using Topal's attachment menu (if you are using Topal's MIME sending features).


The second patch file \marginpar{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.  But see
section~\ref{sec:crash-second-patch} if you find Alpine crashes when
this patch is used.


\section{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, so 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:
\begin{itemize}\item 
   For each recipient email address (supplied by Pine)
   \begin{enumerate}\item 
      For each matching line in keylist, use the key ID to get a
  fingerprint, and add the key to the list. \item If there are no
  matching lines in keylist, try to get a fingerprint via just that
  email address (but exclude \verb|xk| configuration entries).
\end{enumerate}
\end{itemize}



The keylist is a way to say, ‘for this particular email address, use
this particular key’.  In your \verb|config| file, include lines
such as
\begin{lstlisting}
ake=50973B91,philb@soc.plym.ac.uk
ake=50973B91,pjb@lothlann.freeserve.co.uk
\end{lstlisting}
These mean ‘use key 50973B91 for the given email addresses’.
Similarly,
\begin{lstlisting}
xk=50973B91
\end{lstlisting}
means ‘don't use key 50973B91’.  There are also similar
\verb|sake| and \verb|sxk| options for selection of  secret keys
via the (recommended) \verb|--read-from| option (page~\pageref{pg:readFrom}).

For S/MIME, the same lists are used.  If a key isn't relevant (an
  S/MIME key when using OpenPGP or \vv) it is ignored.
  Importantly, you need to use \verb|sake|/\verb|sxk| to give the
  signing key for S/MIME, as \verb|my-key| only applies to OpenPGP
  usage.

\section{Sending defaults}

\marginpar{New in release~68.}
verb|sd| lines in your \verb|config| file can assign a default to a key ID or email address.
The special string \verb|@ANY@| matches any email address (or
key).
The \emph{last matching} \verb|sd| expression applies, so use
\verb|@ANY@| first. 

The individual letters mean\\

\begin{centering}
  \begin{tabular}[t]{ll}
    \verb|n|&no GPG\\
    \verb|e|&encrypt\\
    \verb|s|&sign and encrypt\\
    \verb|c|&clearsign\\
  \end{tabular}
  \begin{tabular}[t]{ll}
    \verb|I|&inline plain\\
    \verb|A|&app pgp\\
    \verb|M|&multipart\\
    \verb|E|&multipart encapsulated\\
    \verb|P|&S/MIME (not OpenPGP)\\
  \end{tabular}

\end{centering}


\begin{samepage}
  \noindent Example:
  \begin{quote}
    \verb|sd=pjb@lothlann.freeserve.co.uk,eI|
  \end{quote}
  means that the default settings for the given address are encryption
  and inline plain.
\end{samepage}

Topal will warn you if you are sending to multiple recipients,
\verb|sd| has selected encryption, and not all of the recipients have
keys.  However, it won't stop you continuing and sending an email that
some recipients can't read.


\section{Sendmail-path configuration}\label{sec:smp-config}


\marginpar{New in release~73.}
\verb|sc| lines in your \verb|config| file assign a \verb|sendmail-path|
command to the ‘from’ (sending)
email address.
Again, the special expression \verb|@ANY@| matches any email address
(but not key id's) and the last matching \verb|sd| expression applies.

Example:
\begin{quote}
\verb|sc=pjb@lothlann.freeserve.co.uk,mstmp -a default|
\end{quote}
means that emails sent using that address will actually be sent using
the (external) \verb|msmtp| program.  If you are using Topal as a
\verb|sendmail-path|, you must ensure that there is a suitable
\verb|sc| line, as Topal does not actually know how to send email.


\subsection{Additional (bcc) recipients}

Note that \verb|msmtp| can add additional recipients, \eg, 
\begin{quote}
\verb|mstmp -a default -- pjb@lothlann.freeserve.co.uk|
\end{quote}

\subsection{Message-ID munging}

The \verb|sendmail-path| mode can also modify Message-IDs and Content-IDs.  The
configuration option \verb|replace-ids| controls this.  If set to 0,
nothing is changed; 1 causes the Message-ID to be altered; and 2 (the
default) alters both Message-ID and Content-IDs (of attachments).

The Message-ID is altered from the standard Alpine form of
\begin{quote}
\verb|<alpine.DEB.2.02.1103063481092.1140@somewhere.com>|
\end{quote}
to 
\begin{quote}
\verb|<1103063481092.1140.NCYBIHRU%user@somehost.org>|  
\end{quote}
The email address used in the replacement is based on the From line.

\subsection{Send tokens}

The \verb|sendmail-path| mode also enables the \verb|st| (send token) lines in the
\verb|config| file.  These lines have the form
\begin{quote}
\verb|st=user@example.org,somepasswordstring|
\end{quote}
If the Message-ID is altered and there is a matching send token, the
original Message-ID is encrypted and stored in the headers.
Additionally, a header is added based on this token, the Message-ID
and From line.  This can be used to match inbound emails (self blind
copies) via procmail, \eg, 
\begin{lstlisting}
:0fw
* ^From: .*\<user@example.org\>$
| /usr/local/bin/topal --check-send-token somepasswordstring

:0:
* ^X-Topal-Check-Send-Token: yes$
.topal-cc/
\end{lstlisting}
This causes emails apparently from \verb|user@example.org| to be
passed to Topal, which checks the headers.  If the header token
matches for that password, a new header, \verb|Topal-Check-Send-Token: yes| is added.
Then procmail can filter on the basis of this header.

\subsection{Missing attachments trap}

\marginpar{New in Topal 73.}  If set, the configuration line
\verb|attachment-trap=on| causes Topal to complain if the message contains
the string “attach” but  it does not have any attachments.

This is only effective if Topal is running as a
\verb|sendmail-path|.

\section{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 in section~\ref{sec:author}).


\section{Saving encrypted 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 your configuration options here).  Otherwise, you'll
get a decrypted file with the original attachment filename, plus the
various Topal headers.


\section{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 (\ie,
bad signature).  



I currently have no way to automatically fix this.  However, the
\verb|--ask-charset| option will ask 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.


\section{“\texttt{Couldn't find certificate needed to sign.}”}


A regular query (for both Topal and other OpenPGP filters) concerns
the message “\texttt{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 ("\verb|S/MIME -- Turn off S/ MIME|").



\section{Cleaning up the cache}


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


\section{Remote and server mode}


When remote is invoked in a sending menu:

\begin{itemize} 
  \item The host has to be chosen for \verb|ssh|/\verb|scp|. \item Because Topal
  might be outside the normal path, you'll be asked for that too.
  \item The sender \verb|scp|s the relevant files into
  \verb|.topal/server|. \item The sender calls
  \begin{quote}
    \verb|ssh (server) -remotesend ...|
  \end{quote}
or
\begin{quote}
  \verb|ssh (server) -remotesendmime ...|\end{quote}
. \item The invocation of
  \verb|-remotesend| or \verb|-remotesendmime| triggers the server to
  run a new instance of Topal on the local computer. \item When
  that instance is finished, the relevant files are copied back, along
  with the return value.
\end{itemize}

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.


\section{Working with GPG Agent}


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

Notes:
\begin{enumerate}\item 
  \verb|--no-use-agent| is deprecated in some versions of GPG.
\item If you change \verb|trustlist.txt| (when using \verb|gpgsm|,
  \ie, GnuPG for S/MIME) then remember to send the \verb|HUP| signal
  to your current GPG agent.
\end{enumerate}



\section{Decryption prerequisite}


This relates to the configuration option \verb|decrypt-prereq|.

If empty (the default), this is
ignored.  Otherwise, if decryption is required (\ie, a non-cached
encrypted block is found) it will run the command stated (this should
be just the command name, with no arguments).  If the command's exit
status is 
0, then decryption continues.  If not, then no decryption is attempted.



I've introduced this for the case where decryption keys are not always
available.  It is a nuisance for Topal to offer to decrypt when it
cannot.  Example: the secret key ring is kept on removable media.
Then set
\begin{quote}
  \verb|decrypt-prereq=/path/to/topal-decrypt-prereq|
\end{quote}
 The
executable file \verb|/path/to/topal-decrypt-prereq| contains
something like
\begin{quote}
  \verb|mount grep /path/of/keyring > /dev/null|
\end{quote}
This returns 0 if that path is found, and 1 otherwise.

\section{Crash with second patch when reading multipart messages}\label{sec:crash-second-patch}

Some Alpine crashes have been traced to the second Topal patch.

This occurs when you have compiled Alpine using this patch, but not
  set up your \verb|.mailcap| configuration
  appropriately.

\section{New releases}

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


\section{Interoperability}

I have tested Topal's interoperability with MS Outlook (both IMAP and
Exchange) and Thunderbird.  It works in all tested cases, except as
follows.
\begin{itemize}
\item At least one instance of MS Exchange rewrites the content-*
  headers of inbound clearsigned messages with attachments, which results in
  the signature failing to verify.  This also affects messages sent
  from Thunderbird and MS Outlook.  However, it does not apply to all MS
  Exchange systems.
\item MS Outlook and Thunderbird do not handle clearsigned messages
  properly when the clearsigned message is itself part of a
  multipart/mixed message.  The only way to reliably send messages to
  users of these systems is via the \verb|sendmail-path| mode.
\end{itemize}


\section{Hints}

\begin{itemize}\item 
Consider using GPG's \verb|--trusted-key| option in Topal's
  \verb|gpg-options| configuration setting.  This is useful if you keep your
  secret keys offline. \item Use the \verb|--read-from| option (page~\pageref{pg:readFrom}), especially if you
  use multiple roles rather than setting \verb|my-key|.
\end{itemize}

\chapter{Author}\label{sec: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.





I can be emailed on 
\href{mailto:pjb@lothlann.freeserve.co.uk}{\tt 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.

\chapter{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 \url{http://www.gnu.org/licenses/}.


(See the file \verb|COPYING|.)


\chapter{To do}

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

\chapter{Change log}

The change log is kept in a separate file, \url{Changelog.html}.

\end{document}