Provided by: gpg-remailer_3.04.05-1build1_amd64 
NAME
gpg-remailer - forward re-encrypted/signed PGP/GPG encrypted/signed mail to a group
SYNOPSIS
gpg-remailer [OPTIONS]
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. Gpg-remailer can also be
configured so as to process clear-text e-mail.
Using gpg-remailer the list of members of a group of people who want to exchange encrypted
and authenticated e-mails (and maybe also clear-text messages) 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 (or optionally clear-text) e-mail to.
Gpg-remailer reads incoming e-mail from its standard input stream.
If the incoming e-mail is clear-text, it resends the e-mail to one or more configurable
e-mail addresses.
If the incoming e-mail is PGP/GPG encrypted (and optionally signed) it re-encrypts the
received information for every member of a configurable group, and send the re-encrypted
information to one or more configurable e-mail addresses.
By itself, gpg-remailer is not a mailing list. However, the configured recipient address
could be, e.g., a mailing list address, for further distribution of the processed e-mail.
Gpg-remailer is a remailer: it uses the message’s data, but not its headers. Having
received an e-mail it resends, rather than forwards, the received e-mail. The e-mail that
is received via gpg-remailer therefore contains a completely new set of e-mail headers.
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):
o 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
o All locations used by the gpg-remailer must be given highly restrictive
permissions. E.g., the functional accounts should set umask 077. It is the
responsibility of the user to make sure that the access rights are correctly
configured.
o 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
o 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.
o 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
o 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:
o 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.
o 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
o Also add a line containing
force-mdc
to ~/.gnupg/gpg.conf. This prevents the warning
WARNING: message was not integrity protected
o 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.
o 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.
o 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.
o 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
o 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.
o 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.
o 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.
o --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.
o --help (-h)
A short summary of the usage is displayed to the standard output after which
gpg-remailer terminates.
o --logfile=filename (-l)
Specifies the file on which gpg-remailer’s log messages are written (by default
~/etc/gpg-remailer.log).
o --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.
o --member=PGP e-mail address (-m)
The PGP-key e-mail address 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. The --member specifications can also be
used to specify a set of e-mail envelope addresses from where clear-text e-mail is
accepted, using the envelope: members and clear-text: envelope configuration file
specifications.
o --noMail
When specified no mail is sent.
o --nr=file-number (-n)
Files created by the gpg-remailer while processing incoming e-mails are kept, and
receive suffix file-number, which should be a number.
o --recipient=e-mail address (-r)
The recipient address(es) of the (re-encrypted or plain) resent 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.
These addresses may or may not be unique. If multiple identical addresses are
specified gpg-remailer will send e-mail to each of these multiply specified
addresses.
Each --recipient option should normally only define one plain e-mail address (e.g.,
recipient@domain.iso, but multiple --recipient options are also accepted. The
format of the e-mail addresses is not checked by gpg-remailer, but providing any
information in addition to or differing from a plain e-mail address may result in
gpg-remailer being unable to re-encrypt or resend e-mail messages.
In addition to plain e-mail addresses, the specification --recipient members can be
used to indicate that the re-encrypted mail must be sent to all e-mail addresses
specified using member specifications.
o --step=name
Perform the indicated step of the remailing process. Step names are:
hdrs (write the mail headers),
org (write the mail data),
dec (only for PGP encrypted e-mail: write the decrypted info),
doc (only for PGP encrypted e-mail: create the info to send),
enc (only for PGP encrypted e-mail: encrypt the info to send),
clearmail (send clear-text mail),
clearmail:address (send mail only to the provided address, ignore recipient(s)
specified otherwise). pgpmail (send pgp-encrypted mail),
pgpmail:address (send pgp-encrypted mail only to the provided address, ignore
recipient(s) specified otherwise).
Step hdrs is completely optional. Later steps depend on earlier steps. E.g., --step
doc can only be requested after having specified --step dec in a previous run.
With clear-text e-mail steps dec, doc, enc and pgpmail should not be provided.
With PGP encrypted mail step clearmail should not be provided.
o --tmp=path (-t)
The path of the directory where the temporary files are written (by default:
$HOME/tmp). This should be an absolute path.
o --umask=octalValue
By default, gpg-remailer uses umask 077 for all files it creates: only the
pseudo-user has read and write permissions. In normal circumstances there should be
no reason for changing this umask value, but if necessary the --umask option can be
used, providing an octal value, to specify an alternative umask value.
o --version (-v)
Gpg-remailer’s version number is is written to the standard output stream after
which gpg-remailer terminates.
o --x-headers (-x)
Add `X-GPG-remailer-from’ and `X-GPG-remailer-From’ headers containing,
respectively, the original sender’s From and From: headers, as well as (in
`X-GPG-remailer-envelope’ headers) all headers containing `envelope’ to the
distributed e-mail. )
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.
o 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.
o clear-text: specification (rejected)
By default, the gpg-remailer does not accept clear-text e-mail. This can explicitly
be indicated in the configuration file using the
clear-text: rejected
specification. If clear-text e-mail should be allowed specify
clear-text: accepted
It is also possible to specify the envelope addresses that are accepted for
received clear-text e-mail. If this is required, specify
clear-text: envelope
and define the accepted envelope e-mail addresses using the envelope: configuration
option.
o envelope: e-mail address
The envelope specifications are only interpreted when clear-text: envelope has been
specified. When clear-text: envelope was specified only clear-text e-mail using one
of the configured envelope addresses will be re-mailed to the configured
recipients. The special envelope specification
envelope: members
may be used to indicate that envelope addresses which are equal to the addresses
specified using member specifications are all accepted.
All envelope addresses are interpreted case-insensitively. By default (if no
envelope specification has been provided) all envelope addresses are accepted, in
which case the specification clear-text: envelope reduces to clear-text: accepted.
o 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.
o logfile: filename (etc/gpg-remailer.log)
The file on which gpg-remailer’s log messages are written.
o 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.
o member: address
Multiple members may be specified. Each member specification specifies a PGP-key
e-mail address to re-encrypt the message for. The addresses should be plain e-mail
addresses (e.g., member@domain.iso), and should not contain other elements (like
the name of the person using the address). 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. The member specifications can also be used to
specify a set of e-mail envelope addresses from where clear-text e-mail is
accepted, using the envelope: members and clear-text: envelope specifications.
o noMail: logic (false)
When specified as true no mail is sent.
o recipient: e-mail address
The recipient address(es) of the (re-encrypted or plain) resent e-mail. Multiple
recipients may be specified. These addresses may or may not be unique. If multiple
identical addresses are specified gpg-remailer will send e-mail to each of these
multiply specified addresses. Recipients should be specified using plain e-mail
addresses (e.g., destination@some.host.org). The re-encrypted mail is sent to each
recipient in turn. The specification
recipient: members
can be used to indicate that the re-encrypted mail must be sent to all e-mail
addresses specified using member specifications.
o replyTo: full address
The reply to address may be any e-mail reply-to address. The reply-to becomes 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>
This specification should be according to the requirements defined in RFC 822:
Standard for ARPA Internet Text Messages. Failing to comply with RFC 822 may result
in the e-mail sending program rejecting the e-mail that is submitted by the
gpg-remailer.
o 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’.
o 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:
o Simple encrypted messages, consisting of an encrypted e-mail body;
o Multi-part encrypted messages;
o 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
o a new line character
o two dashes followed by the boundary text
o the last boundary is followed by two dashes
o 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
Default locations are shown. Configuration options may change these locations.
o /etc/mail/aliases: defines the mail accounts used by gpg-remailer.
o etc/gpg-remailer.rc: gpg-remailer’s configuration file.
o /etc/sudoers: defines actions executed by the MTA.
o tmp/decrypted.<nr>: the decrypted original text.
o tmp/err.<nr>: a file containing errors generated when processing the original text.
The tmp/signature.<nr> may contain gog-decryption errors.
o tmp/hdrs.<nr>: the headers of the received e-mail.
o tmp/mail.<nr>: the mail sent to the recipient(s).
o 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.
o tmp/reencrypt.<nr>: the (as yet unencrypted) file to return to the the
recipient(s).
o tmp/reencrypted.<nr>: the reencrypted file to return to the the recipient(s).
o tmp/signature.<nr>: the signature found in the original text.
SEE ALSO
addgroup(1), adduser(1), chmod(1), chown(1), gpg(1), sudo(1), umask(1),
BUGS
None reported
AUTHOR
Frank B. Brokken (f.b.brokken@rug.nl).