Uwe Ohse homepage

upgpverify

NAME

         upgpverify - PGP wrapper for verifying messages

SYNOPSIS

upgpverify [options] [tmp [program [arguments]]]

DESCRIPTION

upgpverify verifies a PGP signed or encrypted and signed message on stdin, checks the user id or key id against a database, if wanted, and starts another program, providing the payload of the PGP message on an own file descriptor.

upgpverify is designed to work under qmail. It can handle MIME and non-MIME (traditional PGP format) messages. It handles base64 and quoted-printable.

options is a is a series of getopt or getopt_long style options. See below for more information.

tmp is a temporary directory. It must not be world writable. You must provide tmp if you want upgpverify to call another program or if the input is read from a pipe.

upgpverify since version 0.3.2 handles input from pipes by creating a temporary file.

Access Control

Access control is done in the following order:

1. upgpverify tries to verify the PGP signature. It exits with an appropriate exit code (100 or 111) if this fails. This means the signers public key has to be in the key ring used.

2. If the --rules option is used then:
   1. a.
      The signers fingerprint is checked against the rules database. Goto 2g if successful.

      This can only be checked with GPG.

   2. b.
      The signers long key id is checked against the rules database. Goto 2g if successful.

      This can only be checked with GPG.

   3. c.
      The signers short key id is checked against the rules database. Goto 2g if successful.

   4. d.
      The full user id of the key is checked against the rules database. Goto 2g if successful.

   5. e.
      The user id is parsed and all email addresses found therein are checked against the rule database. Goto 2g if successful.

   6. f.
      If the option --allow-is-default is not used then access will be denied, otherwise goto 2g.

   7. g.
      If the action of the matching rules is deny then upgpverify will exit with code 100; otherwise (if the action is accept) then the message is accepted, and a number of environment variables may be set.

Payload Handling

The payload is the signed part of the message. The client program may read the payload of the message from the file descriptor denoted by the environment variable MESSAGE_FD (the full message is available on file descriptor 0).

upgpverify removes all traces from quoted-printable and base64 from the payload if the payload isn't a structured MIME entity.

The payload starts with zero or more headers containing MIME information, followed by an empty line, followed by a text. If there's no MIME information than the payload starts with an empty line.

OPTIONS

-G, --gpg

Use GNU privacy guard to verify messages. This is the default anyway.

upgpverify expects the GPG program to reside in $PATH and to be named gpg. If this true you might use the --program option to select a suitable binary.

-2, --pgp2

Use PGP version 2.6.3 to verify messages.

upgpverify expects the PGP program to reside in $PATH and to be named pgp. If this true you might use the --program option to select a suitable binary.

-5, --pgp5

Use PGP version 5 to verify messages.

upgpverify expects the PGP signature verification program to reside in $PATH and to be named pgpv. If this true you might use the --program option to select a suitable binary.

-e, --exec=PROGRAM

Use this PROGRAM instead of the default to check the messages.

-G, --allow-key-retrieve

Allow GPG to get missing keys from a key server. GPG by default tries to retrieve missing public keys from a key server. The upgpverify default since version 0.3.2 is to disable this.

If you want to automatically retrieve keys then use this option, which is ignored for PGP2 and PGP5.

-P, --passphrase-fd=FD

This option is passed to the program used to decrypt a message. FD is a file handle, the external program will try to read a passphrase from it.

Use like this:

  | upgpverify -P 3 tmp payload_handling_program 3<secret/passphrase

where secret/passphrase is a file containing the passphrase of the key.

-p, --pubring=PUBRING

Select public key ring. PUBRING stands for a file name.

Note that PGP5 (not GPG) will read the key ring in $HOME/.pgp anyway, unless it's nonexistant.

Note that at least PGP2 has silly limitations on the length of the PGPPATH and HOME environment variables, if they are more than 50 characters long then pgp version 2 will ignore them.

-r, --rules=RULESFILE

Follow the rules compiled into RULESFILE by upgprules. These rules may specify setting environment variables or denying access from certain keys.

