Sender Rewriting Scheme
=======================

The Sender Rewriting Scheme (SRS) allows mail servers to forward emails without
breaking SPF checks. By rewriting the envelope sender to an address within the
forwarder’s domain, SRS ensures that forwarded messages pass SPF validation,
preventing them from being rejected as spoofed or unauthorized.

How SRS works in practice
~~~~~~~~~~~~~~~~~~~~~~~~~

1. ``alice@foo.example`` receives an E-Mail from ``bob@bar.example``. Both the
envelope sender as well as the ``From`` header show ``bob@bar.example``. This
results in strict SPF alignment, because ``bar.example`` is the domain used in
both the ``Return-Path`` and ``FROM`` headers.

2. ``alice@foo.example`` forwards the mail to ``charlie@moo.example`` and
uses SRS to rewrite the envelope sender to originate from the local SRS domain
(e.g. `SRS0=HHH=TT=bar.example=alice@foo.example`). The ``FROM`` header remains
unchanged. This ensures that the forwarded mail succeeds SPF checks.

3. The email reaches ``charlie@moo.example``. SPF passes because the sender
domain in the envelope has been rewritten. The mismatch between envelope sender
domain and ``FROM`` domain does however break strict SPF alignment.

Enabling SRS
~~~~~~~~~~~~

In a simple setup just enabling SRS will use your ``mailserver.systemDomain``
when rewriting the envelope sender domain.

.. code:: nix

  {
    mailserver = {
      srs = {
        enable = true;
        #domain = "srs.example.com";
      };
    };
  };
..

While you can reuse an existing email domain for SRS, it is recommended to
configure a dedicated SRS domain. This is particularly important under the
following conditions:

* Multiple unrelated mail domains are hosted on the mailserver
* The mail domain requires strict SPF alignment in its DMARC policy

Required DNS changes
~~~~~~~~~~~~~~~~~~~~

.. note::
  In the following example we assume that you want to set up a dedicated SRS
  domain. If that is not the case you already have SPF and DKIM set up for the
  system domain. If you have a DMARC record on the system domain, make sure it
  uses a relaxed SPF alignment policy (``aspf=r``).

First we set up an MX record. This is so that we can receive and route bounces
that can result from forwards.

======================== ===== ==== ======== =====================
Name (Subdomain)         TTL   Type Priority Value
======================== ===== ==== ======== =====================
srs.example.com          10800 MX   10       ``mail.example.com``
======================== ===== ==== ==============================

Next up is the SPF record on the SRS domain to allow SPF authentication.

======================== ===== ==== ===================
Name (Subdomain)         TTL   Type Value
======================== ===== ==== ===================
srs.example.com          10800 TXT  ``v=spf1 mx -all``
======================== ===== ==== ===================

Then we deploy the DKIM record with the `p=<value>` taken from
``/var/dkim/srs.example.com.mail.txt``, that appears after deploying with SRS
enabled.

=============================== ===== ==== ========================================
Name (Subdomain)                TTL   Type Value
=============================== ===== ==== ========================================
mail._domainkey.srs.example.com 10800 TXT  ``v=DKIM1; k=rsa; p=<really-long-key>``
=============================== ===== ==== ========================================

Finally we can tie this together in the DMARC record to require receivers to
verify the requested SPF/DKIM alignment.

.. note::

   The SRS domain can only support relaxed SPF alignment due to the envelope
   sender and ``FROM`` header mismatch.

======================== ===== ==== =========================================
Name (Subdomain)         TTL   Type Value
======================== ===== ==== =========================================
_dmarc.srs.example.com   10800 TXT  ``v=DMARC1; p=reject; aspf=r; adkim=s;``
======================== ===== ==== =========================================

We can safely configure a ``reject`` policy on the SRS domain, to enforce the
SPF and DKIM alignment as configured above.