Provided by: gpg-remailer_3.00.01-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.  )

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