pine-gpg-filter-0.72 README Description =========== pine-gpg-filter (pgf) is almost a clone of pinepg [0]. It, however, adds the capability for specifying which user ID (or IDs) to use for the encryption or signing. It does absolutely no passphrase caching. If you need (want) passphrase caching, look into gpg-agent, available in the "gnupg2" package, e.g., gnupg-1.9.21 as of 2006-07-04. This utility is intended to allow the pine user to be able to take advantage of multiple separate roles and keys for each of those roles within pine. Other pine and GnuPG integration (i.e., pgp4pine, pinepg) utilities do not allow for selection of user ID for a particular encryption or signing request. While this can be used as a plain GPG filter, it offers less than raw GPG tools to the end user. The script was conceived and written exclusively to bind Pine's support for roles to GPG's capacity for handling roles. Quickstart ========== Below is the simplest configuration set for using these tools. Prerequisites and warnings: --------------------------- 0. You must have Pine and GnuPG installed. 1. You must have a working GPG keyring. 2. Pine refuses to run filters unless you have specified the full path to the filter, e.g. /usr/bin/pgfa-decrypt. These example entries are line broken for readability; you must enter each one on its own line. If you enter these lines in your configuration file include a comma at the end of the first line. If you ntere these lines through the Pine configuration interface, you should omit the comma. display-filters=_LEADING("-----BEGIN PGP MESSAGE-----")_ \ /usr/bin/pgf-decrypt -R _RESULTFILE_, _LEADING("-----BEGIN PGP SIGNED MESSAGE-----")_ \ /path/to/pgf-verify -D _DATAFILE_ -R _RESULTFILE_ sending-filters=/usr/bin/pgfa-clearsign _INCLUDEALLHDRS_ -R _RESULTFILE_, /usr/bin/pgfa-sign-encrypt _INCLUDEALLHDRS_ -tR _RESULTFILE_ _RECIPIENTS_ Required Option(s) ================== At least one of these first options is required. The sign and encrypt options may be combined, but no other combination is possible. If multiple options are specified in incompatible combinations, the last one "wins". --clearsign (-c) Have GPG clearsign the message. This is what most people mean when they talk about "signed" email messages. --encrypt (-e) Have GPG encrypt the message. When using this option, you must specify recipient addresses, as well. --sign (-s) Have GPG sign the message (use with encrypt). --decrypt (-d) Have GPG decrypt the message. --verify (-v) Have GPG verify the message. Behaviour modifying options =========================== --to-self (-t) This option asks GPG to employ the encrypt-to-self option, where self is defined as the local user specified with the -L option. (This option is simply ignored if not needed.) --one-line (-o) Only print out one line of the status generated by GnuPG on the STDERR (_RESULTFILE_). --multi-line (-m) Produce all of the usual GnuPG status output. --no-comment (-n) Suppress the default comment string. --comment (-C) Override the default comment string. Default is pgf-0.72 (http://linux-ip.net/sw/pine-gpg-filter/) --resultfile (-R) Pine returns the filter's STDERR via the _RESULTFILE_ See Examples. --datafile (-D) Pine provides a session-unique filename called We use it as a FIFO. _DATAFILE_ (cf. Examples). --local-user (-l) Select a specific local key identifier. With this option, you may specify a non-default key on your GPG keyring. The may be an email address or the actual key ID itself. --autoid (-a) Select a specific local key identifier by parsing the From: header line. Requires the use of Pine's _INCLUDEALLHDRS_ directive. See Examples. Special options =============== --build-symlinks This will install all of the compatibility symlinks for the pine-gpg-filter program. You must have write permissions on the directory in which pine-gpg-filter is installed order to use this option. Prerequisites ============= You must have a working GnuPG installation. If you are using these scripts for integration with your pine MUA and you have only a single GPG identity (one secret key), you may wish to consider the GnuPG option (check ~/.gnupg/options or ~/.gnupg/gpg.conf in newer versions) known as "encrypt-to". The encrypt-to option allows you to specify a key identifier which will be added to the recipient list for any encryption. Although not strictly a prerequisite, you may find that the passphrase caching offered by gpg-agent (included in SuSE's gpg2 package) will save some keystrokes when used with this filter, which performs none of its own caching. Notes on sending-filters and display-filters ============================================ all scripts: All of the scripts can make use of the _RESULTFILE_ token as either a sending-filter or a display-filter. The _RESULTFILE_ is used to store output like "gpg: Good signature..." while the filter itself is running. I recommend invoking each of the utilities with the "--resultfile _RESULTFILE_" option (see Examples, below). Pine will pause and display the STDERR output from GPG, which has ended up in the _RESULTFILE_. This option is, perhaps, less important when used on the sending-filters. If you are absolutely sure you want to bypass the confirmations of successful decryption or verification, you may omit the "-R _RESULTFILE_" (in which case, the output will go to the terminal "behind" pine's curses interface) or you may specify "-R /dev/null" to obliterate the output. (Not recommended.) I would encourage the use of "--resultfile _RESULTFILE_", because the user will then receive feedback from GPG regarding the signature (or encryption). *-verify: The *-verify command requires the use of a temporary file (it uses a FIFO) in order to both output the text of the message and validate the signature. Thus, not supplying the --datafile _DATAFILE_ option when using the *-verify commands is an error. *-encrypt, *-sign-encrypt: Any use of the encryption command requires at least one recipient. If there is no recipient, then the command will fail. Pine will provide the recipient list, including Cc and Bcc (careful!), to the filters as command line arguments. By using the _RECIPIENTS_ token in the sending-filter, you are asking pine to provide these addresses. Compatibility names =================== In order to make the utility easier to use, there are several ways to call it without requiring long options. Here are the names and the indicated behaviour: option compat autoid compat ================ ================ ================= --clearsign pgf-clearsign pgfa-clearsign --encrypt pgf-encrypt pgfa-encrypt --sign --encrypt pgf-sign-encrypt pgfa-sign-encrypt --sign pgf-sign pgfa-sign --decrypt pgf-decrypt pgfa-decrypt (N.B.) --verify pgf-verify pgfa-verify (N.B.) N.B., for symmetry, the pgfa-decrypt and pgfa-verify compatibility symlinks are installed, although there is little sense to a pine filter which selects an identity for receiving a message. Why? Because GPG simply attempts to decrypt (or verify) the message with the key used for encryption. In these invocations, the autoid component is simply ignored. See also Examples, below. Examples ======== Here are several examples of how to configure your pine filters: 0: /path/to/pgf-sign-encrypt --resultfile _RESULTFILE_ _RECIPIENTS_ 0: /path/to/pgf-sign-encrypt -r _RESULTFILE_ _RECIPIENTS_ The above will select the primary GPG key ID to use for signing and encrypting the message. These two are exactly the same, one uses the long command line options, and the other uses the short command line options. 1: /path/to/pgf-sign-encrypt -tl 0x2486302b -R _RESULTFILE_ _RECIPIENTS_ 1: /path/to/pgf-sign-encrypt --to-self --local-user 0x2486302b \ --resultfile _RESULTFILE_ _RECIPIENTS_ In these examples, we are specifying the key identifier (0x0x2486302b) we wish to use when encrypting. The --to-self (-t) option instructs GPG to encrypt the message not only to the _RECIPIENTS_, but also to the key 0x2486302b. Because there may be multiple _RECIPIENTS_, this should be the last parameter on the command line. 2: /path/to/pgf-clearsign -l frank@cheese-shop.net -R _RESULTFILE_ 2: /path/to/pgf-clearsign --local-user frank@cheese-shop.net \ --resultfile _RESULTFILE_ In this case, we are asking GPG to use the key for address frank@cheese-shop.net. 3: /path/to/pgf-clearsign -C "Organization Name" -R _RESULTFILE_ We do not specify a key ID here, so the default GPG user will be selected. The --comment (-C) option allows you to alter the string sent in the body of the GPG signature (in this case, or the header of the encrypted message in the case of encryption). 4: /path/to/pgf-sign-encrypt -nR _RESULTFILE_ _RECIPIENTS_ Maybe you don't like the advertisement for pine-gpg-filter in the clearsign text of your messages. Suppress the comment string by using the --no-comment (-n) option. 5: /path/to/pgf-verify -R _RESULTFILE_ -D _DATAFILE_ 5: /path/to/pgf-verify --resultfile _RESULTFILE_ --datafile _DATAFILE_ The verify functionality requires a temporary file. If you do not supply the "--datafile _DATAFILE_", pine-gpg-filter cannot validate the signature on the message, and must abort. 6: /path/to/pgfa-sign-encrypt _INCLUDEALLHDRS_ -R _RESULTFILE_ _RECIPIENTS_ This is the calling method for using the automatic identity selection of this utility. 7: /path/to/pgfa-clearsign _INCLUDEALLHDRS_ -R _RESULTFILE_ To select one of your identities automatically for any clearsigning, this invocation should suffice. Similar applications ==================== [0] http://quantumlab.net/pine_privacy_guard/ pinepg [1] http://hany.sk/~hany/software/pinepgp/ pinepgp [2] http://user.cs.tu-berlin.de/~gator/pgp4pine/ PGP4Pine (PAPP) [3] http://dougbarton.net/FreeBSD/Downloads/ Pine PGP Filters [4] http://pgpenvelope.sourceforge.net/ pgpenvelope Usage: pine-gpg-filter [ options ] [ ... ] Options (defaults marked, or in parentheses): -h, --help Print out this handy help screen. -L, --long-usage Provide help and some more hints. -q, --quiet Reset verbosity to none. -v, --verbose Increase verbosity, can be used multiple times. -V, --version Print version information. -c, --clearsign Ask GPG to clearsign the input. -e, --encrypt Ask GPG to encrypt the input. -s, --sign Ask GPG to sign the input. -d, --decrypt Ask GPG to decrypt the input. -y, --verify Ask GPG to verify the input. -o, --one-line Compress multiline status output from GPG. -m, --multi-line Allow all of the status output from GPG. -t, --to-self Also encrypt-to-self (ignored if not needed). -n, --no-comment Suppress any comment string. -C, --comment Override the default comment string. -D, --datafile Use pine-provided _DATAFILE_ as temporary FIFO. -R, --resultfile Pine reports command output via _RESULTFILE_. -l, --local-user Specify a local username. -a, --autoid Determine (role) from From: line. --build-symlinks Install pgf-* and pgfa-* symlinks.