~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,