gpg-remailer

gpg-remailer._CurVers_.tar.gz

_CurYrs_

gpg-remailer(1)

gpg-remailer._CurVers_.tar.gz gpg-remailer - reencrypt PGP/GPG maill

_CurYrs_

NAME

SYNOPSIS

DESCRIPTION

Gpg-remailer decrypts received PGP/GPG messages, verifies the received signature, and re-encrypts the e-mail for a well defined group of recipients.

Using gpg-remailer the list of members of a group of people who want to exchange encrypted and authenticated e-mails can be maintained at one location, allowing the members of the group to specify just one e-mail address to send PGP/GPG signed and encrypted e-mail to.

Gpg-remailer reads incoming e-mail from its standard input stream and sends the processed input as a signed and encrypted PGP/GPG e-mail, encrypted for every member of the group, to one or more e-mail addresses. The address the signed and encrypted mail is sent to could, e.g., be a mailing list address.

A configuration file as well as command line options can be used to fine-tune gpg-remailer's behavior.

RETURN VALUE

Gpg-remailer always returns 0 to the operating system to prevent unknown mailer error messages in the MTA's logs. However, when gpg-remailer ends prematurely an error message is written to the standard error stream.

REQUIREMENTS

In order to use gpg-remailer the following requirements must be met (all commands should be issued by the root user):

• Since multiple groups may use gpg-remailer it is advised to define functional accounts handling e-mail to be processed by gpg-remailer. A functional account secmail can be defined using a command like this:

  
      adduser --home /var/lib/secmail --disabled-password secmail
      
  

• All locations used by the gpg-remailer must be given highly restrictive permissions. E.g., use chmod -R og-rwx /var/lib/secmail for the functional accounts. Gpg-remailer will not process e-mail unless these permissions were set.

• Consider making all functional gpg-remailer accounts members of a special group (e.g., gpg-remailer) and allow execution of /usr/sbin/gpg-remailer only my members of that group:

  
      addgroup gpg-remailer
      adduser secmail gpg-remailer
      chown root.gpg-remailer /usr/sbin/gpg-remailer
      chmod o-rx /usr/bin/gpg-remailer
      
  

• To allow the functional account to handle incoming e-mail sudo(1) can be used. In the file /etc/sudoers the following lines can be entered (REMAILERS can be given a comma separated list of functional account names, mailhost.org should be replaced by the name of the host handling incoming e-mail):

  
  Runas_Alias REMAILERS = secmail
  
  mail    mailhost.org=(REMAILERS) NOPASSWD:  /usr/sbin/gpg-remailer
      
  

  E.g., if gpg-remailer runs on a computer named remailer.mydomain.nl which may receive incoming e-mails, then specify remailer.mydomain.nl for mailhost.org.

• An e-mail address must be defined to where the mail to reencrypt must be sent to. This e-mail address must be known by the members of the group who want to use the gpg-remailer. Such an account could be, e.g., secmail@mailhost.org, appearing as a defined mail address in, e.g., /etc/mail/aliases. The address for this example would be entered in the /etc/mail/aliases file (some installations use /etc/aliases) in this way:

  
      secmail:         "|sudo -u secmail /usr/sbin/gpg-remailer"
      
  

THE PSEUDO USER'S PGP KEY RINGS

• The functional account must be provided with a GPG/PGP keypair. Its public key must be distributed over the people who are allowed to send mail to the gpg-remailer (which may be the world if the public key is published at a PGP key server). Since the gpg-remailer must be able to act on its own, the secret key must not require a passphrase. The key can be created as follows (after the initial command, which is specified by root, the remaining commands through the final exit command at the end of this section are executed by the pseudo-user secmail):

  
      su - secmail
  
      gpg --gen-key
          
  

  At the gpg --gen-key command the gpg program asks for some details. Accept the defaults unless you have reason not to, but make sure you do not require a pass-phrase: press Enter twice when asked for one.

Some additional suggestions:

• Details for defining a PGP key without password:

  define default RSA key, size 2048, never to expire
  real name: secmail gpg-remailer functional account
  email address: secmail@mailhost.org
  No passphrase required: press Enter twice.
  

