doc/PGP-Notes.txt

   1 $Id$
   2
   3                      USING PGP FROM WITHIN MUTT
   4
   5
   6 WARNING: The configuration interface has completely changed as of
   7          0.96.3!
   8
   9
  10
  11                             USERS' GUIDE
  12
  13
  14 How do I use mutt with PGP, PGP5, or GnuPG?
  15 -------------------------------------------
  16
  17 Go to the contrib subdirectory of the source tree.  You'll find
  18 three files there, pgp2.rc, pgp5.rc, and gpg.rc.  These files
  19 contain ready-to-use configurations for using mutt with pgp2, pgp5,
  20 and gpg.
  21
  22 Include one of these files with your ~/.muttrc, and things should
  23 work out fine.
  24
  25 You may wish to verify that all paths and  the language parameters
  26 given to the PGP binaries match your needs.
  27
  28
  29
  30 Frequently Asked Questions and Tips
  31 -----------------------------------
  32
  33 Q: "People are sending PGP messages which mutt doesn't
  34     recognize.  What can I do?"
  35
  36 The new way is to leave headers alone and use mutt's
  37 check-traditional-pgp function, which can detect PGP messages at
  38 run-time, and adjust content-types.
  39
  40 The old way is to configure your mail filter so it fixes headers:
  41
  42 Add the following lines to your ~/.procmailrc (you are
  43 using procmail, aren't you?):
  44
  45                    ------------------------------
  46
  47 ##
  48 ## PGP
  49 ##
  50
  51 :0
  52 * !^Content-Type: message/
  53 * !^Content-Type: multipart/
  54 * !^Content-Type: application/pgp
  55 {
  56         :0 fBw
  57         * ^-----BEGIN PGP MESSAGE-----
  58         * ^-----END PGP MESSAGE-----
  59         | formail \
  60             -i "Content-Type: application/pgp; format=text; x-action=encrypt"
  61
  62         :0 fBw
  63         * ^-----BEGIN PGP SIGNED MESSAGE-----
  64         * ^-----BEGIN PGP SIGNATURE-----
  65         * ^-----END PGP SIGNATURE-----
  66         | formail \
  67             -i "Content-Type: application/pgp; format=text; x-action=sign"
  68 }
  69
  70
  71                    ------------------------------
  72
  73 For users of maildrop, "Mark Weinem"
  74 <mark.weinem@unidui.uni-duisburg.de> suggests the following recipe:
  75
  76                    ------------------------------
  77
  78 BPGPM="-----BEGIN PGP MESSAGE-----"
  79 EPGPM="-----END PGP MESSAGE-----"
  80 BPGPS="-----BEGIN PGP SIGNATURE-----"
  81 EPGPS="-----END PGP SIGNATURE-----"
  82
  83 if (!/^Content-Type: message/ && !/^Content-Type: multipart/ \
  84         && !/^Content-Type: application\/pgp/)
  85 {
  86 if (/^$BPGPM/:b && /^$EPGPM/:b)
  87         xfilter "reformail -A 'Content-Type: application/pgp; format=text; \
  88                 x-action=encrypt'"
  89
  90 if (/^$BPGPS/:b && /^$EPGPS/:b)
  91         xfilter "reformail -A 'Content-Type: application/pgp; format=text; \
  92                 x-action=sign'"
  93 }
  94
  95                    ------------------------------
  96
  97
  98
  99 Q: "I don't like that PGP/MIME stuff, but want to use the
 100     old way of PGP-signing my mails.  Can't you include
 101     that with mutt?"
 102
 103 The old answer to this question used to be this:
 104
 105   No.  Application/pgp is not really suited to a world with MIME,
 106   non-textual body parts and similar things.  Anyway, if you really
 107   want to generate these old-style attachments, include the
 108   following macro in your ~/.muttrc (line breaks for readability,
 109   this is actually one line):
 110
 111   macro compose S "Fpgp +verbose=0 -fast
 112         +clearsig=on\ny^T^Uapplication/pgp; format=text;
 113         x-action=sign\n"
 114
 115
 116 There's a new answer, though: Set the $pgp_create_traditional
 117 configuration variable (it's a quad-option) to something different
 118 from "no" (that's the default).  Mutt will then try to use
 119 application/pgp wherever it makes sense.  In particular, it does
 120 not make any sense with multiparts, or non-ASCII or non-text bodies.
 121 In all other cases, PGP/MIME is used unconditionally.
 122
 123 Note that application/pgp is still strongly deprecated.
 124
 125
 126
 127 Q: "I don't like all the ^Gs and various other verbosity
 128     PGP is presenting me with."
 129
 130 Roland Rosenfeld <roland@spinnaker.rhein.de> has found a quite
 131 elegant solution to this problem: PGP has some pretty good foreign
 132 language support.  So we just introduce a language called "mutt"
 133 which contains empty strings for the messages we don't want to see.
 134 To use this, copy either language.txt or language50.txt (depending
 135 on what PGP version you are using) to your $PGPPATH.  Make sure the
 136 PGP command formats pass "+language=pgp" to all the PGP binaries
 137 (but not to pgpring!).
 138
 139 For PGP 2.6, a German version called "muttde" is available
 140 as well.
 141
 142
 143 Q: "My PGP signatures are being invalidated.  BTW, I'm using Courier
 144     MTA."
 145
 146 The author of the Courier MTA believes that the standard specifying
 147 multipart/signed is broken.  For that reason, he has chosen to
 148 implement his MTA in a way which does not assure that
 149 multipart/signed body parts are left untouched.
 150
 151 We suggest that you abandon courier and change to sendmail, postfix,
 152 or exim.
 153
 154
 155
 156                              BACKGROUND
 157
 158
 159 Auxiliary Programs
 160 ------------------
 161
 162 Mutt needs two auxiliary programs for its PGP support: pgpewrap and
 163 pgpring.
 164
 165
 166 1. pgpring
 167
 168 pgpring is a key ring dumper.  It extracts information from PGP's
 169 binary key ring and emits it in an (almost) readable output format
 170 understood by mutt's key selection routines.  This output format
 171 mimics the one used by the GNU Privacy Guard (GPG).
 172
 173 You'll need this program with PGP 2 and PGP 5.
 174
 175 Command line options:
 176
 177         -k <key ring>   Dump the contents of the key ring specified
 178                         as an argument to -k.
 179
 180         -2, -5          Use the default key ring for PGP 2 or 5,
 181                         respectively.
 182
 183         -s              Dump the secret key ring.
 184
 185
 186
 187 2. pgpewrap
 188
 189 This is a little C program which does some command line munging: The
 190 first argument is a command to be executed.  When pgpewrap
 191 encounters a "--" (dash-dash) argument, it will interpret the next
 192 argument as a prefix which is put in front of all following
 193 arguments.
 194
 195 Example:
 196
 197         pgpewrap pgpe file -- -r a b c
 198
 199 will execute:
 200
 201         pgpe file -r a -r b -r c
 202
 203 This script is needed with PGP 5 and with GPG, since their command
 204 line interfaces can't be properly served by mutt's format mechanism.
 205
 206
 207
 208 The Configuration Interface
 209 ---------------------------
 210
 211 As usual within mutt, the configuration interface for the PGP
 212 commands relies on printf-like formats.  For all PGP commands, the
 213 following %-sequences are defined.
 214
 215   %p    The empty string when no passphrase is needed,
 216         the string "PGPPASSFD=0" if one is needed.
 217
 218         This is mostly used in conditional % sequences.
 219
 220   %f    Most PGP commands operate on a single file or a file
 221         containing a message.  %f expands to this file's name.
 222
 223   %s    When verifying signatures, there is another temporary file
 224         containing the detached signature.  %s expands to this
 225         file's name.
 226
 227   %a    In "signing" contexts, this expands to the value of the
 228         configuration variable $pgp_sign_as.  You probably need to
 229         use this within a conditional % sequence.
 230
 231   %r    In many contexts, mutt passes key IDs to pgp.  %r expands to
 232         a list of key IDs.
 233
 234 The following command formats are defined:
 235
 236   $pgp_decode_command   Decode application/pgp messages.  This
 237                         command operates with and without pass phrases.
 238
 239   $pgp_verify_command   Verify a PGP/MIME signature.
 240
 241   $pgp_decrypt_command  Decrypt a PGP/MIME encrypted MIME body.
 242                         This command always gets a pass phrase.
 243
 244   $pgp_sign_command     Sign a PGP/MIME body.  This command always
 245                         gets a pass phrase.
 246
 247
 248   $pgp_encrypt_sign_command Encrypt and sign a MIME body.  This
 249                         command always gets a pass phrase.
 250
 251   $pgp_encrypt_only_command Encrypt a MIME body, but don't sign it.
 252
 253   $pgp_import_command   Import PGP keys from a file.
 254
 255   $pgp_export_command   Export PGP keys to a file.  The output must
 256                         be ASCII armored.
 257
 258   $pgp_verify_key_command Check a public key. This is used from the
 259                         key selection menu.
 260
 261   $pgp_list_secring_command List the secret keys matching some hints
 262                         given in %r.
 263
 264   $pgp_list_pubring_command List the public keys matching some hints
 265                         given in %r.
 266
 267 The passphrase is always passed on stdin; all commands must send
 268 their output to stdout and stderr.
 269
 270
 271