NOUSERMACRO(recipient member)

includefile(../../release.yo)

TYPEOUT(USING: VERSION = _CurVers_, YEARS: _CurYrs_)

htmlbodyopt(text)(#27408B)
htmlbodyopt(bgcolor)(#FFFAF0)
whenhtml(mailto(Frank B. Brokken: f.b.brokken@rug.nl))

DEFINEMACRO(lsoption)(3)(\
    bf(--ARG1)=tt(ARG3) (bf(-ARG2))\
)
DEFINEMACRO(laoption)(2)(\
    bf(--ARG1)=tt(ARG2)\
)
DEFINEMACRO(loption)(1)(\
    bf(--ARG1)\
)
DEFINEMACRO(soption)(1)(\
    bf(-ARG1)\
)


DELETEMACRO(tt)
DEFINEMACRO(tt)(1)(em(ARG1))

COMMENT( man-request, section, date, distribution file, general name)
manpage(gpg-remailer)(1)(_CurYrs_)(gpg-remailer._CurVers_.tar.gz)
        (gpg-remailer - reencrypt PGP/GPG maill)

COMMENT( man-request, larger title )
manpagename(gpg-remailer)
    (forward re-encrypted/signed PGP/GPG encrypted/signed mail to a group)

COMMENT( all other: add after () )
manpagesynopsis()
       bf(gpg-remailer) [OPTIONS] 

manpagedescription()

    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 em(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. 

manpagesection(RETURN VALUE)

    Gpg-remailer always returns 0 to the operating system to prevent
tt(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.

manpagesection(REQUIREMENTS)

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

    itemization(
    it() 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 tt(secmail) can be defined using a command like this:
    verb(
    adduser --home /var/lib/secmail --disabled-password secmail
    )

    it() All locations used by the gpg-remailer must be given highly
restrictive permissions. E.g., the functional accounts should set tt(umask
077). It is the responsibility of the user to make sure that the access rights
are correctly configured.

    it() Consider making all functional gpg-remailer accounts members of a
special group (e.g., tt(gpg-remailer)) and allow execution of
tt(/usr/sbin/gpg-remailer) only my members of that group:
        verb(
    addgroup gpg-remailer
    adduser secmail gpg-remailer
    chown root.gpg-remailer /usr/sbin/gpg-remailer
    chmod o-rx /usr/bin/gpg-remailer
    )    

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

mail    mailhost.org=(REMAILERS) NOPASSWD:  /usr/sbin/gpg-remailer
    )
    E.g., if gpg-remailer runs on a computer named tt(remailer.mydomain.nl)
which may receive incoming e-mails, then specify tt(remailer.mydomain.nl) for
tt(mailhost.org).

    it() 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.,
tt(secmail@mailhost.org), appearing as a defined mail address in, e.g.,
tt(/etc/mail/aliases). The address for this example would be entered in the
tt(/etc/mail/aliases) file (some installations use tt(/etc/aliases)) in this
way:
    verb(
    secmail:         "|sudo -u secmail /usr/sbin/gpg-remailer"
    )
        )

manpagesection(THE PSEUDO USER'S PGP KEY RINGS)

    itemization(
    it() 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 tt(root), the remaining
commands through the final tt(exit) command at the end of this section are
executed by the pseudo-user tt(secmail)):
        verb(
    su - secmail

    gpg --gen-key
        )
    At the tt(gpg --gen-key) command the tt(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 tt(Enter) twice when asked for one.
    )

bf(Some additional suggestions:)

    itemization(
    it() Details for defining a PGP key without password: 

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

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

    it() Also add a line containing
    verb(
force-mdc
    ) 
    to tt(~/.gnupg/gpg.conf).  This prevents the warning
    verb(
WARNING: message was not integrity protected
    )  

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

    it() Next use tt(gpg --search-keys), tt(gpg --recv-keys) or tt(gpg
--import) (see the bf(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.

    it() 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.

    it() 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
        verb(
    gpg --armor --export secmail > secmail.pub
        )
    and the members of the group can import the remailer's public key using:
        verb(
    gpg --import secmail.pub
        )

    it() 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.

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

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

manpageoptions()

    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.
    itemization(

    it() loption(debug) (soption(d)) nl()
        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.

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

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

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

    it() lsoption(member)(m)(PGP e-mail address) nl()
        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 tt(--member) option only provide one e-mail address (e.g.,
tt(member@domain.iso). This format is not checked by bf(gpg-remailer), but a
failure to comply may result in bf(gpg-remailer) being unable to re-encrypt or
e-mail messages. The tt(--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 tt(envelope: members) and tt(clear-text: envelope) configuration
file specifications.

    it() loption(noMail)nl()
        When specified no mail is sent.

    it() lsoption(nr)(n)(file-number) nl()
        Files created by the gpg-remailer while processing incoming e-mails
are kept, and receive suffix tt(file-number), which should be a number.

    it() lsoption(recipient)(r)(e-mail address) nl()
        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 tt(--members) option, multiple recipients may be specified by providing
multiple tt(--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 tt(--recipient) option should normally only define one plain e-mail
address (e.g., tt(recipient@domain.iso), but multiple tt(--recipient) options
are also accepted. The format of the e-mail addresses is not checked by
bf(gpg-remailer), but providing any information in addition to or differing
from a plain e-mail address may result in bf(gpg-remailer) being unable to
re-encrypt or resend e-mail messages. 

    In addition to plain e-mail addresses, the specification tt(--recipient
members) can be used to indicate that the re-encrypted mail must be sent to
all e-mail addresses specified using tt(member) specifications.

    it() laoption(step)(name)nl()
        Perform the indicated step of the remailing process. Step names
are:nl()

        tt(hdrs) (write the mail headers),nl()
        tt(org) (write the mail data),nl()
        tt(dec) (only for PGP encrypted e-mail: write the decrypted info),nl()
        tt(doc) (only for PGP encrypted e-mail: create the info to send),nl()
        tt(enc) (only for PGP encrypted e-mail: encrypt the info to send),nl()
        tt(clearmail) (send clear-text mail),nl()
        tt(clearmail:address) (send mail only to the provided address, ignore
                   recipient(s) specified otherwise).
        tt(pgpmail) (send pgp-encrypted mail),nl()
        tt(pgpmail:address) (send pgp-encrypted mail only to the provided
                address, ignore recipient(s) specified otherwise).nl()

    Step tt(hdrs) is completely optional. Later steps depend on earlier
steps. E.g., tt(--step doc) can only be requested after having specified
tt(--step dec) in a previous run. 

    With clear-text e-mail steps tt(dec, doc, enc) and tt(pgpmail) should not
be provided.

    With PGP encrypted mail step tt(clearmail) should not be provided.

    it() lsoption(tmp)(t)(path) nl()
        The path of the directory where the temporary files are written (by
default: tt($HOME/tmp)). This should be an absolute path.

    it() laoption(umask)(octalValue)nl()
       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
tt(--umask) option can be used, providing an octal value, to specify an
alternative umask value.

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

    it() loption(x-headers) (soption(x))nl()
       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.
    )

manpagesection(CONFGURATION FILE)

The default configuration file is tt(~/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 tt(#)-characters is
interpreted as comment and is ignored as well.

All directives in the configuration file obey the pattern 
    verb(
    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 em(case insensitively), but their values are used as
specified. E.g., tt(DeBUG: true) is as good as tt(debug: true), but tt(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.

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

    it() bf(clear-text:) tt(specification) (rejected)nl()
        By default, the gpg-remailer does not accept clear-text e-mail. This
can explicitly be indicated in the configuration file using the

    tt(clear-text: rejected)

    specification. If clear-text e-mail should be allowed specify

    tt(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

    tt(clear-text: envelope)

    and define the accepted envelope e-mail addresses using the tt(envelope:)
configuration option. 

    it() bf(envelope:) tt(e-mail address) nl()
        The tt(envelope) specifications are only interpreted when
tt(clear-text: envelope) has been specified. When tt(clear-text: envelope) was
specified only clear-text e-mail using one of the configured tt(envelope)
addresses will be re-mailed to the configured recipients. The special envelope
specification
    
    tt(envelope: members) 

    may be used to indicate that envelope addresses which are equal to the
addresses specified using tt(member) specifications are all accepted.

    All envelope addresses are interpreted case-insensitively. By default (if
no tt(envelope) specification has been provided) all envelope addresses are
accepted, in which case the specification tt(clear-text: envelope) reduces to
tt(clear-text: accepted).

    it() bf(keepFiles:) tt(nr) nl()
        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 tt(*.<nr>) files. 

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

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

    it() bf(member:) tt(address) nl()
        Multiple members may be specified. Each tt(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., tt(member@domain.iso)), and
should not contain other elements (like the name of the person using the
address). This format is not checked by bf(gpg-remailer), but a failure to
comply may result in bf(gpg-remailer) being unable to re-encrypt or e-mail
messages. The tt(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
tt(envelope: members) and tt(clear-text: envelope) specifications.

    it() bf(noMail:) tt(logic) (false)nl()
        When specified as tt(true) no mail is sent.

    it() bf(recipient:) tt(e-mail address) nl()
        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.,
tt(destination@some.host.org)). The re-encrypted mail is sent to each
recipient in turn. The specification
    
    tt(recipient: members)

    can be used to indicate that the re-encrypted mail must be sent to all
e-mail addresses specified using tt(member) specifications.

    it() bf(replyTo:) tt(full address) nl()
        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.,
        verb(
    SECMAIL signed AND encrypted <secmail@mailhost.org>
        )
        This specification should be according to the requirements defined in
RFC 822: em(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.

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

    it() bf(tmp) tt(directory) (tmp/)nl()
        The directory into which gpg-remailer writes its temporary files.
    )
)
                    
manpagesection(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:
    itemization(
    it() Simple encrypted messages, consisting of an encrypted e-mail body;
    it() Multi-part encrypted messages;
    it() 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):
        verb(
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):
        verb(
----------------------------------------------------------------------
    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 
    itemization(
    it() a new line character
    it() two dashes followed by the boundary text
    it() the last boundary is followed by two dashes
    it() a new line character
    )

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


bf(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:
        verb(
----------------------------------------------------------------------
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable

decrypted text of the message
----------------------------------------------------------------------
        )


bf(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:
        verb(
----------------------------------------------------------------------
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.

bf(Encrypted Messages Containing Detached Signatures.)

   
    During decryption the signature is em(not) verified (but the 
recipient(s) is (are) shown) and the decrypted file is organized as follows:
        verb(
----------------------------------------------------------------------
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., tt(decrypted)) (creating,
e.g., the file tt(contents)). That latter file's signature may then be
verified using the command
        verb(
    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.
    )

COMMENT(
manpagesection(EXAMPLES)

    To do
END)

manpagefiles()
    Default locations are shown. Configuration options may change these
locations. 
    itemization(
    it() tt(/etc/mail/aliases): defines the mail accounts used by
gpg-remailer.
    it() tt(etc/gpg-remailer.rc): gpg-remailer's configuration file.
    it() tt(/etc/sudoers): defines actions executed by the MTA.

    it() tt(tmp/decrypted.<nr>): the decrypted original text.
    it() tt(tmp/err.<nr>): a file containing errors generated when processing 
the original text. The tt(tmp/signature.<nr>) may contain gog-decryption
errors. 
    it() tt(tmp/hdrs.<nr>): the headers of the received e-mail.
    it() tt(tmp/mail.<nr>): the mail sent to the recipient(s).
    it() tt(tmp/org.<nr>): a copy of the received e-mail. When random file
numbers are used a tt(org.<nr>) file will not overwrite an existing tt(org.*)
file. 
    it() tt(tmp/reencrypt.<nr>): the (as yet unencrypted) file to return to
the the recipient(s).
    it() tt(tmp/reencrypted.<nr>): the reencrypted file to return to
the the recipient(s).
    it() tt(tmp/signature.<nr>): the signature found in the original text.
    )

manpageseealso()

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

manpagebugs()

    None reported

manpageauthor()

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