gpg-remailer(1)

💌 gpg-remailer(1) — the remailer that re-encrypts your PGP/GPG mail like a ✨queen✨

okay bestie, sit down, hydrate, because this is the manual page for gpg-remailer and she is iconic. we're talking reencrypt PGP/GPG mail, forward signed/encrypted goodness to a whole group, the works. let's get into it 💅

---

🎀 NAME 🎀

gpg-remailer — forward re-encrypted/signed PGP/GPG encrypted/signed mail to a group

---

🌸 SYNOPSIS 🌸

gpg-remailer [OPTIONS]

---

✨ DESCRIPTION ✨

so here's the tea, bestie 🍵 — gpg-remailer decrypts the PGP/GPG messages it receives, verifies the signature that came with them, and then re-encrypts that e-mail for a very well defined group of recipients. and because she's flexible like that, gpg-remailer can also be configured so it processes plain clear-text e-mail too.

using gpg-remailer, the whole list of members of a group — the people who want to swap encrypted and authenticated e-mails (and maybe clear-text messages too, no judgement) — can be kept in one single location. which means the members of the group only ever have to remember one e-mail address to send their PGP/GPG signed and encrypted (or optionally clear-text) e-mail to. one address. that's it. main character energy fr fr 👑

gpg-remailer reads incoming e-mail from its standard input stream. yes, stdin. she's a pipeline girlie.

if the incoming e-mail is clear-text, she resends the e-mail to one or more configurable e-mail addresses.

if the incoming e-mail is PGP/GPG encrypted (and optionally signed), she re-encrypts the received information for every member of a configurable group, and sends the re-encrypted information to one or more configurable e-mail addresses.

now, lowkey important: by itself, gpg-remailer is not a mailing list. but the configured recipient address could totally be, like, a mailing list address, for further distribution of the processed e-mail. she's a remailer: she uses the message's data, but not its headers. having received an e-mail she resends, rather than forwards, the received e-mail. so the e-mail that arrives via gpg-remailer has a completely new set of e-mail headers. fresh fit, new vibe, no inherited baggage 💖

a configuration file as well as command line options can be used to fine-tune gpg-remailer's behavior. you get options, you get a config file, you get control.

---

💀 RETURN VALUE 💀

gpg-remailer always returns 0 to the operating system. always. why? to prevent unknown mailer error messages from showing up in the MTA's logs. she's keeping the logs calm, she's keeping the vibes immaculate. 😌

however — and this is the important part — when gpg-remailer ends prematurely, an error message is written to the standard error stream. so she exits quietly, but she does not leave you guessing. periodt.

---

🔥 REQUIREMENTS 🔥

in order to use gpg-remailer the following requirements must be met (and listen, all commands should be issued by the root user, no cap):

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

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

• all locations used by the gpg-remailer must be given highly restrictive permissions. e.g., the functional accounts should set umask 077. it is the responsibility of the user to make sure that the access rights are correctly configured. (bestie, please. lock it down. 🔒)
• consider making all functional gpg-remailer accounts members of a special group (e.g., gpg-remailer) and allow execution of /usr/sbin/gpg-remailer only my members of that group:

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

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

Runas_Alias REMAILERS = secmail

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

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

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

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

---

🦋 THE PSEUDO USER'S PGP KEY RINGS 🦋

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

su - secmail

gpg --gen-key

