$Id$

		     USING PGP FROM WITHIN MUTT


WARNING: The configuration interface has completely changed as of
         0.96.3!



			    USERS' GUIDE


How do I use mutt with PGP, PGP5, or GnuPG?
-------------------------------------------

Go to the contrib subdirectory of the source tree.  You'll find
three files there, pgp2.rc, pgp5.rc, and gpg.rc.  These files
contain ready-to-use configurations for using mutt with pgp2, pgp5,
and gpg.

Include one of these files with your ~/.muttrc, and things should
work out fine.

You may wish to verify that all paths and  the language parameters
given to the PGP binaries match your needs.



Frequently Asked Questions and Tips
-----------------------------------

Q: "People are sending PGP messages which mutt doesn't
    recognize.  What can I do?"

The new way is to leave headers alone and use mutt's
check-traditional-pgp function, which can detect PGP messages at
run-time, and adjust content-types.

The old way is to configure your mail filter so it fixes headers:

Add the following lines to your ~/.procmailrc (you are
using procmail, aren't you?):

		   ------------------------------

##
## PGP
##
  
:0
* !^Content-Type: message/
* !^Content-Type: multipart/
* !^Content-Type: application/pgp
{
        :0 fBw
        * ^-----BEGIN PGP MESSAGE-----
        * ^-----END PGP MESSAGE-----
        | formail \
            -i "Content-Type: application/pgp; format=text; x-action=encrypt"

        :0 fBw
        * ^-----BEGIN PGP SIGNED MESSAGE-----
        * ^-----BEGIN PGP SIGNATURE-----
        * ^-----END PGP SIGNATURE-----
        | formail \
            -i "Content-Type: application/pgp; format=text; x-action=sign"
}


		   ------------------------------

For users of maildrop, "Mark Weinem"
<mark.weinem@unidui.uni-duisburg.de> suggests the following recipe:

		   ------------------------------

BPGPM="-----BEGIN PGP MESSAGE-----"
EPGPM="-----END PGP MESSAGE-----"
BPGPS="-----BEGIN PGP SIGNATURE-----"
EPGPS="-----END PGP SIGNATURE-----"

if (!/^Content-Type: message/ && !/^Content-Type: multipart/ \
	&& !/^Content-Type: application\/pgp/)
{	
if (/^$BPGPM/:b && /^$EPGPM/:b)
	xfilter "reformail -A 'Content-Type: application/pgp; format=text; \
		x-action=encrypt'"

if (/^$BPGPS/:b && /^$EPGPS/:b)
	xfilter "reformail -A 'Content-Type: application/pgp; format=text; \
		x-action=sign'"
}

		   ------------------------------



Q: "I don't like that PGP/MIME stuff, but want to use the
    old way of PGP-signing my mails.  Can't you include
    that with mutt?"

The old answer to this question used to be this:

  No.  Application/pgp is not really suited to a world with MIME,
  non-textual body parts and similar things.  Anyway, if you really
  want to generate these old-style attachments, include the
  following macro in your ~/.muttrc (line breaks for readability,
  this is actually one line):

  macro compose S "Fpgp +verbose=0 -fast
  	+clearsig=on\ny^T^Uapplication/pgp; format=text;
	x-action=sign\n"


There's a new answer, though: Set the $pgp_create_traditional
configuration variable (it's a quad-option) to something different
from "no" (that's the default).  Mutt will then try to use
application/pgp whereever it makes sense.  In particular, it does
not make any sense with multiparts, or non-ASCII or non-text bodies.
In all other cases, PGP/MIME is used unconditionally.

Note that application/pgp is still strongly deprecated.



Q: "I don't like all the ^Gs and various other verbosity
    PGP is presenting me with."

Roland Rosenfeld <roland@spinnaker.rhein.de> has found a quite
elegant solution to this problem: PGP has some pretty good foreign
language support.  So we just introduce a language called "mutt"
which contains empty strings for the messages we don't want to see.
To use this, copy either language.txt or language50.txt (depending
on what PGP version you are using) to your $PGPPATH.  Make sure the
PGP command formats pass "+language=pgp" to all the PGP binaries
(but not to pgpring!).

For PGP 2.6, a German version called "muttde" is available
as well.


Q: "My PGP signatures are being invalidated.  BTW, I'm using Courier
    MTA."

The author of the Courier MTA believes that the standard specifying
multipart/signed is broken.  For that reason, he has choosen to
implement his MTA in a way which does not assure that
multipart/signed body parts are left untouched.

We suggest that you abandon courier and change to sendmail, postfix,
or exim.



			     BACKGROUND


Auxiliary Programs
------------------

Mutt needs two auxiliary programs for its PGP support: pgpewrap and
pgpring.


1. pgpring

pgpring is a key ring dumper.  It extracts information from PGP's
binary key ring and emits it in an (almost) readable output format
understood by mutt's key selection routines.  This output format
mimics the one used by the GNU Privacy Guard (GPG).

You'll need this program with PGP 2 and PGP 5.

Command line options:

	-k <key ring>	Dump the contents of the key ring specified
			as an argument to -k.
			
	-2, -5	 	Use the default key ring for PGP 2 or 5, 
			respectively.
			
	-s		Dump the secret key ring.



2. pgpewrap

This is a little C program which does some command line munging: The
first argument is a command to be executed.  When pgpewrap
encounters a "--" (dash-dash) argument, it will interpret the next
argument as a prefix which is put in front of all following
arguments.

Example:

	pgpewrap pgpe file -- -r a b c

will execute:

	pgpe file -r a -r b -r c

This script is needed with PGP 5 and with GPG, since their command
line interfaces can't be properly served by mutt's format mechanism.



The Configuration Interface
---------------------------

As usual within mutt, the configuration interface for the PGP
commands relies on printf-like formats.  For all PGP commands, the
following %-sequences are defined.

  %p	The empty string when no passphrase is needed,
  	the string "PGPPASSFD=0" if one is needed.

	This is mostly used in conditional % sequences.

  %f	Most PGP commands operate on a single file or a file
  	containing a message.  %f expands to this file's name.

  %s	When verifying signatures, there is another temporary file
	containing the detached signature.  %s expands to this
	file's name.

  %a	In "signing" contexts, this expands to the value of the
	configuration variable $pgp_sign_as.  You probably need to
	use this within a conditional % sequence.

  %r	In many contexts, mutt passes key IDs to pgp.  %r expands to
	a list of key IDs.

The following command formats are defined:

  $pgp_decode_command	Decode application/pgp messages.  This
  			command operates with and without pass phrases.
			
  $pgp_verify_command	Verify a PGP/MIME signature.

  $pgp_decrypt_command	Decrypt a PGP/MIME encrypted MIME body.
   			This command always gets a pass phrase.

  $pgp_sign_command	Sign a PGP/MIME body.  This command always
  			gets a pass phrase.


  $pgp_encrypt_sign_command Encrypt and sign a MIME body.  This
  			command always gets a pass phrase.
			
  $pgp_encrypt_only_command Encrypt a MIME body, but don't sign it.
  
  $pgp_import_command	Import PGP keys from a file.
  
  $pgp_export_command	Export PGP keys to a file.  The output must
  			be ASCII armored.
			
  $pgp_verify_key_command Check a public key. This is used from the
  			key selection menu.

  $pgp_list_secring_command List the secret keys matching some hints
  			given in %r.

  $pgp_list_pubring_command List the public keys matching some hints
  			given in %r.

The passphrase is always passed on stdin; all commands must send
their output to stdout and stderr.



