Provided by: gpg-remailer_3.04.07-1_amd64 bug

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