-A, --allow-is-default

If now rule matches then allow access anyway. The default, if this option is not used, is to deny access.

-s, --secring=SECRING

Select secret key ring. SECRING stands for a file name.

Note that PGP5 (not GPG) will read the key ring in $HOME/.pgp anyway, unless it's nonexistant.

Note that at least PGP2 has silly limitations on the length of the PGPPATH and HOME environment variables, if they are more than 50 characters long then pgp version 2 will ignore them.

-x, --allow-x-pgp-sig

-X, --require-x-pgp-sig

These options turn on handling of articles with an X-PGP-Sig header. This is a special format of PGP signed messages backwards compatible with the existing news standards which allows the signing of header fields (to guard against replay attacks with of control messages).

The --allow-x-pgp-sig turns on handling of these articles, but also handles other kinds of signatures. The --require-x-pgp-sig mode doesn't handle any other kind of signature.

-M, --max-len BYTES

Allow incoming messages up to BYTES bytes. Default is 1000000. Use a value of 0 to disable length checks.

--version

Show version information.

--help

Show a list of options or the long help on one.

The use with an argument shows the long helptext of that option, without an argument it will list all options.

--longhelp

Show longer help texts for all or one variable

The use with an argument shows the long help for this option, without arguments it shows the long description of all options.

ENVIRONMENT

upgpverify sets the following environment variables:

HEADER_FROM

This environment variable contains the from mail header. All characters with ASCII code below 32 are deleted.

No MIME handling is done on this header.

This environment variable is under the influence of a possibly malicious entity.

HEADER_SENDER

This environment variable contains the sender mail header. It's treated like HEADER_FROM, above.

Note that you might be more interested in the variables set by qmail (see the qmail-command manual page for more information).

HEADER_TO

This environment variable contains the to mail header. It's treated like HEADER_TO, above.

Note that you might be more interested in the variables set by qmail (see the qmail-command manual page for more information).

HEADER_SUBJECT

This environment variable contains the subject mail header. It's treated like HEADER_FROM, above.

HEADER_CC

This environment variable contains the CC mail header. It's treated like HEADER_FROM, above.

HEADER_REPLY_TO

This environment variable contains the Reply-To mail header. It's treated like HEADER_FROM, above.

HEADER_FOLLOWUP_TO

This environment variable contains the Followup-To mail header. It is only set if the message is a news article with X-PGP-Sig header and handling of that form of PGP signature has been turned on. It's otherwise treated like HEADER_FROM, above.

HEADER_NEWSGROUPS

This environment variable contains the Followup-To mail header. It is only set if the message is a news article with X-PGP-Sig header and handling of that form of PGP signature has been turned on. It's treated like HEADER_FROM, above.

MESSAGE_FD

The file descriptor the PGP payload may be read from.

AUTH_FINGERPRING

The fingerprint of the signer key (only available with gpg)

AUTH_KEYID

The key id of the signer key.

AUTH_LONG_KEYID

The long key id of the signer key (only available with gpg)

AUTH_USERID

The user id of the signer key.

Aside from these environment variables it's possible to set a number of further environment variables in the rules file.

EXAMPLES

Keep Out Messages From Unknown Sources

.qmail:

    |upgpverify 
        |./Maildir/

Execute Shell Commands

        | upgpverify --ring=special.pub tmpdir sh -c \
          'exec /bin/sh - <&$MESSAGE_FD'

on one line, please. It's not necessarily a sign of security to do this.

BUGS

Doesn't get fingerprint and long key id from PGP5 and PGP2. There's a way to get the fingerprint: get the short key, list the fingerprint through pgpk -ll, and parse that. I consider this ugly as hell.

THOUGHTS

• At least gpg doesn't check for write errors in a lot of cases.

• Should be able to pass unchanged (as q-p or b64) body parts to the program _if_ and only if the signed part is a multipart itself. May set $MIME to 1 and demand that people parse the payload.

  Make that an option?

AUTHOR

Uwe Ohse