• Specify the key-id of the just created gpg-key as the default key in the file ~/.gnupg/gpg.conf (or ~/.gnupg/options, whichever is used). E.g.,

  
  default-key 1234ABCD
      
  

• Also add a line containing

  
  force-mdc
      
  

  to ~/.gnupg/gpg.conf. This prevents the warning

  
  WARNING: message was not integrity protected
      
  

• If you want to allow non-group members to send e-mail to the gpg-remailer consider adding a key server specification to ~/.gnupg/gpg.conf as well, to allow the automatic retrieval of missing public keys. E.g., add a line like

  
  keyserver keys.gnupg.net
      
  

  to ~/.gnupg/gpg.conf.

• Next use gpg --search-keys, gpg --recv-keys or gpg --import (see the gpg(1) man-page for the required formats of these commands) to already add the public keys of all the members of the group who will be using gpg-remailer to the pseudo user's public key ring.

• If a group member exists who has signed the GPG/PGP keys of all other members, then consider to trust this member fully, to prevent warnings resulting from using untrusted keys.

• Once the gpg-remailer's GPG key pair has been created, provide the remailer's public key to the members of the group. These members should import the public key and they should be advised to sign the remailer's public key to prevent warnings about using an unverified public key. The remailer's public key can be be exported to file using

  
      gpg --armor --export secmail > secmail.pub
          
  

  and the members of the group can import the remailer's public key using:

  
      gpg --import secmail.pub
          
  

• When a new member is added to the group he/she should add the remailer's public key to his/her public key ring and provide his/her public key for import into the functional account's public key ring.

• Gpg-remailer requires the existence of a configuration file and of a directory to store its temporary files in. See the section CONFIGURATION FILE below.

• Having prepared the pseudo user's PGP key rings, the command exit takes you back to the root user's session.

OPTIONS

If available, single letter options are listed between parentheses following their associated long-option variants. Single letter options require arguments if their associated long options require arguments as well.

• --debug (-d)
  When specified, debug messages are logged to the log-file (see below). When this option is specified the files written by gpg-remailer are not removed after gpg-remailer has processed an incoming e-mail.

• --help (-h)
  A short summary of the usage is displayed to the standard output after which gpg-remailer terminates.

• --logfile=filename (-l)
  Specifies the file on which gpg-remailer's log messages are written (by default ~/etc/gpg-remailer.log).

• --loglevel=level (-L)
  LogLevel 0 provides extensive debug output as well as all other logmessages;
  LogLevel 1 logs the executed commands and the default messages;
  LogLevel 2 logs the default messages (characteristics of incoming and outgoing e-mail) (default);
  Higher levels will suppress logging.