at the gpg --gen-key command the gpg program asks for some details. accept the defaults unless you have reason not to, but make sure you do not require a pass-phrase: press Enter twice when asked for one. (two Enters. that's the whole trick. 💅)

some additional suggestions:

• details for defining a PGP key without password:

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

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

default-key 1234ABCD

• also add a line containing

force-mdc

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

WARNING: message was not integrity protected

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

keyserver keys.gnupg.net

to ~/.gnupg/gpg.conf.

• next use gpg --search-keys, gpg --recv-keys or gpg --import (see the gpg(1) man-page for the required formats of these commands) to already add the public keys of all the members of the group who will be using gpg-remailer to the pseudo user's public key ring.
• if a group member exists who has signed the GPG/PGP keys of all other members, then consider to trust this member fully, to prevent warnings resulting from using untrusted keys.
• once the gpg-remailer's GPG key pair has been created, provide the remailer's public key to the members of the group. these members should import the public key and they should be advised to sign the remailer's public key to prevent warnings about using an unverified public key. the remailer's public key can be be exported to file using

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

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

gpg --import secmail.pub

• when a new member is added to the group he/she should add the remailer's public key to his/her public key ring and provide his/her public key for import into the functional account's public key ring. (new member, new keys, new era. welcome to the group chat 🫶)
• gpg-remailer requires the existence of a configuration file and of a directory to store its temporary files in. see the section CONFIGURATION FILE below.
• having prepared the pseudo user's PGP key rings, the command exit takes you back to the root user's session.

---

and that's part 1 bestie, we are SO not done yet — more is coming 🌈

✨ OPTIONS ✨

okay bestie, this is the part where we get into the knobs and switches 💅 if a single-letter option exists, it's chillin' in parentheses right after its long-option twin. and fr fr, a single-letter option needs an argument exactly when its long version does — same energy, no exceptions.

• --debug (-d) — turn this on and debug messages get logged to the log-file (peep below for that). also, when you use it, the files gpg-remailer wrote do not get removed after it's done processing an incoming e-mail. they just stay there. no cleanup, no cap 🫶
• --help (-h) — shows a short lil summary of the usage to standard output, and then gpg-remailer dips out. bye 👋
• --logfile=filename (-l) — tells you which file gpg-remailer writes its log messages to. default is ~/etc/gpg-remailer.log in case you were wondering 💖
• --loglevel=level (-L) — how chatty do we want the logs? here's the tea:
  • LogLevel 0 gives you extensive debug output plus all the other log messages.
  • LogLevel 1 logs the executed commands and the default messages.
  • LogLevel 2 logs the default messages — that's the characteristics of incoming and outgoing e-mail — and this one is the default.
  • higher levels will suppress logging entirely. silence. 🤫
• --member=PGP e-mail address (-m) — the PGP-key e-mail address to re-encrypt the message for. this overrides the member(s) listed in the configuration file. you can specify it multiple times if you need multiple members on the command line. with each --member option, only provide one e-mail address (like member@domain.iso — and yes, that format is not checked by gpg-remailer, but if you don't comply it might just fail to re-encrypt or e-mail messages, so like... comply 🥲). also, the --member specifications can 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. slay.
• --noMail — when specified, no mail is sent. that's it. that's the whole vibe. 📭
• --nr=file-number (-n) — the files gpg-remailer creates while processing incoming e-mails get kept, and they receive the suffix file-number, which should be a number. 🔢
• --recipient=e-mail address (-r) — the recipient address(es) of the (re-encrypted or plain) resent e-mail. this overrides the recipient(s) listed in the configuration file. as with the --members option, you can specify multiple recipients by providing multiple --recipient options. these addresses may or may not be unique — and if you specify multiple identical addresses, gpg-remailer will send e-mail to each of those multiply specified addresses. yes, really, all of them 💌

each --recipient option should normally only define one plain e-mail address (like 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 info 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. so keep it plain, bestie 😭

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.

• --step=name — perform the indicated step of the remailing process. the 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, like a little bonus. later steps depend on earlier steps — e.g., --step doc can only be requested after having specified --step dec in a previous run. the pipeline is real 🧚

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.

• --tmp=path (-t) — the path of the directory where the temporary files are written (by default: $HOME/tmp). this should be an absolute path. ⚠️ absolute, bestie, don't play.
• --umask=octalValue — by default, gpg-remailer uses umask 077 for all files it creates: only the pseudo-user has read and write permissions. under normal circumstances there should be no reason to change this umask value, but if necessary the --umask option can be used, providing an octal value, to specify an alternative umask value. 🔐
• --version (-v) — gpg-remailer's version number is written to the standard output stream, after which gpg-remailer terminates. iconic behavior honestly 👑
• --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. headers on headers on headers 💅

🌸 CONFGURATION FILE 🌸

okay so bestie, the default configuration file is ~/etc/gpg-remailer.rc, chillin' under the pseudo user's home directory 💖. Wanna move it somewhere else? There's a program option for that, iykyk.

Empty lines? Ignored, literally gone. And anything at or beyond a # character is comment territory — also ignored 🎀.

Every directive in the configuration file obeys this exact pattern:

directive: value

A line can hold at most one directive, but white space is totally fine (including a comment hanging off the end of the line, slay). Some directives can be specified multiple times; for the rest, the first occurrence is the one that counts. All directives are interpreted case insensitively, but their values are used exactly as specified. So like, DeBUG: true is just as good as debug: true — but debug: TRUE is not recognized 🙈. And non-empty lines that don't start with a recognized directive? Silently ignored. No drama, no error message, nothing.

Here's the full list of supported directives (default values are shown between parentheses — when none is specified, there's no default). And when equivalent command line options are used, those overrule the configuration file specifications. Periodt. 👑

• debug: logic (false) — when logic is specified as true, debug messages get 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.
• clear-text: specification (rejected) — by default, the gpg-remailer does not accept clear-text e-mail. You can say that out loud in the config file using clear-text: rejected. If clear-text e-mail should be allowed, specify clear-text: accepted. And you can also specify the envelope addresses that are accepted for received clear-text e-mail — if that's the vibe you want, specify clear-text: envelope and then define the accepted envelope e-mail addresses using the envelope: configuration option.
• envelope: e-mail address — these 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.
• keepFiles: nr — when a number is specified, all files written by gpg-remailer use the specified number and are not removed when gpg-remailer terminates. When this option is not specified, the files receive a random numeric extension, resulting in the creation of new, as yet non-existing *.<nr> files.
• logfile: filename (etc/gpg-remailer.log) — the file on which gpg-remailer's log messages are written.
• loglevel: value (2) —
  • LogLevel 0 provides extensive debug output as well as all other logmessages;
  • LogLevel 1 logs the executed commands and the default messages;
  • LogLevel 2 logs the default messages (characteristics of incoming and outgoing e-mail);
  • With higher levels, logging is suppressed.
• 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.
• noMail: logic (false) — when specified as true, no mail is sent.
• 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.
• 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 💀.

• 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 good signature.
• tmp directory (tmp/) — the directory into which gpg-remailer writes its temporary files. )

✨ FORMATS ✨

okay so bestie, PGP/GPG in e-mail is like, established technology, but the e-mail itself can be shaped all kinds of ways. Right now gpg-remailer recognizes these formats:

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

Below is the tea on what's actually inside PGP encrypted and decrypted files. 💅

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

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

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

----------------------------------------------------------------------
    mail headers

--+QahgC5+KEYLbs62
Content-Type: application/pgp-encrypted
Content-Disposition: attachment

Version: 1

--+QahgC5+KEYLbs62
Content-Type: application/octet-stream
Content-Disposition: inline; filename="msg.asc"

-----BEGIN PGP MESSAGE-----
...
-----END PGP MESSAGE-----

--+QahgC5+KEYLbs62--
----------------------------------------------------------------------

Note that boundaries consist of

• a new line character
• two dashes followed by the boundary text
• the last boundary is followed by two dashes
• a new line character

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

💌 Simple Encrypted Messages.

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

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

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

🧩 Multi-part Encrypted Messages.

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

----------------------------------------------------------------------
Content-Type: multipart/mixed; boundary="f+W+jCU1fRNres8c"
Content-Disposition: inline

--f+W+jCU1fRNres8c
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable

Text of the first attachment

--f+W+jCU1fRNres8c
Content-Type: application/pdf
Content-Disposition: attachment; filename="attachment.pdf"
Content-Transfer-Encoding: base64

text of the attachment.pdf in base64 encoding

--f+W+jCU1fRNres8c--
----------------------------------------------------------------------

Multiple attachments might follow in the same way. slay. 🎀

🖊️ 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. iykyk. 🔥

---

📁 FILES 📁

Default locations are shown. Configuration options may change these locations. (so like, don't come for me if yours are different, bestie 💜)

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

(iconic behaviour tbh, no bugs on the record ✨)

---

👑 AUTHOR 👑

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

---

okay that's a wrap bestie 🫶 this was gpg-remailer.3.04.07, dated 2006-2022, and yes the page is literally called gpg-remailer(1) 💖 go forth and remail responsibly, mwah 💅🌸