• --member=PGP e-mail address (-m)
  The PGP-key e-mail address or PGP-key ID to re-encrypt the message for. Overrides the member(s) listed in the configuration file. This option may be specified multiple times when multiple members must be specified on the command line. With each --member option only provide one e-mail address (e.g., member@domain.iso. This format is not checked by gpg-remailer, but a failure to comply may result in gpg-remailer being unable to re-encrypt or e-mail messages.

• --noMail
  When specified no mail is sent.

• --recipient=e-mail address (-r)
  The recipient of the e-mail. Overrides the recipient(s) listed in the configuration file. As with the --members option, multiple recipients may be specified by providing multiple --recipient options. each --recipient option should only provide one e-mail address (e.g., recipient@domain.iso. This format is not checked by gpg-remailer, but a failure to comply may result in gpg-remailer being unable to re-encrypt or e-mail messages.

• --relax
  Tests for proper permissions of home directory and files are not performed, instead a warning is issued in the log-file.

• --step=name
  Perform the indicated step of the remailing process. Step names are:
  org (info from mail),
  dec (decrypt info),
  doc (create doc to send),
  enc (encrypt doc),
  mail (send mail),
  mail:address (send mail only to the provided address, ignore recipient(s) specified otherwise).

  Later steps depend on earlier steps. E.g., --step doc can only be requested after having specified --step dec in a previous run.

• --version (-v)
  Gpg-remailer's version number is is written to the standard output stream after which gpg-remailer terminates. )

  CONFGURATION FILE

  The default configuration file is ~/etc/gpg-remailer.rc under the pseudo user's home directory. Its path may be altered using a program option.

  Empty lines are ignored. Information at and beyond #-characters is interpreted as comment and is ignored as well.

  All directives in the configuration file obey the pattern

  
      directive: value
      
  

  A line may at most contain one directive, but white space (including comment at the end of the line) is OK. Several directives may be specified multiple times; otherwise the first occurrence of a directive is used. All directives are interpreted case insensitively, but their values are used as specified. E.g., DeBUG: true is as good as debug: true, but debug: TRUE is not recognized. Non-empty lines not starting with a recognized directive are silently ignored.

  The following directives are supported (default values are shown between parentheses; when none is specified there is no default). When equivalent command line options are used then they overrule the configuration file specifications.

  • debug: logic (false)
    When logic is specified as true debug messages will be logged to the log-file (see below). Command line options: --debug, -d. When this option is specified the files written by gpg-remailer will not be removed when gpg-remailer terminates.

  • keepFiles: nr
    When a number is specified all files written by gpg-remailer use the specified number and are not removed when gpg-remailer terminates. When this option is not specified the files receive a random numeric extension resulting in the creation of new, as yet non-existing *.<nr> files.

  • logfile: filename (etc/gpg-remailer.log)
    The file on which gpg-remailer's log messages are written.

  • loglevel: value (2)
    LogLevel 0 provides extensive debug output as well as all other logmessages;
    LogLevel 1 logs the executed commands and the default messages;
    LogLevel 2 logs the default messages (characteristics of incoming and outgoing e-mail);
    With higher levels logging is suppressed.

  • noMail: logic (false)
    When specified as true no mail is sent.

  • recipient: e-mail address
    Multiple recipients may be specified. Recipients should be specified as a plain e-mail address (e.g., destination@some.host.org). The re-encrypted mail is sent to each recipient in turn.

  • replyTo: full address
    The reply to address may be any e-mail reply-to address. The reply-to will be the default reply address for the recipient receiving gpg-remailer's e-mail message. Quotes and double quotes are removed from the reply to address. A reply-to specification could be, e.g.,

    
        SECMAIL signed AND encrypted <secmail@mailhost.org>
            
    

  • signature: requirement (required)
    This option is used to control signature checking. Recognized values are:
    none (or not specified): no signature checking is performed;
    required: a PGP signature must have been provided;
    good: the PGP signature must be recognized as a a `good signature'.

  • tmp directory (tmp/)
    The directory into which gpg-remailer writes its temporary files.
  )

  FORMATS

  Although using PGP/GPG in e-mail is established technology, various formats of the e-mail are possible. Currently gpg-remailer recognizes the following formats:

  • Simple encrypted messages, consisting of an encrypted e-mail body;
  • Multi-part encrypted messages;
  • Encrypted messages containing detached signatures.

  Below a description is given of the actual contents of PGP encrypted en decrypted files.

  All PGP encrypted e-mail shows the following headers (the boundary values will differ over different e-mail messages):

  
  Content-Type: multipart/encrypted; protocol="application/pgp-encrypted";
          boundary="+QahgC5+KEYLbs62"
  Content-Disposition: inline
          
  

  All PGP encrypted e-mail shows the following organization (the lines are used to separate the e-mail organization from the text of this man-page and are not actually present in the e-mail or in the decrypted information; empty lines, where shown, are required):

  
  ----------------------------------------------------------------------
      mail headers
  
  --+QahgC5+KEYLbs62
  Content-Type: application/pgp-encrypted
  Content-Disposition: attachment
  
  Version: 1
  
  --+QahgC5+KEYLbs62
  Content-Type: application/octet-stream
  Content-Disposition: inline; filename="msg.asc"
  
  -----BEGIN PGP MESSAGE-----
  ...
  -----END PGP MESSAGE-----
  
  --+QahgC5+KEYLbs62--
  ----------------------------------------------------------------------
          
  

  Note that boundaries consist of
  • a new line character
  • two dashes followed by the boundary text
  • the last boundary is followed by two dashes
  • a new line character

  The various PGP encrypted e-mail formats differ in the way they organize the decrypted information.

  Simple Encrypted Messages.

  During decryption the signature is verified, and the result of the verification is written to the standard error stream. The decrypted message itself contains but one message, organized as follows:

  
  ----------------------------------------------------------------------
  Content-Type: text/plain; charset=us-ascii
  Content-Disposition: inline
  Content-Transfer-Encoding: quoted-printable
  
  decrypted text of the message
  ----------------------------------------------------------------------
          
  

  Multi-part Encrypted Messages.

  During decryption the signature is verified, and the result of the verification is written to the standard error stream. The decrypted message itself contains multiple messages, organized as follows:

  
  ----------------------------------------------------------------------
  Content-Type: multipart/mixed; boundary="f+W+jCU1fRNres8c"
  Content-Disposition: inline
  
  --f+W+jCU1fRNres8c
  Content-Type: text/plain; charset=us-ascii
  Content-Disposition: inline
  Content-Transfer-Encoding: quoted-printable
  
  Text of the first attachment
  
  --f+W+jCU1fRNres8c
  Content-Type: application/pdf
  Content-Disposition: attachment; filename="attachment.pdf"
  Content-Transfer-Encoding: base64
  
  text of the attachment.pdf in base64 encoding
  
  --f+W+jCU1fRNres8c--
  ----------------------------------------------------------------------
          
  

  Multiple attachments might follow in the same way.

  Encrypted Messages Containing Detached Signatures.

  During decryption the signature is not verified (but the recipient(s) is (are) shown) and the decrypted file is organized as follows:

  
  ----------------------------------------------------------------------
  Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature";
          boundary="=-TNwuMvq+TfajHhvqBuO7"
  
  --=-TNwuMvq+TfajHhvqBuO7
  Content-Type: text/plain
  Content-Transfer-Encoding: quoted-printable
  
  Text of the message
  
  --=-TNwuMvq+TfajHhvqBuO7
  Content-Type: application/pgp-signature; name=signature.asc
  Content-Description: This is a digitally signed message part
  
  -----BEGIN PGP SIGNATURE-----
  ... signature text
  -----END PGP SIGNATURE-----
  
  --=-TNwuMvq+TfajHhvqBuO7--
  ----------------------------------------------------------------------
          
  

  The last part represents the detached signature, The contents section must be separated from the decrypted file (named, e.g., decrypted) (creating, e.g., the file contents). That latter file's signature may then be verified using the command

  
      gpg --verify decrypted contents
          
  

  resulting in the signature verification written to the standard error (as usual). The contents start immediately following the first boundary, and continues up to, but not including, the new line just before the next boundary.

FILES

• /etc/mail/aliases: defines the mail accounts used by gpg-remailer.
• tmp/err.<nr>: a file containing errors generated when processing the original text. The tmp/signature.<nr> may contain gog-decryption errors.
• tmp/mail.<nr>: the mail sent to the recipient(s).
• tmp/reencrypt.<nr>: the (as yet unencrypted) file to return to the the recipient(s).
• tmp/reencrypted.<nr>: the reencrypted file to return to the the recipient(s).
• etc/gpg-remailer.rc: gpg-remailer's configuration file.
• /etc/sudoers: defines actions executed by the MTA.
• tmp/decrypted.<nr>: the decrypted original text.
• tmp/org.<nr>: a copy of the received e-mail. When random file numbers are used a org.<nr> file will not overwrite an existing org.* file.
• tmp/signature.<nr>: the signature found in the original text.

SEE ALSO

addgroup(1), adduser(1), chmod(1), chown(1), gpg(1), sudo(1),

BUGS

None reported

AUTHOR

Frank B. Brokken (f.b.brokken@rug.nl).